Affected People

Internally-Displaced Persons

The data for this sub-category is taken from the International Organization for Migration (IOM)'s displacement tracking matrix (DTM), which collects and analyzes data on population movements, displacements, and mobility patterns to provide timely information for humanitarian response efforts. The DTM data used in HAPI is taken from their publicly accessible API, however we note that there are many country-specific DTM datasets available on HDX, which contain more detail and disaggregation.

Summary

Attribute	Details
Data provider	IOM
Dataset	Global IOM Displacement Tracking Matrix (DTM) from API
Time series	Approximately monthly, dating back to 2010
Update frequency	Weekly
Related tables	`Assessment Type`

Parameters Returned

The table below describes the parameters returned from this endpoint. For available query parameters, please see the API sandbox.

Parameter	Description	Source
`resource_hdx_id`	Unique resource UUID on HDX	`Resource`
`reporting_round`	Data collection round number
`assessment_type`	Either baseline assessment (BA) or site assessment (SA)	`Assessment Type`
`operation`	Name of DTM Operation for which the data was collected
`population`	The number of people
`reference_period_start`	The start date for which the data are applicable
`reference_period_end`	The end date for which the data are applicable
`location_code`	Location p-code, based on the ISO-3 (ISO 3166 alpha-3) standard	`Location`
`location_name`	Location name, based on the "short name" from the UN M49 Standard	`Location`
`location_ref`	A reference to the `id` of the associated entry in the `location` table	`Location`
`admin1_code`	Admin 1 p-code	`Admin 1`
`admin1_name`	Admin 1 name	`Admin 1`
`provider_admin1_name`	Admin 1 names provided in the original source data
`admin1_ref`	A reference to the `id` of the associated entry in the `admin 1` table	`Admin 1`
`admin2_code`	Admin 2 p-code	`Admin 2`
`admin2_name`	Admin 2 name	`Admin 2`
`provider_admin2_name`	Admin 2 names provided in the original source data
`admin2_ref`	A reference to the `id` of the associated entry in the `admin 2` table	`Admin 2`

Transformations applied

None

Usage notes

To obtain the number of IDPs per year in a given location, only the most recent reporting round per operation should be aggregated

Refugees & Persons of Concern

This sub-category is populated using data compiled by UNHCR, which offers annual age- and gender-disaggregated global statistics on forcibly displaced and stateless persons, categorised by their country of origin and country of asylum. The data are sourced primarily from governments hosting these populations, UNHCR's own registration data, and occasionally data published by non-governmental organizations.

Summary

Attribute	Details
Data provider	UNHCR
Dataset	Data on forcibly displaced populations and stateless persons (Global)
Time series	Annual, dating back to 2001
Update frequency	Annually
Related tables	`Gender`, `PopulationGroup`

Parameters Returned

The table below describes the parameters returned from this endpoint. For available query parameters, please see the API sandbox.

Parameter	Description	Source
`resource_hdx_id`	Unique resource UUID on HDX	`Resource`
`population_group`	Population group as defined by UNHCR	`Population Group`
`gender`	The gender of the population group in question, set to "all" if there is no disaggregation	`Gender`
`age_range`	The age range of the population group in question, set to "all" if there is no disaggregation
`min_age`	The minimum age from `age_range`, set to `null` if `age_range` is "all" and there is no age disaggregation
`max_age`	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`	The number of people
`reference_period_start`	The start date for which the data are applicable
`reference_period_end`	The end date for which the data are applicable
`origin_location_code`	Location of origin p-code (ISO-3)	`Location`
`origin_location_name`	Location of origin name	`Location`
`origin_location_ref`	An internal, stable identifier that references the location of origin	`Location`
`asylum_location_code`	Location of asylum p-code (ISO-3)	`Location`
`asylum_location_name`	Location of asylum name	`Location`
`asylum_location_ref`	An internal, stable identifier that references the location of asylum	`Location`

Transformations applied

As this endpoint only concerns refugees and people of concern, and not IDPs or returnees, we only include statistics from the population groups "REF", "ROC", "ASY", "OIP", "IOC", "STA", "OOC", "HST", "RST", and "NAT"
The table has been reshaped from wide to long: demographic-specific columns have been cast to gender, age_range, and population
It is not possible to p-code based on the location information in the original data, therefore population numbers are aggregated to the national level
The reference period is constructed using the full range of the year presented in the “Year” column of the original data

Usage notes

Not all of the possible population groups are necessarily found in the UNHCR data
An “all” value in the gender and age_range columns indicates no disaggregation
age_range is expressed as "[min_age]-[max_age]", where max_age is inclusive, or "[min_age]+" for an age range starting at min_age or above

Returnees

This sub-category is populated using data compiled by UNHCR, which offers annual age- and gender-disaggregated global statistics on forcibly displaced and stateless persons, categorised by their country of origin and country of asylum. The data are sourced primarily from governments hosting these populations, UNHCR's own registration data, and occasionally data published by non-governmental organizations.

Summary

Attribute	Details
Data provider	UNHCR
Dataset	Data on forcibly displaced populations and stateless persons (Global)
Time series	Annual, dating back to 2001
Update frequency	Annually
Related tables	`Gender`, `PopulationGroup`

Parameters Returned

The table below describes the parameters returned from this endpoint. For available query parameters, please see the API sandbox.

Parameter	Description	Source
`resource_hdx_id`	Unique resource UUID on HDX	`Resource`
`population_group`	Population group as defined by UNHCR	`Population Group`
`gender`	The gender of the population group in question, set to "all" if there is no disaggregation	`Gender`
`age_range`	The age range of the population group in question, set to "all" if there is no disaggregation
`min_age`	The minimum age from `age_range`, set to `null` if `age_range` is "all" and there is no age disaggregation
`max_age`	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`	The number of people
`reference_period_start`	The start date for which the data are applicable
`reference_period_end`	The end date for which the data are applicable
`origin_location_code`	Location of origin p-code (ISO-3)	`Location`
`origin_location_name`	Location of origin name	`Location`
`origin_location_ref`	An internal, stable identifier that references the location of origin	`Location`
`asylum_location_code`	Location of asylum p-code (ISO-3)	`Location`
`asylum_location_name`	Location of asylum name	`Location`
`asylum_location_ref`	An internal, stable identifier that references the location of asylum	`Location`

Transformations applied

As this endpoint only concerns returnees and not the other population groups available in the UNHCR data, we only include statistics from the "RET" and "RDP" population groups
The table has been reshaped from wide to long: demographic-specific columns have been cast to gender, age_range, and population
It is not possible to p-code based on the location information in the original data, therefore population numbers are aggregated to the national level
The reference period is constructed using the full range of the year presented in the “Year” column of the original data

Usage notes

UNHCR is the only source for returnees in some countries and is therefore included in HDX HAPI, but if data is available from IOM, that data is preferable
An “all” value in the gender and age_range columns indicates no disaggregation
age_range is expressed as "[min_age]-[max_age]", where max_age is inclusive, or "[min_age]+" for an age range starting at min_age or above

Humanitarian Needs

This Humanitarian Needs Overview (HNO) represents the shared understanding of OCHA Humanitarian Country Teams of people's widespread emergency needs during crises. It includes an estimate of the number of people by sector who require assistance, often referred to as People in Need (PIN), which is derived using the Joint Intersectoral Analysis Framework (JIAF).

While the HNO data is directly available on HDX, it comes from different OCHA offices and is currently not standardised. Thus, HDX HAPI obtains the PIN numbers from the HPC Tools API-based datasets on HDX. This results in some loss of detail — unlike the original data, HPC Tools does not have consistent Sex and Age Disaggregation (SADD), but instead includes a single, freeform category field — but using it allows HAPI to include data for more countries and update that data more quickly. As HPC Tools improves its SADD support, we will update HAPI to take advantage of it.

Summary

Attribute	Details
Data provider	OCHA HPC
Dataset	Global Humanitarian Programme Cycle, Humanitarian Needs
Time series	Past datasets are available in the HPC API, but are sparse prior to 2023
Update frequency	Annually
Related tables	`PopulationStatus`

Parameters Returned

The table below describes the parameters returned from this endpoint. For available query parameters, please see the API sandbox.

Parameter	Description	Source
`resource_hdx_id`	Unique resource UUID on HDX	`Resource`
`sector_code`	The sector code, derived either from the Global Coordination Groups dataset, or created for HDX HAPI	`Sector`
`sector_name`	The name of the sector	`Sector`
`population_status`	The population status, such as in-need or targeted	`Population Status`
`population`	The number of people
`reference_period_start`	The start date for which the data are applicable
`reference_period_end`	The end date for which the data are applicable
`location_code`	Location p-code, based on the ISO-3 (ISO 3166 alpha-3) standard	`Location`
`location_name`	Location name, based on the "short name" from the UN M49 Standard	`Location`
`location_ref`	A reference to the `id` of the associated entry in the `location` table	`Location`
`admin1_code`	Admin 1 p-code	`Admin 1`
`admin1_name`	Admin 1 name	`Admin 1`
`provider_admin1_name`	Admin 1 names provided in the original source data
`admin1_ref`	A reference to the `id` of the associated entry in the `admin 1` table	`Admin 1`
`admin2_code`	Admin 2 p-code	`Admin 2`
`admin2_name`	Admin 2 name	`Admin 2`
`provider_admin2_name`	Admin 2 names provided in the original source data
`admin2_ref`	A reference to the `id` of the associated entry in the `admin 2` table	`Admin 2`

Transformations applied

The table has been reshaped from wide to long: the columns in the original data of "population", "in-need", "targeted", "affected", "reached", and "population" have been cast to a single population_status field, and renamed to "all", "INN", "TGT", "AFF", and "REA", respectively
Sector values of “ALL” have been converted to “intersectoral”, as these represent the intersectoral PIN and not the disaggregated population
The methodology in Yemen leads to negative population values in some admin 2 level areas. Where negative values appear they have been omitted from the API.
The reference period is obtained from the HDX dataset

Usage notes

The PIN should not be summed across sectors or population statuses, as the same people can be present across multiple groups
For the number of people affected across all sectors, please use the PIN value where sector=Intersectoral