Affected People

Get refugees data

get

UNHCR's Refugee data provides information about displaced people in a crisis. See the more detailed technical HDX HAPI documentation, and the original HDX source website.

Query parameters

app_identifierstring · max: 512 · nullableRequired

base64 encoded application name and email, as in base64("app_name:email"). This value can also be passed in the X-HDX-HAPI-APP-IDENTIFIER header. See the encoded_app_identifier endpoint.

population_groupstring · enum · max: 32 · nullableOptional

Filter the response by the population group, available values are described here.

Possible values:

population_mininteger · nullableOptional

Filter the response by a lower bound for the population.

population_maxinteger · nullableOptional

Filter the response by a upper bound for the population.

genderstring · enum · max: 3 · nullableOptional

Filter the response by the gender, available values are described here.

Possible values:

age_rangestring · max: 32 · nullableOptional

Filter the response by the age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data.

origin_location_codestring · max: 128 · nullableOptional

Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the location endpoint for details.

origin_location_namestring · max: 512 · nullableOptional

Filter the response by a location (typically a country). The location names are based on the "short name" from the UN M49 Standard. See the location endpoint for details.

origin_has_hrpboolean · nullableOptional

Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.

origin_in_ghoboolean · nullableOptional

Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the Global Humanitarian Overview.

asylum_location_codestring · max: 128 · nullableOptional

Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the location endpoint for details.

asylum_location_namestring · max: 512 · nullableOptional

Filter the response by a location (typically a country). The location names are based on the "short name" from the UN M49 Standard. See the location endpoint for details.

asylum_has_hrpboolean · nullableOptional

Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.

asylum_in_ghoboolean · nullableOptional

Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the Global Humanitarian Overview.

start_datestring · nullableOptional

Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00

end_datestring · nullableOptional

Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59

output_formatstring · enumOptionalDefault: jsonPossible values:

limitinteger · max: 10000Optional

Maximum number of records to return. The system will not return more than 10,000 records.

Default: 10000Example: 100

offsetintegerOptional

Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.

Default: 0

Responses

200

Successful Response

application/json

400

Bad Request

application/json

422

Validation Error

application/json

500

Internal Server Error

application/json

get/api/v2/affected-people/refugees-persons-of-concern

GET /api/v2/affected-people/refugees-persons-of-concern?app_identifier=text HTTP/1.1
Host: hapi.humdata.org
Accept: */*

{
  "data": [
    {
      "resource_hdx_id": "text",
      "population_group": "REF",
      "gender": "f",
      "age_range": "text",
      "min_age": 1,
      "max_age": 1,
      "population": 1,
      "reference_period_start": "2026-01-01T00:00:00.000Z",
      "reference_period_end": "2026-01-01T00:00:00.000Z",
      "origin_location_code": "text",
      "origin_location_name": "text",
      "asylum_location_code": "text",
      "asylum_location_name": "text"
    }
  ]
}

Get humanitarian needs data

get

OCHA's Humanitarian Needs data, based on the Joint and Intersectoral Analysis Framework (JIAF), provides information about the number of people in need during a crisis. See the more detailed technical HDX HAPI documentation, and the original JIAF source website.

Query parameters

app_identifierstring · max: 512 · nullableRequired

base64 encoded application name and email, as in base64("app_name:email"). This value can also be passed in the X-HDX-HAPI-APP-IDENTIFIER header. See the encoded_app_identifier endpoint.

categorystring · max: 128 · nullableOptional

A category combining gender, age range, disability marker and population group information

sector_codestring · max: 32 · nullableOptional

Filter the response by the sector code.

population_statusstring · enum · max: 32 · nullableOptional

Filter the response by the population status, available values are described here.

Possible values:

population_mininteger · nullableOptional

Filter the response by a lower bound for the population.

population_maxinteger · nullableOptional

Filter the response by a upper bound for the population.

sector_namestring · max: 512 · nullableOptional

Filter the response by the sector name.

has_hrpboolean · nullableOptional

Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.

in_ghoboolean · nullableOptional

Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the Global Humanitarian Overview.

start_datestring · nullableOptional

Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00

end_datestring · nullableOptional

Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59

location_codestring · max: 128 · nullableOptional

Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the location endpoint for details.

location_namestring · max: 512 · nullableOptional

Filter the response by a location (typically a country). The location names are based on the "short name" from the UN M49 Standard. See the location endpoint for details.

admin1_codestring · max: 128 · nullableOptional

Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the Common Operational Datasets. See the admin1 endpoint for details.

admin1_namestring · max: 512 · nullableOptional

Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the Common Operational Datasets or those provided in the original data source. See the admin1 endpoint for details.

admin2_codestring · max: 128 · nullableOptional

Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the Common Operational Datasets. See the admin2 endpoint for details.

admin2_namestring · max: 512 · nullableOptional

Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the Common Operational Datasets or those provided in the original data source. See the admin2 endpoint for details.

admin_levelstring · enum · nullableOptional

Filter the response by admin level.

Possible values:

output_formatstring · enumOptionalDefault: jsonPossible values:

limitinteger · max: 10000Optional

Maximum number of records to return. The system will not return more than 10,000 records.

Default: 10000Example: 100

offsetintegerOptional

Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.

Default: 0

Responses

200

Successful Response

application/json

400

Bad Request

application/json

422

Validation Error

application/json

500

Internal Server Error

application/json

get/api/v2/affected-people/humanitarian-needs

GET /api/v2/affected-people/humanitarian-needs?app_identifier=text HTTP/1.1
Host: hapi.humdata.org
Accept: */*

{
  "data": [
    {
      "location_code": "text",
      "location_name": "text",
      "admin1_code": "text",
      "admin1_name": "text",
      "admin2_code": "text",
      "admin2_name": "text",
      "admin_level": 1,
      "resource_hdx_id": "text",
      "sector_code": "text",
      "category": "text",
      "population_status": "AFF",
      "population": 1,
      "reference_period_start": "2026-01-01T00:00:00.000Z",
      "reference_period_end": "2026-01-01T00:00:00.000Z",
      "sector_name": "text"
    }
  ]
}

Get idps data

get

Query parameters

app_identifierstring · max: 512 · nullableRequired

base64 encoded application name and email, as in base64("app_name:email"). This value can also be passed in the X-HDX-HAPI-APP-IDENTIFIER header. See the encoded_app_identifier endpoint.

has_hrpboolean · nullableOptional

Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.

in_ghoboolean · nullableOptional

Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the Global Humanitarian Overview.

start_datestring · nullableOptional

Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00

end_datestring · nullableOptional

Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59

location_codestring · max: 128 · nullableOptional

Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the location endpoint for details.

location_namestring · max: 512 · nullableOptional

Filter the response by a location (typically a country). The location names are based on the "short name" from the UN M49 Standard. See the location endpoint for details.

admin1_codestring · max: 128 · nullableOptional

Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the Common Operational Datasets. See the admin1 endpoint for details.

admin1_namestring · max: 512 · nullableOptional

Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the Common Operational Datasets or those provided in the original data source. See the admin1 endpoint for details.

admin2_codestring · max: 128 · nullableOptional

Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the Common Operational Datasets. See the admin2 endpoint for details.

admin2_namestring · max: 512 · nullableOptional

Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the Common Operational Datasets or those provided in the original data source. See the admin2 endpoint for details.

admin_levelstring · enum · nullableOptional

Filter the response by admin level.

Possible values:

output_formatstring · enumOptionalDefault: jsonPossible values:

limitinteger · max: 10000Optional

Maximum number of records to return. The system will not return more than 10,000 records.

Default: 10000Example: 100

offsetintegerOptional

Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.

Default: 0

Responses

200

Successful Response

application/json

400

Bad Request

application/json

422

Validation Error

application/json

500

Internal Server Error

application/json

get/api/v2/affected-people/idps

GET /api/v2/affected-people/idps?app_identifier=text HTTP/1.1
Host: hapi.humdata.org
Accept: */*

{
  "data": [
    {
      "location_code": "text",
      "location_name": "text",
      "admin1_code": "text",
      "admin1_name": "text",
      "admin2_code": "text",
      "admin2_name": "text",
      "admin_level": 1,
      "resource_hdx_id": "text",
      "reporting_round": 1,
      "assessment_type": "BA",
      "operation": "text",
      "population": 1,
      "reference_period_start": "2026-01-01T00:00:00.000Z",
      "reference_period_end": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Get returnees data

get

Query parameters

app_identifierstring · max: 512 · nullableRequired

base64 encoded application name and email, as in base64("app_name:email"). This value can also be passed in the X-HDX-HAPI-APP-IDENTIFIER header. See the encoded_app_identifier endpoint.

population_groupstring · enum · nullableOptional

Filter the response by the population group, available values are described here.

Possible values:

genderstring · enum · nullableOptional

Filter the response by the gender, available values are described here.

Possible values:

age_rangestring · max: 32 · nullableOptional

Filter the response by the age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data.

min_ageinteger · nullableOptional

The minimum age from age_range, set to null if age_range is "all" and there is no age disaggregation

max_ageinteger · nullableOptional

The maximum age from age_range, set to null if age_range is "all" and there is no age disaggregation, or if there is no upper limit to the age range

origin_location_codestring · max: 128 · nullableOptional

Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the location endpoint for details.

origin_location_namestring · max: 512 · nullableOptional

Filter the response by a location (typically a country). The location names are based on the "short name" from the UN M49 Standard. See the location endpoint for details.

origin_has_hrpboolean · nullableOptional

Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.

origin_in_ghoboolean · nullableOptional

Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the Global Humanitarian Overview.

asylum_location_codestring · max: 128 · nullableOptional

Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the location endpoint for details.

asylum_location_namestring · max: 512 · nullableOptional

Filter the response by a location (typically a country). The location names are based on the "short name" from the UN M49 Standard. See the location endpoint for details.

asylum_has_hrpboolean · nullableOptional

Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.

asylum_in_ghoboolean · nullableOptional

Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the Global Humanitarian Overview.

start_datestring · nullableOptional

Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00

end_datestring · nullableOptional

Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59

output_formatstring · enumOptionalDefault: jsonPossible values:

limitinteger · max: 10000Optional

Maximum number of records to return. The system will not return more than 10,000 records.

Default: 10000Example: 100

offsetintegerOptional

Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.

Default: 0

Responses

200

Successful Response

application/json

400

Bad Request

application/json

422

Validation Error

application/json

500

Internal Server Error

application/json

get/api/v2/affected-people/returnees

GET /api/v2/affected-people/returnees?app_identifier=text HTTP/1.1
Host: hapi.humdata.org
Accept: */*

{
  "data": [
    {
      "resource_hdx_id": "text",
      "population_group": "REF",
      "gender": "f",
      "age_range": "text",
      "min_age": 1,
      "max_age": 1,
      "population": 1,
      "reference_period_start": "2026-01-01T00:00:00.000Z",
      "reference_period_end": "2026-01-01T00:00:00.000Z",
      "origin_location_code": "text",
      "origin_location_name": "text",
      "asylum_location_code": "text",
      "asylum_location_name": "text"
    }
  ]
}