Microproduct data guidebeginner

UNHCR Refugee Population Statistics

Official refugee, asylum-seeker, displacement, statelessness, return, and resettlement statistics for building humanitarian trend and flow tools.

Start the guide Open official source

At a glance

Difficulty
Beginner — comfortable for a first prototype
Size
Small · ≤0.1 GB
Formats
JSON, CSV
Access
API or Download
API key
Not required
Provider
UNHCR
Updates
Annual
Data terms
UNHCR terms of use for datasets

From source to product signal

Test a product idea in four steps

UNHCR's database reports forcibly displaced and stateless populations by year, origin, and asylum location. Start with refugees for two countries across five years. End-of-year stocks are not annual flows, categories differ, and some values are estimates or supplied by other authorities.

1

Check the setup

  • Python 3.10 or newer
  • A notebook environment such as Jupyter or Google Colab
  • An internet connection
2

Access the data

  1. 1.Read UNHCR's population-category definitions and select one measure.
  2. 2.Request a five-year window for a small country set using ISO codes.
  3. 3.Retrieve footnotes and retain the source year and country-role definitions.
Open official source
3

Run the Python example

Install the packages, then run the notebook cell.

python -m pip install pandas requests

import pandas as pd
import requests

response = requests.get(
    "https://api.unhcr.org/population/v1/population/",
    params={
        "yearFrom": 2020,
        "yearTo": 2024,
        "coo": "AFG,UKR",
        "coa_all": "true",
        "cf_type": "ISO",
        "limit": 100,
    },
    timeout=30,
)
response.raise_for_status()
population = pd.DataFrame(response.json()["items"])
print(population[["year", "coo_name", "refugees", "asylum_seekers"]].head(20))
4

Test a useful signal

Compare displacement stocks by origin

Compare reported refugee and asylum-seeker stocks originating from Afghanistan and Ukraine from 2020 through 2024.

  1. 01Retrieve the bounded years and retain origin, asylum, and population-category fields.
  2. 02Aggregate only compatible categories and review the associated footnotes before charting.
  3. 03Explain why stocks are not flows and how estimates, coverage, and category definitions limit comparison.

Dataset details

UNHCR is an intergovernmental source. Last verified 2026-08-13. Temporal coverage: 1951-present.

Theme

Demographics & Development

Domains

Forced DisplacementHumanitarian Development

Data types

Population DataTime Series

Tasks

Population AnalysisFlow AnalysisMapping

Geography

Global

Formats

JSONCSV

Provider

UNHCR

Data terms

UNHCR terms of use for datasets