---
title: "Get refugees data"
method: GET
path: "/api/v2/affected-people/refugees-persons-of-concern"
tags: ["Affected People"]
---

# Get refugees data

`GET /api/v2/affected-people/refugees-persons-of-concern`

## Request

- Base URL: `https://data.humdata.org/api/3/action`
- URL: `https://data.humdata.org/api/3/action/api/v2/affected-people/refugees-persons-of-concern`
- Auth: one of:
  - none
  - API key in header `Authorization`

UNHCR's Refugee data provides information about displaced people in a crisis. See the more detailed technical <a href="https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/affected_people/#refugees-persons-of-concern">HDX HAPI documentation</a>, and the <a href="https://data.humdata.org/dataset/unhcr-population-data-for-world">original HDX source</a> website.

## Query parameters

- `app_identifier` string, nullable, required: 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_group` 'REF' | 'ROC' | 'ASY' | 'OIP' | 'IDP' | 'IOC' | 'STA' | 'OOC' | 'HST' | 'RET' | 'RST' | 'NAT' | 'RDP' | 'RRI' | 'all', nullable
- `population_min` integer, nullable: Filter the response by a lower bound for the population.
- `population_max` integer, nullable: Filter the response by a upper bound for the population.
- `gender` 'f' | 'm' | 'x' | 'u' | 'o' | 'all', nullable
- `age_range` string, nullable: 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_code` string, nullable: Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href="/docs#/Metadata/get_locations_api_v1_metadata_location_get" target="_blank">location endpoint</a> for details.
- `origin_location_name` string, nullable: Filter the response by a location (typically a country). The location names are based on the "short name" from the <a href="https://unstats.un.org/unsd/methodology/m49/#fn2">UN M49 Standard</a>. See the <a href="/docs#/Metadata/get_locations_api_v1_metadata_location_get" target="_blank">location endpoint</a> for details.
- `origin_has_hrp` boolean, nullable: Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.
- `origin_in_gho` boolean, nullable: Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href="https://humanitarianaction.info/">Global Humanitarian Overview</a>.
- `asylum_location_code` string, nullable: Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href="/docs#/Metadata/get_locations_api_v1_metadata_location_get" target="_blank">location endpoint</a> for details.
- `asylum_location_name` string, nullable: Filter the response by a location (typically a country). The location names are based on the "short name" from the <a href="https://unstats.un.org/unsd/methodology/m49/#fn2">UN M49 Standard</a>. See the <a href="/docs#/Metadata/get_locations_api_v1_metadata_location_get" target="_blank">location endpoint</a> for details.
- `asylum_has_hrp` boolean, nullable: Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.
- `asylum_in_gho` boolean, nullable: Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href="https://humanitarianaction.info/">Global Humanitarian Overview</a>.
- `start_date` string, nullable: 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_date` string, nullable: 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_format` 'csv' | 'json'
- `limit` integer: Maximum number of records to return. The system will not return more than 10,000 records.
- `offset` integer: Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.

## Response `200`

Successful Response

- HapiGenericResponseRefugeesResponse
  - `data` RefugeesResponse[], required
    - `resource_hdx_id` string, required: The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX.
    - `population_group` 'REF' | 'ROC' | 'ASY' | 'OIP' | 'IDP' | 'IOC' | 'STA' | 'OOC' | 'HST' | 'RET' | 'RST' | 'NAT' | 'RDP' | 'RRI' | 'all', required: The population group, available values are described <a href="https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-group">here.</a>
    - `gender` 'f' | 'm' | 'x' | 'u' | 'o' | 'all', required: The gender, available values are described <a href="https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender">here.</a>
    - `age_range` string, required: 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_age` integer, nullable, required: The minimum age from `age_range`, set to `null` if `age_range` is "all" and there is no age disaggregation
    - `max_age` integer, nullable, required: 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
    - `population` integer, required: The number of people
    - `reference_period_start` string, date-time, required: The start date for which the data are applicable
    - `reference_period_end` string, date-time, nullable, required: The end date for which the data are applicable
    - `origin_location_code` string, required: Location of origin p-code (ISO-3)
    - `origin_location_name` string, required: Location of origin name
    - `asylum_location_code` string, required: Location of asylum p-code (ISO-3)
    - `asylum_location_name` string, required: Location of asylum name

## Other responses

- `400`: Bad Request
- `422`: Validation Error
- `500`: Internal Server Error

---

[API](https://skmtc.dev/humdata/apis/hdx-apis.md) - [All operations](https://skmtc.dev/humdata/apis/hdx-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/humdata/apis/hdx-apis/revisions/cc1970bc392c?raw)
