UNHCR Refugee Statistics API

Use in your agent

Load UNHCR refugee statistics into pandas and Parquet. Checked against the provider's documentation on Nov 2, 2026.

Access

• No account or key was required for the checked Refugee Statistics API endpoint.
• Use limit and page for pagination; download=true requests CSV where supported.

Request

curl 'https://api.unhcr.org/population/v1/population/?yearFrom=1951&yearTo=1952&limit=20'

Format

JSON pagination object with items containing year, origin and asylum codes and names, plus refugee, asylum-seeker, returnee, internally displaced, stateless and other population measures.

Load into pandas and Parquet

Needs Python 3 with requests, pandas and pyarrow.

"""UNHCR end-year population totals for 1951-1952 -> pandas -> Parquet."""
import requests
import pandas as pd

URL = "https://api.unhcr.org/population/v1/population/"
r = requests.get(URL, params={"yearFrom": 1951, "yearTo": 1952, "limit": 20}, timeout=60)
r.raise_for_status()
df = pd.DataFrame(r.json()["items"])
for col in ["refugees", "asylum_seekers", "returned_refugees", "idps",
            "returned_idps", "stateless", "ooc", "hst"]:
    df[col] = pd.to_numeric(df[col], errors="coerce")
df.to_parquet("unhcr_population_1951_1952.parquet", index=False)
print(len(df), "annual rows; years", int(df["year"].min()), "to", int(df["year"].max()),
      "; refugees total", int(df["refugees"].sum()))

Run by us on 2026-11-02 (python 3.13.5 | pandas 3.1.0 | pyarrow 26.0.0 | requests 2.34.2). Result: 2 annual rows; years 1951 to 1952 ; refugees total 4068939

Limits

• Rate limit: Not stated.
• The documented default page limit is 100 items.
• UNHCR reserves the ability to establish authentication, quotas, rate limits and access controls.

Quirks

• Population measures can arrive as a mix of JSON numbers and numeric strings; coerce columns explicitly.
• A dash in origin or asylum dimensions denotes an aggregate row rather than a country code.
• Country filters use UNHCR three-character codes by default; cf_type=ISO switches filtering to ISO3 codes.

Terms and attribution

• Portal datasets are CC BY 4.0 except where otherwise indicated; attribute UNHCR and indicate changes.
• Do not present transformed or derived data as official UNHCR information or imply endorsement.
• Do not attempt to identify, re-identify, profile or track individuals or protected groups from Portal data.

Sources

• https://api.unhcr.org/docs/refugee-statistics.html: “UNHCR’s Refugee Population Statistics Database contains information about forcibly displaced”
• https://api.unhcr.org/docs/refugee-statistics.html: “Get the result as a CSV file.”
• https://refugeedata.unhcr.org/en/terms-and-conditions-of-use/: “Users reusing datasets must provide appropriate attribution to UNHCR in accordance with the requirements of the Creative Commons Attribution 4.0 International Public License and must indicate whether changes have been made.”
• https://refugeedata.unhcr.org/en/terms-and-conditions-of-use/: “Refugee and displacement statistics may be revised, corrected, reclassified, delayed, updated, or withdrawn without notice.”