UNHCR Population Statistics: Intelligence Source Guide

UNHCR's Refugee Statistics API serves the official global counts of refugees, asylum-seekers, internally displaced people, stateless persons and returnees, by country of origin and country of asylum, back to 1951. It is the reference series for forced displacement, and almost every figure in it was supplied by a government.

At a glance

Source	UNHCR Population Statistics
Category	Conflict, Crime & Human Security › Conflict & Event Databases
Homepage	https://www.unhcr.org/refugee-statistics/
Machine interface	`https://api.unhcr.org/population/v1/population/`
Format	`JSON`
Access	Open — no account required
Disciplines	Geospatial Intelligence, Economic Intelligence
Mission domains	Conflict & Humanitarian, Border Security & Migration

Refugee/IDP population data API. — as catalogued in the platform’s own source registry.

The Refugee Population Statistics Database is UNHCR's compilation of annual, end-of-year stock figures for populations within its statistical mandate, exposed through a public REST API at api.unhcr.org/population/v1/ with no key and no registration. The core resource, population, returns one row per year per country-of-origin per country-of-asylum combination, carrying counts for refugees, asylum-seekers, returned refugees, internally displaced persons, returned IDPs, stateless persons, others of concern, other people in need of international protection, and host community. Parallel resources cover asylum applications, asylum decisions broken down by procedure type, decision level and whether the count is of persons or cases, durable solutions (returns, resettlement, naturalisation), IDMC's internal displacement figures, UNRWA's registered Palestine refugee figures, demographic breakdowns, and the footnotes that qualify individual figures. Reference resources return the country and region lookup tables and the list of available years, which begins in 1951. Every data resource accepts yearFrom, yearTo, coo and coa filters, a cf_type switch to use ISO3 codes instead of UNHCR's own country codes, and a download flag that returns CSV instead of JSON. Rows are aggregated across any dimension you do not filter on, so an unfiltered call returns global totals rather than an error.

This is the counting system that turns displacement into an administrative fact. Its job is not to describe suffering; it is to produce a comparable, dated, attributable number that governments, courts, donors and operational agencies can all argue from. That has a specific analytical consequence: the numbers are counts of people in legal and administrative categories, not counts of people in need. A refugee in this dataset is someone recognised as such by a state or by UNHCR under its mandate, an asylum-seeker is someone with a pending claim in a formal procedure, and a stateless person is someone a state has reported as lacking any nationality. Where the category does not fit, the person is not counted, however displaced they are. Understood that way, the database becomes powerful for a set of jobs nothing else does: measuring the movement of populations between specific origin and asylum country pairs over seventy years, tracking whether a state's asylum system is processing or accumulating claims, and detecting the moment when a government's own reporting changes. For ECONINT and GEOINT work on borders, displacement pressure and the fiscal weight of hosting, it is the primary series. It is also, for most conflicts, the least politically contested large number available, which is precisely why the politics show up inside it rather than around it.

Who publishes it, and why that matters

UNHCR is a UN agency funded overwhelmingly by voluntary contributions from a small number of donor states, and it operates in the territory of, and with the permission of, the governments whose figures it publishes. Both facts shape the data. The agency does not generally count people itself in countries with functioning asylum systems; it publishes what governments report, applying its own methodology notes and footnotes where the figures need qualification, and it produces its own estimates chiefly where no state system exists or where it registers refugees directly. That gives the series institutional weight and creates a structural dependency: a government that stops reporting, changes its definition of who is registered, or declines to acknowledge a population produces a change in the published series that looks like a change in the world. The agency is transparent about this, publishes a methodology section and attaches footnotes to individual figures, and has invested seriously in open access, with a public API, a microdata library and an operational data portal. Longevity is not in question. What is in question, permanently, is whose count you are reading, and the footnotes endpoint exists precisely so you can find out.

Provenance is the first question to ask of any dataset and the one most often skipped. Who collects it, what their incentive is, whether they publish a methodology, and whether they correct the record when they get something wrong all bear directly on how much weight a finding drawn from it can carry.

What a record actually contains

The fields you will be working with, what each one means, and whether it is something you can pivot on. Read the meanings carefully — more analysis is wrecked by misreading a field than by failing to find one, and a field that looks like an observation is often an inference.

Field	Type	What it means	Pivot value
`year`	int	The reference year. Figures are end-of-year stocks unless the resource is explicitly a flow, such as asylum applications or solutions. Available years begin in 1951.	Time series construction; alignment with conflict event data and displacement triggers.
`coo / coo_iso / coo_name`	string	Country of origin in UNHCR's own three-letter code, the ISO3 equivalent, and the display name. The two coding systems are not identical and cf_type controls which one your filters use.	Conflict datasets, sanctions regimes, country risk profiles, the countries reference resource.
`coa / coa_iso / coa_name`	string	Country of asylum, coded the same way. The origin-asylum pair is the analytical unit that makes this database distinctive; almost no other displacement source publishes the full bilateral matrix.	Border and route analysis; host-state burden comparisons; regional agreements.
`refugees`	int	People recognised as refugees under the 1951 Convention, the 1969 OAU Convention, the Cartagena Declaration, or UNHCR's mandate. Recognition is the criterion, not displacement.	Asylum decision data for the same pair; host country policy analysis.
`asylum_seekers`	int	People with a pending claim for international protection at the end of the year. A rising figure can mean more arrivals or a slower system, and the two are indistinguishable without the applications and decisions resources.	asylum-applications and asylum-decisions resources; backlog and processing-rate analysis.
`idps`	int	Internally displaced people of concern to UNHCR. This is not the same as all IDPs in a country: it covers the population UNHCR reports on, which in many countries is a subset, and IDMC's figures are the broader series.	The idmc resource; IDMC's own database; conflict event data for the same subnational areas.
`returned_refugees / returned_idps`	int	People recorded as having returned during the year. A flow, not a stock, sitting in a table of stocks, which catches people out. Return is recorded, not assessed for durability or voluntariness.	The solutions resource; protection monitoring; conditions-of-return reporting.
`stateless`	int	People reported as not considered a national by any state. Coverage is acknowledged to be very partial, since identifying stateless populations requires a state willing to acknowledge them.	Nationality law analysis; minority rights reporting; UNHCR statelessness campaigns.
`ooc / oip / hst`	int	Others of concern, other people in need of international protection, and host community. These categories have been introduced and revised over time, which makes long time series across them discontinuous.	Footnotes resource; methodology documentation; reconciling headline totals across reporting years.
`procedure_type / dec_level / dec_pc`	enum	On the asylum-decisions resource: whether the procedure was governmental or UNHCR-conducted, whether the decision was first instance or on appeal, and whether counts are of persons or of cases. Ignoring the persons-versus-cases flag produces incomparable numbers.	Recognition rate calculation; comparison of national asylum systems.
`dec_recognized / dec_rejected / dec_other / dec_closed / dec_total`	int	Asylum decision outcomes. Recognition rates computed with different denominators, particularly whether closed cases are included, differ enormously and are the most commonly mangled derived statistic in this dataset.	Country-of-origin protection needs; policy change detection; legal research.
`page / maxPages`	int	Pagination controls returned in every response envelope alongside items. Large unfiltered queries page heavily and a client that ignores maxPages silently truncates its own extract.	Collection completeness checking.
`footnotes`	array	Qualifications attached to specific figures, available through their own resource. These carry the caveats that make a figure interpretable, including changes in methodology and the basis of an estimate.	Reading any figure honestly; explaining discontinuities in a series.

Coverage — and what is not in it

Global, annual, from 1951 to the most recent completed reporting year, with the bilateral origin-and-asylum matrix as the distinctive feature. Coverage is uneven in exactly the way an administrative dataset is: excellent for populations inside functioning asylum systems, thinner for populations in states that do not report, and structurally partial for internal displacement and statelessness. Palestine refugees registered with UNRWA are covered by a separate resource because they fall under a different agency's mandate, and treating the two as additive without care will double-count or undercount depending on the country. IDMC figures are exposed through their own resource rather than merged into the main population series, reflecting a genuine methodological difference rather than a technical convenience. Update rhythm is annual, with the global figures published in UNHCR's mid-year reporting cycle for the preceding year, so there is always a lag of months between an event and its appearance in these tables. The demographics resource, which offers age and sex breakdowns, returned empty result sets for several straightforward parameter combinations when we tested it; verify it returns data for your countries and years before designing anything around it.

Known blind spots

Absence of evidence here is not evidence of absence. These are the conditions under which UNHCR Population Statistics will not show you something that is nevertheless real:

People who never enter a formal category are absent. Someone displaced across a border who does not claim asylum, is not registered, or lives in a state that does not register refugees is not counted anywhere in this database, and in several of the largest displacement situations that describes most of the people.
The main population resource shows stocks at year end, so a displacement crisis that begins and resolves inside a calendar year can leave almost no trace, and the peak of a movement is invisible between two annual snapshots.
Internal displacement coverage is partial by design. The idps field covers populations UNHCR reports on rather than all internally displaced people in a country, and using it as a national IDP figure will understate, sometimes drastically.
Statelessness is undercounted everywhere and undercounted most where it is deliberate. Identifying a stateless population requires a state willing to acknowledge that it has created one, so the countries with the largest problems frequently report the smallest numbers.
Category definitions have changed. Others of concern, other people in need of international protection and host community have been introduced and revised over time, so headline totals are not comparable across the full time series without reading the methodology and the footnotes.
A government that stops reporting produces a flat or falling series that looks like improvement. The database records what was reported; the footnotes flag many but not all such gaps, and an unexplained plateau should always be checked before it is interpreted.
Recognition of refugee status reflects the host state's law and politics, not the applicant's circumstances, so recognition rates for the same origin country vary by an order of magnitude between neighbouring states of asylum without any difference in the underlying risk.
Returns are recorded as events, not assessed as outcomes. A returned refugee figure says a return was recorded; it says nothing about whether the return was voluntary, safe or durable, and returns under duress appear identically to returns after a peace settlement.
Sub-national geography is absent from the main series. This is a country-pair database, and any map showing displacement inside a country needs a different source entirely.

Write the blind spot into the product. A statement that something “was not observed in UNHCR Population Statistics” is defensible; a statement that it “did not happen” is not, and the difference is what survives cross-examination.

Access, licensing and what you may do with it

Access model: Open — no account required

The API is open, unauthenticated and immediately usable: a plain GET against api.unhcr.org/population/v1/population/ with year and country filters returns JSON, and adding download=true returns the same result as CSV, which is often the faster route into a spreadsheet-based workflow. The documentation at api.unhcr.org/docs/refugee-statistics.html is a generated OpenAPI page listing every resource and parameter with worked examples in a dozen languages. One practical note worth knowing before you build: the human-facing Refugee Data Finder site on www.unhcr.org sits behind a bot-protection layer that returns 403 to non-browser clients, while the API host does not, so scripted collection should target api.unhcr.org and human research should use a browser. For microdata, including anonymised survey and registration datasets, the UNHCR microdata library is a separate service with its own access conditions, and for operational, sub-annual and situation-specific figures the operational data portal is the right place. Those three services answer different questions and are frequently confused with one another.

Licence

UNHCR publishes these statistics for public use and the practical expectation is attribution to UNHCR with the reference year and the data extraction date. UN agency terms of use typically distinguish non-commercial reuse from commercial exploitation and reserve the organisation's name and emblem, so if the output is a commercial product, check the current terms on the agency's site rather than assuming an open licence. Two conditions matter more than the legal text. First, figures carry footnotes, and reproducing a number without its qualification misrepresents the source even when it is technically accurate. Second, several categories in this database are politically contested, and presenting a UNHCR figure as UNHCR's assessment when it is in fact a government's own report is a misattribution the agency's own methodology is careful to avoid; your output should be equally careful.

Rate limits and fair use

No published quota is stated in the documentation and none should be assumed to be unlimited. The service is a public good funded by donor contributions; treat it accordingly. The practical guidance is to filter server-side rather than pulling the full matrix and discarding it, to use coo_all or coa_all deliberately because those switches expand the result set enormously, to page using the maxPages value returned in the envelope rather than guessing, and to use download=true for bulk pulls instead of paging JSON. Because the underlying figures change only annually, aggressive caching is not merely acceptable but correct: a full extract taken after the annual release is valid for a year. Identify yourself with a descriptive user agent and a contact address if you are collecting at any volume.

Licensing changes, and it changes without warning. A dataset that was free for research this year may not be free for commercial or evidential use next year. Confirm the current terms before you build a dependency on it, and record the terms you relied on alongside the data — the licence in force at the time of collection is part of the provenance.

Collecting it

How UNHCR Population Statistics is actually pulled, in the order you would set it up. Prefer the bulk or export interface over per-item lookups wherever one exists: it is kinder to the publisher, faster for you, and gives a reproducible snapshot rather than a series of point-in-time answers you cannot reconstruct later.

Method	Format	Cadence	Notes
Population resource, filtered	JSON	annual; re-pull after the yearly release	The workhorse. Filter by coo, coa and year range; remember that any dimension you do not filter on is aggregated away rather than returned.
CSV download flag	CSV	annual	Adding download=true returns the same query as CSV. Faster and less error-prone than paging JSON for large extracts, and it drops straight into analytical tooling.
Asylum applications and decisions	JSON	annual	Two separate resources that together support processing-rate and recognition-rate analysis. Carry procedure type, decision level and the persons-versus-cases flag or the numbers are not comparable.
Reference resources	JSON	occasional; re-pull yearly	The countries, regions and years lookups. Pull these first and store them: they resolve UNHCR codes to ISO3 and give you the authoritative list of what periods exist.
Footnotes resource	JSON	annual	Collect alongside every figure extract and store the association. A pipeline that drops footnotes has stripped the source's own caveats out of your product.
Companion resources	JSON	annual	The idmc and unrwa resources expose figures produced by other bodies under their own methodologies. Keep them separate from the main series rather than summing them into a single total.

Ingesting it into the platform

Every step below is idempotent and cursor-based: interrupt one and it resumes from where it stopped rather than duplicating rows or losing progress. Collection is recorded per source, so a feed that quietly stops publishing shows up as a stale timestamp instead of silently thinning your coverage.

Register the resources separately — In sources.php, register population, asylum-applications, asylum-decisions, solutions, idmc and unrwa as distinct feeds. They have different methodologies and different producers, and merging them at ingest destroys the distinction permanently.
Load the reference tables first — Pull the countries and regions lookups through import.php and store the UNHCR-to-ISO3 mapping as a resolvable dimension, so every downstream join uses one country identity rather than three.
Schedule against the annual release — Configure collect.php for an annual pull with a retry window around the publication period, and let cron.php own it. A daily poll of an annual dataset is wasted traffic and hides the one event you care about.
Store stocks and flows in different structures — During ingest.php, mark refugees, asylum-seekers, IDPs and stateless as end-of-year stocks and returns, applications, decisions and resettlement as within-year flows. Storing them in one undifferentiated numeric column guarantees someone will eventually add them together.
Attach footnotes to figures — Join the footnotes resource to the rows it qualifies and surface the qualification wherever the number is displayed, so an analyst sees the caveat at the point of use rather than in a methodology page they will not open.
Resolve to country entities — Run resolve-everything.php so that origin and asylum countries become the same country entities used elsewhere in the platform, letting displacement figures render on country.php and country-risk.php beside conflict, sanctions and economic indicators.
Correlate against conflict events — Use correlate.php to place the annual displacement series alongside conflict event data for the same origin country, which is where the lag structure between violence and movement becomes visible and testable.
Version and diff each release — UNHCR revises prior years as governments submit corrections. Diff each annual pull against the stored series and surface revised historical figures rather than silently overwriting, because a revised baseline changes every trend statement built on it.

Registered sources and their last-collected state are listed in sources.php, and the scheduled chain that keeps them current is in automation.php.

How it is wrong, and how to tell

Every dataset is wrong in characteristic ways. Knowing which ways is the difference between using a source and being used by one, and it is the part of source evaluation most often skipped because it is the part that takes work.

As official statistics go, this is a well-run series: methodology is published, figures are footnoted, revisions are made openly, and the API exposes the same numbers that appear in the agency's flagship reporting. The reliability question is therefore not about UNHCR's handling but about provenance. Each figure has a producer, and the producer is frequently the government of the country of asylum, whose incentives run in both directions: a state seeking burden-sharing support has reason to report generously, and a state denying that a displacement situation exists has reason to report nothing at all. UNHCR's own registration figures, produced where it registers refugees directly, are a different and generally more consistent class of data. The practical basis for judging a figure is therefore the footnote, the methodology note, and the behaviour of the series over time: a number that jumps by an order of magnitude, or one that stays identical for several years, is almost always telling you about a reporting process rather than about people. Comparability across countries is the weakest axis and comparability across years within one country is the strongest, which is the opposite of how most users treat the data.

Characteristic false positives

Stocks are read as flows. The refugees figure is a count of people present at year end, not the number who arrived that year; subtracting one year from the next gives net change, not arrivals, and conflates new displacement with returns, naturalisation, resettlement and deaths.
A reporting gap is read as a decline. When a government stops submitting figures, the series can flatten or fall, and the resulting graph shows an improvement that never happened. Check the footnotes and the reporting history before interpreting any downward move.
Recognition rates are computed with the wrong denominator. Including or excluding administratively closed decisions changes the rate substantially, and comparing a rate computed one way in one country against a rate computed the other way elsewhere is a routine and serious error.
The IDP figure is used as the national IDP total. It covers only the population UNHCR reports on, and in several major crises the IDMC figure exposed through a different resource is several times larger.
Category changes are read as population changes. The introduction and revision of the others-of-concern and other-people-in-need categories moves people between columns without anyone moving anywhere, and long time series across the headline total inherit those discontinuities.
Aggregation defaults are misread as filtered results. Any dimension not specified in the query is summed rather than returned, so a call intended to retrieve one country's figures but with a mistyped parameter returns a plausible global total instead of an error.
UNRWA-registered Palestine refugees are double-counted or dropped. They sit in a separate resource under a separate mandate, and combining datasets without deciding explicitly how to handle them produces totals that differ from every published figure.
Return figures are treated as evidence that conditions improved. A recorded return is an administrative event, and returns under coercion, from a host state closing camps, appear in exactly the same field as voluntary returns after a settlement.

None of these make the source unusable. They make it a source that requires corroboration before an assertion built on it goes into a product, which is true of every source and admitted by few.

Ageing

The published series ages in two distinct ways. Individual annual figures are historical facts about a reporting year and remain valid indefinitely as such, except that UNHCR revises prior years when governments submit corrections, so a value you cached two years ago may no longer match the current series. That is the quiet failure mode: a stale record here looks exactly like a fresh one and is discovered only by re-pulling and diffing. The more obvious ageing is currency. Because the data is annual and published with a lag, the most recent figure available is typically between six and eighteen months old at the moment you read it, which is an eternity in a fast-moving displacement crisis. For anything current, the annual database is the wrong instrument and the operational data portal, situation-specific reporting and partner agency figures are the right ones. Any dashboard presenting this series as a current picture should carry the reference year prominently, not as a footnote.

What this source feeds

A source is only worth what it lets you conclude. These are the disciplines that collect through it, the mission domains it serves and the data points it yields — every one is a tag, so you can follow any thread from here into the rest of the library.

Collected by these intelligence disciplines

Serves these mission domains

Yields these data points

Location / Coordinates

How each sector uses UNHCR Population Statistics

The same dataset is worked very differently depending on who you are, what authority you hold, and what you are ultimately producing. A military analyst is supporting a commander’s decision; a journalist is meeting a publication standard; an NGO caseworker is protecting a person. The records are shared — the constraints, thresholds and outputs are not.

🎖 Military and defence

For planning in and around a theatre, displacement figures are a proxy for two things a force cares about: the scale of population movement that will interact with operations and infrastructure, and the political weight a neighbouring state is carrying. The origin-and-asylum matrix shows where a population went, which is more operationally relevant than a national total, and the multi-decade series shows whether a border has absorbed movement before. Two limits are decisive. The data is annual and lagging, so it describes the situation a year ago and cannot support current operational planning. And it says nothing about where people are inside a country, so camp and route planning needs operational reporting rather than this series. Use it for context, framing and the long view; never for movement prediction.

🕵 National intelligence

The most useful analytical property is that this is a bilateral matrix maintained consistently for seventy years, which supports questions about state behaviour that are otherwise hard to ask: which states have historically absorbed movement from a given origin, how a host state's registration practice changed after a policy shift, whether a government's reported figures diverge from what neighbouring states and agencies report. Because most figures are government-supplied, a change in the reporting itself is an indicator worth watching. The dataset also supports honest calibration of forecasts: displacement responds to violence with a lag that is measurable in these series, and a shop that has never quantified that lag for its own areas of responsibility is guessing when it makes displacement predictions.

👮 Law enforcement

Chiefly relevant to immigration and border enforcement, human trafficking and smuggling investigations, and identity work. The asylum applications and decisions resources give a defensible picture of how a national system processed claims from a given origin country in a given period, which supports both policy analysis and individual case context. Treat the figures as aggregate context only: nothing here identifies a person, and it should never be used to draw inferences about an individual applicant. Where trafficking is the subject, note that this database counts protection categories, not exploitation, so a trafficking picture requires the specialist sources and the referral pathways that go with them, with victim identification and support taking precedence over intelligence value.

🔍 Private investigation and corporate security

Useful for country-risk work, workforce and supply chain assessments in host states, and for understanding the demographic pressures behind a client's operating environment. The host community and asylum-seeker figures are the ones that speak to local tension and service pressure, and the multi-year series distinguishes a long-standing hosting arrangement from a recent shock. Do not use this data in any way that touches individual displaced people: aggregate statistics about a vulnerable population are not a basis for locating, screening or profiling anyone, and a client request that heads in that direction should be declined rather than fulfilled from public data.

📰 Journalism and OSINT media

This is the citation of record for displacement numbers and the reason most headline figures are comparable at all. Two habits separate careful reporting from the rest. Always state the reference year, because the most recent published figure is usually a year old and readers assume it is current. And always check the footnote, because the qualification is frequently the story: a figure that is a government estimate, a figure that excludes a population everyone knows exists, or a figure unchanged for four years because nobody has counted. The bilateral matrix also supports better stories than the global total does, since it shows which specific countries are hosting people from a given conflict, and that is almost never the countries the coverage focuses on.

🌍 NGO, humanitarian and human rights

For humanitarian planning, advocacy and protection work this is the shared baseline that lets organisations argue from the same numbers, and its category structure maps directly onto programming eligibility. The critical professional habit is to distinguish the count from the need: people outside a registered category are not in the data and are frequently the most exposed, and a fall in a registered figure can reflect deregistration or camp closure rather than a resolution. Use the solutions resource carefully in advocacy, since a recorded return is not evidence of a safe or voluntary one and presenting it as such undermines protection arguments. Pair the annual series with your own field data and with IDMC's figures rather than treating any single number as the situation.

🎓 University and research

The seventy-year bilateral panel is a genuinely rare research asset and supports work in migration studies, political economy, international law and conflict studies. Three methodological points recur. First, the series is administrative, so measurement is a function of state capacity and policy, and any model that treats reported counts as observations of displacement needs to model reporting explicitly. Second, the category definitions have changed and the footnotes document the changes; a panel constructed without reading them will contain step changes that are pure artefact. Third, the API's aggregation behaviour, where unfiltered dimensions are summed rather than returned, has silently corrupted more than one dataset, so validate an extract against a published figure before building on it. The microdata library is the route to individual-level data, under its own access conditions and ethical review.

Playbook: working UNHCR Population Statistics end to end

A repeatable sequence from first pull to finished product. Each phase states what you are trying to establish, not merely what to click — the objective is a defensible chain of reasoning, not a completed checklist.

Phase 1 — Fix the question to a category before you query

Decide whether you are asking about people recognised as refugees, people with pending claims, people displaced inside a country, or people without a nationality. These are four different populations with four different measurement regimes, and a question phrased as displacement in general has no single answer in this database. Write the category down before you touch the API.

Phase 2 — Pull the reference tables and settle country identity

Retrieve the countries and regions resources first and decide whether you are working in UNHCR codes or ISO3, then set cf_type accordingly and stick to it. Mixed country coding is the most common cause of extracts that silently lose a country or merge two.

Phase 3 — Validate your first extract against a published figure

Take one country pair and one year, run the query, and check it against the same figure in UNHCR's published reporting. This five-minute step catches the aggregation trap, where an unfiltered dimension is summed and you receive a plausible number for the wrong thing.

Phase 4 — Establish the reporting history for every country in scope

Look at the full time series for each country before interpreting any part of it. Long flat runs, sudden step changes and missing years are reporting artefacts until proven otherwise, and identifying them at the start prevents you from building an argument on one.

Phase 5 — Read the footnotes and carry them forward

Pull the footnotes resource for your extract and attach the qualifications to the figures they belong to. A great many apparent anomalies are explained there, and any figure you publish without its footnote is a figure you have subtly misrepresented.

Phase 6 — Separate the stock question from the flow question

If the question is how many people are displaced, use the population resource. If it is how many people moved, arrived or were decided upon, use applications, decisions and solutions. Differencing annual stocks to infer arrivals is the single most common analytical error with this dataset and it silently nets out returns and resettlement.

Phase 7 — Reconstruct the origin-asylum matrix, not just the totals

The bilateral structure is the distinctive asset. Build the matrix for your origin country across all asylum countries and look at the distribution rather than the sum: it shows which borders absorbed movement, which neighbours reported nothing, and where a population went that the coverage never mentioned.

Phase 8 — Compare against IDMC and UNRWA rather than merging them

Pull the companion resources and place them beside the main series. Where UNHCR's IDP figure and IDMC's differ substantially, that gap is itself a finding about mandate and measurement, and collapsing it into one number destroys the information.

Phase 9 — Test displacement against violence with an explicit lag

Join the annual series to conflict event data for the same origin country and examine the timing. Displacement follows violence by a lag that varies by conflict and by border, and quantifying it for your area of responsibility converts a vague expectation into a usable planning parameter.

Phase 10 — Compute rates with a stated denominator

If you report recognition rates, processing rates or per-capita hosting burdens, write the denominator into the output. Decisions data distinguishes first instance from appeal, persons from cases, and governmental from UNHCR procedures, and a rate that does not say which it used cannot be compared with anyone else's.

Phase 11 — Decide what currency the product needs

If the audience will read the number as current, the annual database alone is not adequate and you must either label the reference year prominently or supplement with operational reporting. Making this decision explicitly, rather than by default, is what stops a year-old figure being presented as today's situation.

Phase 12 — Re-pull and diff before republishing

Prior years are revised as corrections come in. Before any update to a recurring product, re-pull the full series and diff it against the stored version, and tell your readers when a historical figure has moved. Silent revision of your own baseline is how a trend claim becomes indefensible.

The platform ships this as a step-checked workflow in playbooks.php, so progress is recorded against a case rather than held in someone’s head.

What to pair it with

No single source carries a finding. These are the datasets that corroborate, extend or contradict this one — and a source that contradicts is worth more than one that agrees, because it is the only thing that will tell you when you are wrong.

Source	Relationship	What it adds
Internal Displacement Monitoring Centre	extends	The broader and generally larger internal displacement series, with its own methodology covering conflict and disaster displacement. Essential wherever internal displacement is the subject rather than an aside.
UNHCR Operational Data Portal	extends	Situation-level, sub-annual and sub-national operational figures, which is where you go when the annual series is too slow or too coarse for the question.
UNHCR Microdata Library	extends	Anonymised survey and registration microdata under controlled access, for research questions the aggregate tables cannot answer.
IOM Displacement Tracking Matrix	corroborates	Independent, frequently sub-national and much more current displacement tracking, produced by a different agency with a different mandate and method.
UCDP Georeferenced Events	corroborates	The violence that drives displacement, geocoded and dated, which is what lets you test the lag between conflict intensity and movement.
UN World Population Prospects	prerequisite	The denominator for any per-capita hosting or displacement-share statistic, and the standard demographic baseline for the same countries.
UNRWA	extends	Registered Palestine refugees fall under a separate mandate and a separate agency, exposed through its own resource in this API. Handle explicitly rather than by accident.
Refugee Statistics API documentation	prerequisite	The generated OpenAPI reference for every resource and parameter. Read it before writing collection code, particularly the aggregation behaviour of unfiltered dimensions.

Legal, ethical and operational constraints

The published statistics are aggregate and contain no personal data, so data protection law does not bite on the API itself. It bites hard on everything adjacent. Displacement data concerns populations who are, by definition, at risk from at least one state, and any workflow that combines these aggregates with individual-level information, whether from registration systems, social media or field reporting, moves immediately into a regime where a lawful basis, a proportionality assessment and a data protection impact assessment are required in most jurisdictions, and where the consequences of error are refoulement or persecution rather than embarrassment. Second, using the data to support decisions about individuals, such as country-of-origin assessments in asylum adjudication, is a legitimate but consequential use in which the dataset's limits become material: an absence of reported refugees from a country is not evidence that the country is safe, and presenting it that way in an adjudication is both analytically wrong and, in several jurisdictions, legally challengeable. Third, respect the attribution and misattribution point: presenting a government-reported figure as UNHCR's assessment misstates the evidence.

Operational security

Querying an open, unauthenticated UN statistics API is close to the lowest-exposure collection activity in this catalogue. Your requests appear in server logs with a source address, timing and the country parameters you asked about, which in aggregate would reveal which displacement situations you are interested in, but the population of users asking those questions is large and heterogeneous and the signal is correspondingly weak. If interest in one specific origin-and-asylum pair is itself sensitive, pull a broader slice and filter locally, which is cheap here because the annual data volume is small. The genuine operational security consideration lies downstream: an internal product combining these aggregates with named individuals, camp locations or field reporting is a far more sensitive artefact than anything the API returns, and it should be classified and handled on the basis of what it becomes rather than what it was built from.

Two rules that hold regardless of jurisdiction. Collection that is lawful is not automatically proportionate, and a dataset assembled for one purpose does not carry consent for another. Where the records concern identifiable people, the question is not only whether you may hold the data but whether holding it serves the purpose you are accountable for.

Is it earning its place?

Sources accumulate. Feeds get added during an incident and are never reviewed again, and a decade later the pipeline is carrying dead weight that nobody dares remove. These are the measures that show whether UNHCR Population Statistics is contributing anything, and they are worth baselining now so the answer is available later.

Proportion of country-years in your extract that carry a footnote, which is a direct measure of how much of your series needs qualification before it can be quoted.
Number of countries in scope with a reporting gap, a long flat run or a step change in the last decade, tracked as a data-quality register rather than rediscovered each time.
Divergence between the UNHCR IDP figure and the IDMC figure for the same country and year, which measures how much of the internal displacement picture your chosen source is missing.
Lag in months between the reference year end and the date your pipeline actually ingested the release, which is the honest measure of how current your displacement picture is.
Count of historical figures revised at each annual pull, and their magnitude, as a measure of how stable the baseline underneath your recurring products is.
Share of derived rates published with an explicit denominator, which should be all of them and, in most organisations, is not.
Number of analytical products in which this annual series was presented alongside a clearly stated reference year, versus those where it was presented as the current situation.

Beware of volume. Indicator counts rise easily and say almost nothing. Unique contribution — findings this source produced that no other source in your stack would have — is the measure that matters, and it is usually far lower than anyone expects.

Tradecraft notes

The distinctions that separate a competent analyst from a fast one:

These are counts of legal categories, not counts of people in need. Every analytical error with this source ultimately traces to forgetting that sentence, and stating it explicitly in a product prevents the reader from making the same mistake.
Differencing stocks does not give you arrivals. Net change between two year-end figures nets out returns, resettlement, naturalisation and mortality, and reporting it as new displacement is wrong in a way that is very hard to see afterwards.
Check what the API aggregated away. Any dimension you did not filter on has been summed into your result, so a query that looks like a country query and returns a suspiciously large number is usually a global total.
The footnote is part of the figure. Extract it, store it, and display it beside the number, because the qualification is frequently more informative than the value.
Comparability across years within a country is far stronger than comparability across countries in a year. Design your comparisons accordingly, and treat cross-country league tables as the weakest thing this dataset can produce.
A stable number is suspicious. Populations move; reporting systems stall. A figure that has not changed in several years is usually a stale submission rather than a stable situation.
Recognition rates say more about the host state than about the origin country. Two neighbouring states can recognise the same population at wildly different rates, and reading the rate as evidence about conditions in the origin country inverts the causality.
Keep UNRWA and IDMC figures in their own lanes. They come from different mandates and different methods, and every serious total published from this database states explicitly how it handled them.
For anything current, this is the wrong instrument. The annual series is a historical record with a lag measured in months to years, and the operational portals exist precisely because it cannot answer today's question.

Questions analysts actually ask

Do I need an API key?

No. The population API at api.unhcr.org is open and unauthenticated, returns JSON by default and CSV with a download flag. The human-facing statistics website on www.unhcr.org sits behind bot protection and returns 403 to scripted clients, which catches people out; point collection at the API host and use a browser for the site.

Why does my query return one row with a huge number?

Because any dimension you do not filter on is aggregated rather than returned. A call without coo or coa gives you the global total for the year, not an error. Set the filters you mean, or use coo_all and coa_all deliberately, and validate the first extract against a published figure.

Is this the total number of displaced people in the world?

No. It is the number of people in UNHCR's statistical categories, mostly as reported by states. People outside a recognised category, unregistered, or in countries that do not report are not in these tables at all, and internal displacement is covered only for the populations UNHCR reports on rather than for every displaced person in a country.

How do I calculate a recognition rate?

Use the asylum-decisions resource, and decide explicitly whether administratively closed decisions belong in the denominator, whether you are counting persons or cases, and whether you mean first-instance or all-instance decisions. All three choices move the rate substantially, so publish the denominator alongside the rate or the number is not comparable with anyone else's.

Why do UNHCR and IDMC give different IDP numbers for the same country?

Because they are measuring different things under different mandates. UNHCR reports the internally displaced population it is concerned with; IDMC attempts a comprehensive national figure across conflict and disaster displacement. The gap is real and informative, and the API exposes IDMC figures through a separate resource so you can see it rather than lose it.

How current is the data, and what should I use if I need something newer?

The core series is annual, end-of-year, and published with a lag of months. For anything current, use the operational data portal, situation-specific reporting and partner agency figures such as IOM's displacement tracking. Always label the reference year in any product, because readers assume the number is today's.

Are the numbers ever revised?

Yes, prior years are revised as governments submit corrections and methodology is refined. Re-pull the full series rather than only the newest year, diff against your stored version, and tell downstream consumers when a historical figure has changed.

Can I get age and sex breakdowns?

The API documents a demographics resource, but in our testing it returned empty result sets for several straightforward year and country combinations. Verify that it returns data for your specific countries and years before designing an analysis around it, and treat demographic disaggregation as something to confirm rather than assume.

Does a fall in the refugee figure mean the situation improved?

Not on its own. It can mean return, resettlement or naturalisation, all of which are captured in the solutions resource, or it can mean deregistration, a camp closure, a definitional change or a government that stopped reporting. Check the solutions figures and the footnotes before attributing a decline to anything.

Standards, formats and interoperability

What this source speaks natively, and what it has to be translated into before a partner can consume it. Work that arrives in a recognised format is easier to defend, easier to hand over and easier to automate against:

The 1951 Refugee Convention and its 1967 Protocol, plus the 1969 OAU Convention and the 1984 Cartagena Declaration, define who counts as a refugee in these tables and why regional figures are not built on identical criteria.
The 1954 and 1961 Statelessness Conventions underpin the stateless category and explain why coverage depends on a state's willingness to acknowledge the population.
The International Recommendations on Refugee Statistics and the related guidance on internally displaced persons statistics, developed through the UN statistical system, are the methodological framework the database is aligned to.
UNHCR maintains its own country coding alongside ISO 3166 alpha-3, and the cf_type parameter switches between them; any join to external data must settle which is in use.
The API is a conventional REST service returning JSON with a pagination envelope, and supports CSV export through a download parameter, so it fits standard statistical tooling without special handling.
The Guiding Principles on Internal Displacement inform the IDP category conceptually, even though the operational coverage of that category is narrower than the principles imply.
Platform exports carry derived entities and indicators in STIX 2.1, MISP, CSV, JSON and JSONL, so displacement figures attach to the same country and case structures as any other observable.

References

Primary documentation and authoritative references for this source. Publishers revise and retire material, so treat the retrieval date as part of the citation and re-check before relying on any of it in a formal product.

Refugee Statistics API documentation — UNHCR. The generated reference for every resource and parameter, with worked examples. The authoritative statement of what the API does, including the aggregation behaviour that catches most new users.
Refugee Data Finder — UNHCR. The human-facing statistics site with the methodology section, definitions and published tables. Note that it blocks non-browser clients, so use it in a browser and collect from the API host.
UNHCR Operational Data Portal — UNHCR. Situation-level and sub-annual operational figures. The right source when the annual database is too slow or too coarse, and the place to check a current crisis against the historical series.
UNHCR Microdata Library — UNHCR. Anonymised survey and registration microdata under controlled access, with documentation of collection instruments. The route to individual-level research questions.
Internal Displacement Monitoring Centre — IDMC / Norwegian Refugee Council. The comprehensive internal displacement series, covering conflict and disaster displacement with published methodology. Read alongside the UNHCR IDP figures rather than instead of them.
IDMC displacement data — IDMC. The underlying country-level database and downloads, which is where the methodological difference from UNHCR's IDP figures becomes concrete.
IOM Displacement Tracking Matrix — International Organization for Migration. Independent, often sub-national and much more current displacement tracking. The best available cross-check on movement in an active crisis.
UNRWA — United Nations Relief and Works Agency. The separate mandate covering registered Palestine refugees, exposed through its own resource in this API and requiring explicit handling in any global total.
World Population Prospects — UN Department of Economic and Social Affairs. The standard population denominators for per-capita hosting statistics and demographic context for both origin and asylum countries.
Uppsala Conflict Data Program — Uppsala University. Geocoded organised violence, which is the driver most displacement analysis needs on the other axis of the chart.

Link integrity: every reference above was verified with a live request when this page was generated. Where a publisher had moved or withdrawn a document, the link was repointed at a preserved copy in the Internet Archive and marked as archived. Anything with no reachable copy anywhere had its link removed rather than left to rot — the source is still credited, it simply cannot be linked.

Put it into practice

The Quantus Intel threat intelligence platform operationalises this source: it registers each statistical resource as its own feed, keeps stocks and flows in separate structures, carries UNHCR's footnotes through to the point of display, and diffs each annual release so revised history is surfaced rather than silently absorbed.. Browse the full source catalogue, or follow any tag above into the rest of the library.