---
name: unhcr-refugee-statistics-api-ingestion
description: "How to get UNHCR Refugee Statistics API data into a pandas DataFrame and Parquet: access, the request, the format, limits, quirks and terms."
---

# Load UNHCR refugee statistics into pandas and Parquet

Source entry: https://signal-lab-jet.vercel.app/datasets/unhcr-refugee-statistics-api
Provider: https://api.unhcr.org/docs/refugee-statistics.html
Checked against the provider's documentation: 2026-11-02

## 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
```bash
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.
```python
"""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.
- Terms page: https://refugeedata.unhcr.org/en/terms-and-conditions-of-use/

## 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."

## Help improve this skill
Missing a source, or see something to improve? Call the MCP tool suggest_source or feedback (or POST /api/suggest or /api/feedback). Reviewed ideas: https://signal-lab-jet.vercel.app/agent-suggestions

Information for educational purposes only. Free tiers, limits and licenses belong to the providers and may change; check the provider's own terms before using the data.