Data dictionary
Observation columns
| Column | Definition |
|---|---|
| id | Stable observation identifier. Separate sources retain separate identifiers. |
| country_slug | Canonical country identifier; global denotes a source-reported global observation, not a calculated sum. |
| metric_key | Semantic measure identifier. Geography, population coverage and reporting period remain source-specific. |
| value | Exact source numeric value stored and exported as decimal text, including in XLSX. No rounding or aggregation. |
| unit | Unit reported by the source, such as people, percent or a named currency. Do not combine unlike units. |
| source_org | Organization responsible for the cited observation. |
| source_dataset_name | Dataset or publication identifying the source observation. |
| source_url | Direct HTTPS citation for the observation and its methodology. |
| reference_date | Date the source says the figure applies to (YYYY-MM-DD), not the date we downloaded it. |
| retrieved_at | Observed retrieval timestamp in ISO 8601, including timezone. Not an editorial update date. |
| notes | Source qualifications, scope, methodology and correction context; nullable. |
One row is one source observation. Reference dates and retrieval times serve different purposes; conflicting observations stay separate.
Metrics and population definitions
- asylum_seekers
People seeking international protection whose claim has not yet been determined. Not every asylum-seeker will be recognized as a refugee.
UNHCR: asylum-seekers- forcibly_displaced
Source-defined population forcibly displaced by persecution, conflict, violence, human-rights violations or events seriously disturbing public order. Included categories and deduplication follow the cited UNHCR statistical series; do not sum country totals.
UNHCR: refugee statistics methodology- idps
People forced or obliged to leave their homes or habitual residence because of conflict, violence, human-rights violations or disasters, without crossing an internationally recognized state border. Stocks and new displacement movements are not interchangeable.
Guiding Principles on Internal Displacement, introduction, paragraph 2- other_in_need_of_international_protection
People outside their country or territory of origin, typically forcibly displaced across international borders, who have not been reported as asylum-seekers, refugees or people in refugee-like situations but who likely need international protection. Not part of the refugee figure.
UNHCR: refugee statistics definitions- people_in_need
People assessed as needing humanitarian assistance under the cited humanitarian needs analysis. Scope and severity thresholds are specific to each country assessment; this is not a synonym for displaced population.
OCHA: humanitarian needs and response plans- refugees_abroad
Refugees recorded by country of origin outside that country. The Convention definition concerns well-founded fear of persecution and inability or unwillingness to obtain national protection. Coverage of wider protection categories depends on the dataset.
UNHCR: refugee definition- refugees_hosted
Refugees recorded by country of asylum or residence. Use the same refugee definition as the cited series; origin and host-country totals describe different geographic perspectives.
UNHCR: refugee definition- returned_idps
IDPs who were beneficiaries of UNHCR protection and assistance and who returned to their areas of origin or habitual residence during the calendar year. A yearly flow, not a cumulative total.
UNHCR: refugee statistics definitions- returned_refugees
Former refugees who returned to their country of origin, spontaneously or in an organized fashion, but are yet to be fully integrated. UNHCR statistics count only refugees who returned during the calendar year, so this is a yearly flow, not a cumulative total.
UNHCR: refugee statistics definitions- returnees
Previously displaced people who have returned to their place of habitual residence under the cited DTM operation’s criteria. Country operations may distinguish returns from abroad and internal returns. Return does not by itself establish a durable solution; use the dataset-specific definition.
IOM DTM: Sudan return-monitoring operational definition- stateless
Persons not considered as nationals by any State under the operation of its law (1954 Convention relating to the Status of Stateless Persons, Article 1). UNHCR statistics also include people with undetermined nationality. Some stateless people are also displaced and counted in displacement figures.
UNHCR: refugee statistics definitions- unrwa_registered_refugees
Palestine refugees registered with UNRWA: persons whose normal place of residence was Palestine between 1 June 1946 and 15 May 1948 and who lost both home and means of livelihood as a result of the 1948 conflict, plus eligible descendants. Distinct from refugees under UNHCR's mandate.
UNRWA: Palestine refugees