Data downloads
Every number on this site is downloadable. Each row carries its source, as-of date and retrieval date.
Bulk CSV
RFC 4180, UTF-8, LF line endings. Empty field = not reported (distinct from 0).Snapshot f1a2b53a. Long-term archive (Zenodo) concept DOI: 10.5281/zenodo.22087749 — always resolves to the latest quarterly archived version, which can lag the daily online snapshot above. To cite one specific dataset, use that version’s own DOI as listed on the Zenodo record, and note its snapshot id.
| File | Description | Size |
|---|---|---|
| countries.csv | Entity list: ISO3, UNHCR name, display name, region, coverage flags, centroid. | 14 KB |
| unhcr-population-all-years.csv | Long format: one row per country × view × year × metric (non-null only). Best for pandas/R. | 17.7 MB |
| unhcr-population-by-asylum.csv | Wide format by country of asylum: one row per country × year, one column per metric. | 776 KB |
| unhcr-population-by-origin.csv | Wide format by country of origin: one row per country × year, one column per metric. | 753 KB |
| wpp-total-population.csv | UN WPP 2024 mid-year total population (per-1,000 denominator). | 1.4 MB |
datapackage.json(Frictionless Data descriptor with table schemas) ·manifest.json(file list, sha256, snapshot id) ·codebook (every field defined)
JSON files (static, CORS-open, versioned)
There is no API server — everything is a static file under /data/v1/, regenerated daily. Fetch with the ?v= hash from manifest.json for immutable caching, or without it for the latest.
| Path | Contents |
|---|---|
/data/v1/countries.json | 248 entities: ISO3, UNHCR name, display name, region, centroid/bbox, coverage flags |
/data/v1/stock/{from}-{to}.json | Columnar stocks for all metrics × countries × years (both views), population, global totals. Zero-runs packed as ["z",n], null-runs as ["n",n] |
/data/v1/country/{ISO3}.json | Everything for one country: series 1951–2025, demographics, top partners, solutions, asylum applications, IDMC, footnotes |
/data/v1/flows/{year}.json | Bilateral refugee/asylum-seeker matrix (origin × asylum), 2015+ |
/data/v1/live/nowcast.json | UNHCR nowcasting estimates (monthly, labelled as estimates) |
/data/v1/live/idu-latest.json | IDMC Internal Displacement Updates, last 180 days (preliminary; conflict coordinates snapped to a 25 km grid) |
/data/v1/geo/world-50m.topo.json | Natural Earth 1:50m boundaries (simplified), ISO3 ids |
/data/v1/sources.json · /data/v1/metrics.json | Provenance, licenses, caveats; metric definitions (en+zh) |
Sources & licenses
| Source | License | Attribution required | data as of | retrieved | Status |
|---|---|---|---|---|---|
UNHCR — Refugee Population Statistics Database — country listunhcr_countries | CC-BY-4.0 | UNHCR Refugee Population Statistics Database | 2026-08-19 | 2026-08-19 | up to date |
UNHCR — Refugee Population Statistics Database — population figuresunhcr_population | CC-BY-4.0 | UNHCR Refugee Population Statistics Database | 2025-12-31 | 2026-08-19 | up to date |
UNHCR — Refugee Population Statistics Database — demographicsunhcr_demographics | CC-BY-4.0 | UNHCR Refugee Population Statistics Database | 2025-12-31 | 2026-08-19 | up to date |
UNHCR (data: IDMC) — IDMC internal displacement figures via UNHCR APIunhcr_idmc | CC-BY-IGO | Internal Displacement Monitoring Centre (IDMC), via UNHCR Refugee Population Statistics Database | 2025-12-31 | 2026-08-19 | up to date |
UNHCR — Refugee Population Statistics Database — solutionsunhcr_solutions | CC-BY-4.0 | UNHCR Refugee Population Statistics Database | 2025-12-31 | 2026-08-19 | up to date |
UNHCR — Refugee Population Statistics Database — asylum applicationsunhcr_asylum_applications | CC-BY-4.0 | UNHCR Refugee Population Statistics Database | 2025-12-31 | 2026-08-19 | up to date |
UNHCR — Refugee Population Statistics Database — footnotesunhcr_footnotes | CC-BY-4.0 | UNHCR Refugee Population Statistics Database | 2025-12-31 | 2026-08-19 | up to date |
UNHCR — Refugee Population Statistics Database — nowcasting (estimates)unhcr_nowcasting | CC-BY-4.0 | UNHCR Refugee Population Statistics Database | 2026-08-01 | 2026-09-22 | up to date |
United Nations, DESA, Population Division — World Population Prospects 2024 — total population by sexwpp_population | CC-BY-3.0-IGO | United Nations, Department of Economic and Social Affairs, Population Division (2024). World Population Prospects 2024 | 2023-07-01 | 2026-08-19 | up to date |
IDMC — Internal Displacement Updates (IDU) — last 180 daysidmc_idu | CC-BY-IGO | Internal Displacement Monitoring Centre (IDMC), Internal Displacement Updates | 2026-10-02 | 2026-10-05 | up to date |
Natural Earth (via world-atlas) — Admin 0 – Countries, 1:50mnatural_earth | Public Domain | Made with Natural Earth | 2022-05-01 | 2026-08-19 | up to date |
Data licence details:DATA-LICENSE.md. The site code is open source under the MIT licence; the data remains under its original open licences.
Metric definitions
- Refugees
refugees· sourceunhcr_population - Persons recognised as refugees under the 1951 Convention/1967 Protocol, the 1969 OAU Convention, in accordance with the UNHCR Statute, persons granted complementary/subsidiary forms of protection, or those enjoying temporary protection. Includes people in a refugee-like situation. Excludes Palestine refugees under UNRWA’s mandate.
- Year-end stock (31 December).
- Excludes ~6 million UNRWA-registered Palestine refugees.
- Asylum-seekers
asylum_seekers· sourceunhcr_population - Individuals who have sought international protection and whose claims for refugee status have not yet been determined (pending cases).
- Year-end pending cases, counted in persons.
- Internally displaced (IDPs)
idps· sourceunhcr_idmc - People displaced within their own country by conflict or violence (as compiled by IDMC and reported by UNHCR). Counted under their country (origin = asylum).
- Source: IDMC via UNHCR. Disaster displacement is not included.
- Identical in both views (internal displacement has no host country).
- Stateless persons
stateless· sourceunhcr_population - Persons not considered as nationals by any State under the operation of its law, including persons of undetermined nationality.
- Reported by country of residence only; many countries do not report.
- Others of concern
ooc· sourceunhcr_population - Individuals who do not necessarily fall directly into any of the other groups but to whom UNHCR has extended its protection and/or assistance services.
- Returned refugees
returned_refugees· sourceunhcr_population - Former refugees who returned to their country of origin during the calendar year, spontaneously or in an organised fashion.
- Flow during the year, not a stock.
- Returned IDPs
returned_idps· sourceunhcr_population - Former IDPs who returned to their area of origin during the calendar year.
- Flow during the year, not a stock.
- Other people in need of international protection
oip· sourceunhcr_population - People outside their country of origin who are likely in need of international protection but whose status has not been determined (used notably for Venezuelans abroad since 2018).
- Reported since 2018; mostly Venezuelans displaced abroad.
- Host community
hst· sourceunhcr_population - Members of host communities benefiting from UNHCR programmes (reported for a small number of operations).
- Not a displaced population; excluded from totals.
- Total people of concern
total_poc· sourceunhcr_population - Sum of refugees, asylum-seekers, IDPs, stateless persons, others of concern and other people in need of international protection (excludes host community and returnees).
- Derived on the client from the component metrics; a null component is treated as 0 only when at least one component is reported.
- This sum can differ slightly from the headline totals UNHCR publishes (e.g. in Global Trends), which are compiled under UNHCR’s own aggregation rules.