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. What these numbers are, and are not

• They are what governments and UNHCR operations report. States have incentives to over- and under-count — funding appeals, sovereignty claims, contested legal statuses. A missing figure is not an absence of displaced people; grey is not zero.
• Coverage and definitions vary by country and year; watch for definition changes when comparing across time (e.g. OIP exists only from 2018).
• IDP figures cover conflict and violence only (IDMC); disaster displacement is not in the annual stocks.
• Nowcast and IDU figures are estimates / preliminary, labelled as such, and never mixed into the annual series.
• Mapping requires a polygon: a few reporting entities (Martinique, Gibraltar, "Stateless", "Unknown"…) have no drawable boundary; they are listed in the legend and included in all totals, tables and downloads.
• UNHCR figures exclude Palestine refugees under UNRWA's mandate (about 6 million), counted separately by UNRWA.

3. 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 — 18 data invariants (24 automated checks in total) 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 metric and year; the origin×asylum bilateral matrix sums back to each country's marginal totals; 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, its previous snapshot stays online and the site shows a "partial data update delayed" chip; after three consecutive days the maintainer is e-mailed.
5. Publish — the data files are committed to version control (a day-by-day audit trail) and archived quarterly to Zenodo, where the DOI-addressed bundles let anyone verify historical snapshots byte-for-byte; the site is then deployed as static files. The browser never calls UNHCR.

4. 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 (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.
• 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.

All stock figures are year-end (31 December). "Returned" figures are flows during the year.

"Forcibly displaced" is not "people of concern"

People of concern (total_poc) is the scope of UNHCR's protection mandate, not a definition of displacement. It includes stateless persons, who are counted by country of residence and have not necessarily left anywhere, and others of concern, a residual category with no displacement definition at all. Together they are roughly 6% of the total.
So every figure on this site that says forcibly displaced — including the "1 in every N people" sentence on the home page — is the sum of refugees + asylum-seekers + IDPs + OIP only, matching the population groups UNHCR itself reports as forcibly displaced. Host community and returnees are never included.
Correction: before 2026-09-05 that sentence used total_poc as its numerator and ran about 6% high. It is now computed from a single definition, FORCED_DISPLACEMENT_COMPONENTS, checked before every publish by data invariant #17.

Some metrics exist in only one view

Stateless persons and host community have a reading only for "where they are now". Statelessness is reported by country of residence — someone no state recognises as a national has no country of origin to be counted under — and host community counts people already living where they are. The upstream file repeats the same number in both views, which is not the same as that number meaning anything in the second one.
So neither metric is offered under "where they fled from": the menu omits it, a URL that asks for it is corrected, the country page shows that column as not reported, and total people of concern drops stateless persons from its origin sum (4,477,220 people in 2025).
Correction: metrics.json has always declared this rule, but until 2026-09-05 nothing in the app read it — ?m=stateless&v=origin put residence figures under an origin heading. One rule, METRIC_VIEWS, now drives every surface, and invariant #18 asserts it matches the published metadata.

5. Null is not zero

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

6. Two views: where they are, where they fled from

Every figure has two geographies. Country of asylum ("where they are now") counts people where they currently live. Country of origin ("where they fled from") 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.

7. 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. Rates are not shown where population is missing.

Estimates versus projections: in WPP 2024, the years 1950–2023 are estimates, reconstructed from censuses, surveys, registers and official statistics; 1 January 2024 through 2100 are projections derived from statistical forecasting models and demographic assumptions. When the map is showing per-1,000 rates for a projected year, the legend says so in plain text. This boundary and the attribution wording were confirmed with the UN DESA Population Division (2026-08-28). To inspect the empirical basis of the estimates for any country, see the WPP data sources, the methodology documentation folder, or the UN Population Division Data Portal, which offers an open API and the underlying empirical data points.

8. Colour scales

The site uses an earth-tone sequential ramp (ColorBrewer YlOrBr: sand → ochre → tilled-soil brown), seven classes, colour-blind safe. The principle is unchanged: displaced people are never visually framed as a threat — the site deliberately contains no red anywhere; the deepest class is the brown of soil, not an alarm colour, and flows are drawn as arcs, not arrows. The earth palette is a deliberate statement: desert and soil are what people cross, and what they lose. This design replaced an earlier single-hue blue ramp on 2026-08-25 (the change is on record), and is guarded by automated tests: the ramp must be warm-earth and monotonically darkening — any attempt to switch to alarm red fails the build. Default breaks are quantiles computed across the whole year range for the countries shown: while you scrub the timeline, colour means magnitude, not a rank that reshuffles every year — so screenshots from different years are comparable. Zero has its own lightest colour; not-reported is grey.

9. 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.

10. Freshness and failure

UNHCR publishes annual figures around June 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 dataset snapshot_id (content hash of the whole dataset, currently f1a2b53a). The bulk CSVs carry the population source's content-hash prefix in their snapshot column, resolvable via sources.json.

11. The live events layer

The "recent internal displacement events" layer republishes IDMC's preliminary event-level estimates. For dignity and safety: coordinates of conflict events are snapped to a ~25 km grid (never settlement-level); events under 100 people are not drawn as individual points; the popup shows figure, type and date and links to IDMC's own report instead of pasting narrative text. Event definitions differ from the annual IDP stock (which excludes disasters).

12. Citing

Every view has a permanent link that reproduces year, metric, view, filters, selection and map position (links produced by Share/Cite pin the year). The "Cite" button gives APA 7, Chicago (author–date), BibTeX (@dataset with version) and a plain "cite this page" string; the publication year is the data year, not the year you clicked, and the snapshot id is included for exact recovery. Please cite the upstream source as well as this site.

Questions or corrections: see About.