Methodology

1. Sources

Everything shown is group-level statistics published by international organisations. This site never handles person-level data.

Full provenance per source (endpoints, content hashes, retrieval times, caveats) is machine-readable in sources.json. Not used: ACLED (licence forbids dashboard republication), IOM DTM (licence not yet confirmed), UNHCR Operational Data Portal and microdata (non-commercial terms).

2. Pipeline: daily, static, audited

1. Fetch — a scheduled job calls the UNHCR API (throttled: 2 concurrent requests, ≥ 300 ms apart, retries with back-off) and downloads the WPP CSV and the IDMC IDU dump. The latest year with published data is detected automatically (currently 2025).
2. Normalise — every row is keyed by ISO 3166-1 alpha-3 read from UNHCR's coo_iso/coa_iso fields. UNHCR's internal codes (coo/coa) are never used: they collide with real ISO3 codes (UNHCR "AUS" is Austria, "ARE" is Egypt, "MAR" is Martinique). Numeric fields arrive as "-" (not reported),"0" or numbers; they are converted to null / 0 / integer.
3. Validate — 15 invariants must hold before anything is published, including: the three collision cases are keyed correctly; no negative or non-finite values; mapped total + unmappable total = global total for every year; year-over-year totals do not drift more than 20 % against the previous snapshot; and three golden numbers (Türkiye refugees 2024, Syria IDPs 2016, world refugees 2024) match within 1 %.
4. Promote — each source is promoted independently. If a source fails or fails validation, its previous snapshot stays online and the site shows a "partial data update delayed" chip with the date; after three consecutive days the maintainer is e-mailed.
5. Publish — the data files are committed to the repository (a permanent audit trail:git log -- public/data/v1/country/SYR.json answers "what did this number say on day X") and deployed as static files. No server runs at request time; the browser never calls UNHCR.

3. Definitions

Refugees

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

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 persons (IDPs)

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

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

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

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

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

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

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

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.

All stock figures are year-end (31 December). "Returned" figures are flows during the year. The UNHCR population figures exclude Palestine refugees under UNRWA's mandate (about 6 million); see the Palestine page note.

4. Null is not zero

UNHCR distinguishes not reported ("-") from reported zero. We keep that distinction everywhere: on the map (grey vs the lightest blue), in charts (a gap in the line vs a point at 0), in CSV (empty field vs 0) and in JSON (null vs0). A country in grey may host many refugees that simply were not reported for that year.

5. Two views: who hosts, who fled

Every figure has two geographies. Country of asylum ("who hosts them") counts people where they are now. Country of origin ("who fled") counts the same people by the country they left. Internally displaced persons are counted in their own country in both views. The "Flows" tab and the flows/ files give the bilateral matrix.

6. Per 1,000 residents

Rate = persons ÷ UN WPP mid-year total population × 1,000. Two caveats: the numerator is a 31 December stock while the denominator is 1 July; and WPP values after the estimate base year are medium-variant projections. Rates are not shown where population is missing.

7. Colour scales

A single-hue blue ramp (ColorBrewer Blues) is used throughout — no red/orange scales, which would visually frame displaced people as a threat. Seven classes. Default breaks are quantiles of the countries currently shown (so the map always has contrast); log and linear breaks are available and rounded to "nice" numbers. Zero has its own lightest colour; not-reported is grey.

8. Boundaries and names

Boundaries come from Natural Earth, simplified for display. Country names follow the data source being cited (UNHCR), with a small override table for readability (e.g. "Syrian Arab Rep." → "Syria"); the original name is always shown alongside. Disputed territories, Kosovo and Taiwan are handled explicitly — see Boundaries, names and disputed territories.

9. Freshness and failure

UNHCR publishes annual figures around June (previous year) and mid-year figures around October/November. The pipeline runs daily but only commits when content changes. Three timestamps are kept apart: data_as_of (what the data covers), retrieved_at (when we fetched it — only advances when content changed) and the snapshot_id (content hash of the whole dataset, currently dd3c6875).

10. Citing

Every view has a permanent link that reproduces year, metric, view, filters, selection and map position. The "Cite" button gives APA 7, Chicago author-date, BibTeX and a plain "cite this page" string that names the upstream source, its as-of date and our retrieval date. Please cite the upstream source as well as this site.

11. Limitations

• Statistics depend on what governments and UNHCR operations report; coverage and definitions vary by country and year.
• IDP figures cover conflict and violence only (IDMC); disaster displacement is not included in the annual stocks.
• Nowcast and IDU figures are estimates / preliminary and are labelled as such; they are never mixed into the annual series.
• Mapping requires a polygon: a few reporting entities (e.g. Martinique, Gibraltar, Tuvalu, "Stateless", "Unknown") have no drawable boundary here; they are listed in the legend and included in all totals, tables and downloads.

Questions or corrections: see About.