UNHCR's Refugee Data Finder serves comprehensive, reliable and up-to-date data on the world's forcibly displaced and stateless populations.
The data includes demographic and sub-national data as well as refugees and people displaced within their countries that
have found durable solutions to their displacement.
The Refugee Data Finder has been explored several million times by users around the world since its launch in June 2020.
Within the Refugee Data Finder, an Application Programming Interface (API) is available, which allows users to
interact directly with the data and create customized information products.
The API enables third-party applications to interface programmatically with the data so that UNHCR's data on forcibly
displaced and stateless populations can be incorporated directly in innovative humanitarian and research tools
for specific audiences. Imagine trying to dispel some myths and misconceptions about the forcibly displaced
or stateless populations based on data? Or highlighting challenges faced by forcibly displaced and stateless people?
The API provides an opportunity to explore, analyse and visualize this data in context with data from other sources.
The API in UNHCR's Refugee Data Finder is scalable, platform independent and developer friendly.
It is accessible using HTTP requests that return JSON-encoded responses.
It includes advanced query features, allowing filtering by certain fields, limiting the fields to be displayed, sorting and paging.
Who can use the UNHCR Refugee Data Finder API?
It is open to all and requires no special credentials. The API is accessible using HTTP requests that return JSON-encoded responses.
How does it work?
Here are two examples of using the API. Firstly, using three methods, the "People forced to flee" chart from Global Trends
will be replicated using d3.js. This chart combines five population groups from three different API queries as follows:
For refugees under UNHCR's mandate (including people in refugee-like situations), asylum-seekers and other people in
need of international protection:
For Palestine refugees under UNRWA's mandate:
And for the number of internally displaced people, reported by the Internal Displacement Monitoring Centre:
Figure 1 | People forced to flee | 2013 - 2022
The estimated total forced displacement at includes
million IDPs.
This estimate is calculated using IDMC’s figure as a base and reflecting only changes in the statistics
in the countries in which UNHCR reported internal displacement during the first six months of
.
The total new displacement is therefore likely to underestimate internal displacement globally.
Secondly, simple demographic charts can be produced showing data disaggregated by age and sex for specific years and population groups.
In the example below, refugees under UNHCR's mandate, people in refugee-like situations and other people in need of international
protection are shown for the latest year available. The data can be filtered by the largest countries of origin.
The data was sourced from a single API query:
Demographics for refugees, people in refugee-like situations and other people in need of international protection:
The data for the list of countries presented in the dropdown list was sourced using the population API query, and then filtered to show the 10 largest countries of origin:
Population query to show all countries:
Select country:
Figure 2 | Demographics of refugees, people in refugee-like situations
and other people in need of international protection | 2022
DISCLAIMER: figures may not add up to 100 per cent due to rounding.
Data availability by age and sex: %
Data availability by sex but not by age: %
What datasets can be accessed through UNHCR's Refugee Data Finder API?
The API within UNHCR's Refugee Data Finder includes the following methods:
Metadata:
Countries - a list of countries along with their codes, names and regions.
Years - a list of years for which data is available.
UNHCR Datasets:
Asylum applications - Individual asylum applications for international protection by year, country of asylum and country of origin.
Asylum decisions - Decisions on asylum applications by year, country of asylum and country of origin. Includes the number of substantive decisions (refugee status granted or rejected) and the number applications closed for administrative reasons.
Population data - Stock figures of the number of people in each population group at the end of each year, by country of origin and country of asylum.
Demographics - For each population group, data is available disaggregated by sex and age as well as location. The data also includes disaggregation by accommodation type and an urban/rural classification.
Footnotes
- Additional details about important changes to or issues with the data, by year, population group, country of asylum and country of origin.
Nowcasting
- nowcasting estimates of the refugee and asylum-seeker populations, with estimates produced for the previous month on a rolling basis.
See
nowcasting of refugee and asylum-seeker statistics
for more information on the nowcasting dataset.
Solutions
- Data on refugees and internally displaced people who have benefited from a durable solution. For refugees, this includes return to their country of origin, naturalization in their country of asylum and resettlement to a third country. For internally displaced people, currently this includes return to their place of origin.
Datasets from other organisations:
IDMC data - Data on internally displaced persons due to conflict and violence published by the Internal Displacement Monitoring Centre.
UNRWA data - Data on Palestine refugees registered under UNRWA's mandate.
How do I get started?
If you are interested to use the API, explore the two examples above, and then access our
API documentation and read
through the comprehensive documentation to get started. Call the API from your website or online application, process
the data you receive and display it in the way you require.
If you have any questions, feedback or suggestions for improvement of the API (or the site more generally), please do
let us know using the feedback link at the bottom of the home page. We will reply!
