data.unhcr.org APIdata.unhcr.org ↗
Access UNHCR refugee situations, population data, countries, regions, documents, and partner organizations via 11 structured endpoints.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/9db8fcad-49c4-48d2-b8ad-bd3e2229dab0/list_situations' \ -H 'X-API-Key: $PARSE_API_KEY'
List all active refugee/displacement situations tracked by UNHCR. Returns situation names and URL slugs. Deduplicates entries by slug.
No input parameters required.
{
"type": "object",
"fields": {
"situations": "array of situation objects, each with 'name' (string) and 'slug' (string)"
},
"sample": {
"data": {
"situations": [
{
"name": "Afghanistan situation",
"slug": "afghanistan"
},
{
"name": "Ukraine Refugee Situation",
"slug": "ukraine"
}
]
},
"status": "success"
}
}About the data.unhcr.org API
This API exposes 11 endpoints covering UNHCR's Operational Data Portal, returning structured data on refugee and displacement situations, country and regional bureau pages, population statistics, and document repositories. The get_situation_population_data endpoint retrieves time series and geographic population figures by situation slug, while search_documents lets you query UNHCR reports by keyword with pagination support.
Situations and Population Data
The list_situations endpoint returns all active displacement situations tracked by UNHCR, each with a name and slug. Pass that slug to get_situation_detail to retrieve associated widget API URLs, including widget_id and sv_id fields where available. For richer data, get_situation_population_data fetches population-related widget data for a situation — each result includes an api_url and a data object containing geographic coordinates, population group metadata, and time series statistics.
Countries and Regions
list_countries returns every country covered by the portal with ISO 3166-1 alpha-3 codes (lowercase, e.g. afg, col). Use that iso3 value with get_country_detail to retrieve widget API URLs for that country page. UNHCR's regional bureaus are available via list_regions, returning name and slug per bureau. get_region_detail takes a region slug (e.g. rbesa, rbap) and returns its widget URLs. Note that region detail requests may be slow due to large widget parameter lists.
Documents and Repositories
search_documents accepts optional query and page parameters and returns document id, title, and url fields sorted by relevance. Omitting the query returns recent documents. Retrieve per-document metadata with get_document_detail using a numeric document_id; the metadata object can include Publish Date, Upload Date, Document Type, and Document Language when those fields are present. list_document_repositories returns all UNHCR document repositories with name, slug, and url.
Partners
get_partners returns a deduplicated list of partner organization names working with UNHCR, with empty and placeholder entries filtered out. The response is a flat array of objects each containing a single name field.
- Track displacement trends over time using time series data from
get_situation_population_datafor a specific situation slug - Build a country-level humanitarian dashboard by combining
get_country_detailwidget URLs with ISO3 codes fromlist_countries - Search UNHCR reports by keyword with
search_documentsand retrieve publish date and document type viaget_document_detail - Enumerate all UNHCR regional bureaus and their associated data widgets using
list_regionsandget_region_detail - Compile a directory of UNHCR partner organizations for NGO mapping using
get_partners - Catalog available document repositories with names and URLs via
list_document_repositoriesfor research pipeline indexing - Cross-reference situation slugs with geographic and population group metadata to support academic displacement research
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does data.unhcr.org have an official developer API?+
What does `get_situation_population_data` return beyond simple totals?+
api_url and a data object that can contain geographic coordinates, population group metadata (such as refugee, IDP, or returnee categories), and time series data showing how population figures have changed over time for that situation.Does the document search support filtering by document type or date range?+
search_documents endpoint accepts a query keyword and a page number for pagination, but does not currently expose filters for document type, date range, or language. You can retrieve per-document metadata including Document Type and Publish Date individually via get_document_detail. You can fork this API on Parse and revise it to add filtering logic on top of those fields.Is there an endpoint for individual situation funding or financial response data?+
Are there any known quirks with the region detail endpoint?+
get_region_detail endpoint is documented to be slow due to large widget parameter lists on regional bureau pages. If you are polling multiple regions in sequence, building in request delays or processing them asynchronously will reduce timeout risk.