UNHCR APIdata.unhcr.org ↗
Access UNHCR refugee situations, population data, country/region details, documents, and partner organizations via 11 structured endpoints.
What is the UNHCR API?
This API exposes 11 endpoints covering UNHCR's Operational Data Portal — including refugee and displacement situations, country and regional bureau pages, document search, and partner organizations. The get_situation_population_data endpoint returns geographic coordinates, population group metadata, and time series statistics for a given situation slug. You can enumerate all tracked situations with list_situations, then drill into individual situation or country pages to retrieve embedded visualization widget URLs.
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'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace data-unhcr-org-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.unhcr_operational_data_portal_api import UNHCR, RegionSlug, NotFoundError
unhcr = UNHCR()
# List active refugee situations and print the first few
for situation in unhcr.situations.list(limit=5):
print(situation.name, situation.slug)
# Drill into one situation's detail widgets
sit = unhcr.situations.list(limit=1).first()
if sit:
detail = sit.detail()
print(detail.slug, len(detail.widgets))
for widget in detail.widgets:
print(widget.type, widget.url)
# List countries and get detail for the first one
country = unhcr.countries.list(limit=1).first()
if country:
country_detail = country.detail()
print(country_detail.iso3, len(country_detail.widgets))
# Use the RegionSlug enum to fetch a specific region's detail
region = unhcr.regions.get(slug=RegionSlug.RBESA)
region_detail = region.detail()
print(region_detail.slug)
for widget in region_detail.widgets:
print(widget.type, widget.url)
# Search documents and get metadata for the first result
try:
doc = unhcr.documents.search(query="refugees", limit=1).first()
if doc:
doc_detail = doc.detail()
print(doc_detail.id, doc_detail.metadata.publish_date, doc_detail.metadata.document_type)
except NotFoundError as exc:
print(f"Document not found: {exc}")
# List partners
for partner in unhcr.partners.list(limit=3):
print(partner.name)
print("exercised: situations.list / situation.detail / countries.list / country.detail / regions.get / region.detail / documents.search / document.detail / partners.list")
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"
},
{
"name": "Sudan situation",
"slug": "sudansituation"
}
]
},
"status": "success"
}
}About the UNHCR API
Situations and Population Data
The list_situations endpoint returns all active refugee and displacement situations UNHCR tracks, each with a name and slug. Pass a slug to get_situation_detail to retrieve embedded visualization widgets on that situation's page — categorized as powerbi, datawrapper, dataviz, or map types, each with a direct url. For richer structured output, get_situation_population_data fetches population-related widget data for the same slug, returning objects with an api_url and a data field that includes geographic coordinates, population group metadata, and time series figures.
Countries and Regions
list_countries enumerates all countries covered by the portal, returning name and lowercase ISO 3166-1 alpha-3 iso3 codes. Use the iso3 value with get_country_detail to get the country's associated visualization widgets. For regional bureau data, list_regions returns slugs like rbesa, rbap, rba, and rbwca. Feed those into get_region_detail to retrieve any Power BI dashboards or map iframes associated with that bureau.
Documents and Repositories
search_documents accepts an optional query keyword and a page parameter for manual pagination. It returns document id, title, and url fields, sorted by relevance (or recency when no query is provided). Pass a numeric document_id to get_document_detail to retrieve structured metadata including Publish Date, Upload Date, Document Type, and Document Language when those fields are available. list_document_repositories returns named repositories with a slug and url.
Partners
The get_partners endpoint returns a deduplicated list of partner organization names working with UNHCR. Empty strings and placeholder entries are filtered out automatically, so the partners array contains only meaningful organization names.
The UNHCR API is a managed, monitored endpoint for data.unhcr.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when data.unhcr.org changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official data.unhcr.org API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Monitor active displacement situations by iterating
list_situationsslugs and fetchingget_situation_population_datafor time series figures - Build a country-level dashboard by combining
list_countriesISO3 codes withget_country_detailwidget URLs - Track UNHCR reports on a specific topic using
search_documentswith a keyword query and paginating through results - Retrieve document metadata — publish date, language, and document type — via
get_document_detailfor bibliographic tools - Enumerate UNHCR partner organizations from
get_partnersfor grant mapping or partner relationship analysis - Pull regional bureau visualization links from
get_region_detailto embed in humanitarian situation reports - Catalogue available document repositories with
list_document_repositoriesfor data inventory pipelines
| 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 | 100 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 UNHCR provide an official developer API?+
What does `get_situation_population_data` return compared to `get_situation_detail`?+
get_situation_detail returns a flat list of embedded widget URLs categorized by type (powerbi, datawrapper, dataviz, map). get_situation_population_data focuses specifically on population-related widgets and parses deeper structure from them — returning api_url and a data object that includes geographic coordinates, population group metadata, and time series records.Are document full-texts or file downloads available through the API?+
search_documents and get_document_detail endpoints return document titles, URLs, and metadata fields (publish date, upload date, type, language), but not document body text or binary file contents. You can fork this API on Parse and revise it to add an endpoint that fetches and parses document content from the returned URL.Does pagination work automatically across all endpoints?+
search_documents supports manual pagination via the page parameter. The listing endpoints (list_situations, list_countries, list_regions, get_partners, list_document_repositories) return complete deduplicated sets in a single response and do not use pagination parameters.Can I filter situations or countries by region or population threshold?+
list_situations and list_countries return full unfiltered lists of slugs and ISO3 codes. Filtering by region, population size, or situation type is not exposed as a parameter. You can fork this API on Parse and revise it to add filter parameters backed by the relevant detail endpoints.