UNHCR displacement stocks
unhcr_get_populationRead-onlyIdempotent
Get UNHCR year-end displacement stocks (1951 to the latest year) by country of origin and/or asylum: refugees, asylum-seekers, other people in need of international protection, IDPs, stateless people, others of concern, and host communities, plus refugees and IDPs who returned during the year. Stocks count people in a situation on 31 December, not arrivals. Palestine refugees under UNRWA's mandate and IDMC's conflict-IDP estimate are separate series shown beside each row. Set include_nowcast for UNHCR's current-year estimate by asylum country; for sex and age breakdowns, use unhcr_get_demographics.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows returned inline, 1–500 (default 100). Sorting runs over the full result first; a larger result is staged as a dataframe where dataframes are enabled. | |
| stage | No | Stage the full result as a dataframe even when it fits inline, e.g. to join it with another unhcr_get_* result in unhcr_dataframe_query. Where dataframes are unavailable it is ignored, and the notice says so. | |
| asylum | No | Country of asylum — where people sought or hold protection; for returns, the country they returned from — as ISO3 codes (DEU, TUR), case-insensitive, same rules as origin. At most 50 codes. Omit to sum every asylum country into one row, or set expand to list each. | |
| expand | No | List every country, one row each, for a dimension that origin or asylum leaves unfiltered: origin, asylum, or both. Default none, where an unfiltered dimension is summed into one row. Expanding a dimension that origin or asylum already filters is rejected. | none |
| origin | No | Country of origin — where people fled from — as ISO3 codes (SYR, AFG), case-insensitive. ISO 3166 alpha-2 codes (SY) are rewritten to ISO3 and echoed in applied_scope. UNHCR's own codes (GFR) are rejected with the ISO3 to pass instead, and country names are rejected: resolve a name with unhcr_list_reference (topic countries, name_contains). Each listed code returns its own rows; codes are never summed together. At most 50 codes. Omit to sum every origin into one row, or set expand to list each. | |
| sort_by | No | Order of the full result before the inline cut. year (default) orders by year, then origin ISO3, then asylum ISO3; a count field orders largest first, nulls last. | year |
| year_to | No | Last year of the window. When omitted, the window runs to the latest published year (latest_year in the result). A year past the latest published year is clamped to it and the clamp is reported. | |
| year_from | No | First year of the window. When omitted, the window starts at the dataset's first year. A year before the dataset's first year is clamped to it and the clamp is reported; a window entirely outside the dataset's years is rejected. | |
| include_nowcast | No | Append UNHCR's latest monthly estimate of refugees and asylum-seekers by asylum country: one current-year snapshot, independent of the year window. The nowcast has no origin dimension, so it is skipped when origin lists codes. When origin lists no codes, a window entirely after the latest published year returns the nowcast alone instead of failing. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The limit that was applied. | |
| rows | No | Inline rows, sorted, up to limit. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Rows returned inline. | |
| notice | No | Guidance for this result: empty-result hints, year clamps, where the full set was staged, or how to narrow. | |
| dataset | No | Present when the full result was staged as a dataframe; read its columns with unhcr_dataframe_describe, then query it with unhcr_dataframe_query. | |
| measure | No | stock: people in a situation on 31 December; flow: events during the year. | |
| nowcast | No | Present when include_nowcast was set and origin lists no codes. | |
| complete | No | False when the server row cap stopped the upstream fetch; the notice says how many upstream rows were fetched and how to narrow. | |
| footnotes | No | UNHCR caveats matching rows of the full result, country-specific first; at most 20. | |
| truncated | No | True when rows were cut at limit. | |
| data_notes | No | How to read the counts: stock or flow, rounding, the meaning of null, caveats. | |
| total_rows | No | Rows in the full result before the inline cut. When complete is false, the result is built from only the upstream rows fetched before the cap, so rows and summed counts can fall short of the complete result. | |
| attribution | No | Attribution UNHCR requires when these figures are reused. | |
| latest_year | No | Newest year this dataset publishes. | |
| applied_scope | No | The scope actually sent upstream, including clamped years and code rewrites. | |
| footnotes_total | No | Caveats matching the full result, before the cap. |