data/README.md

data/

Runtime data directory for UNHCR Refugee Statistics.

Structure

data/
├── scripts/
│   ├── unhcr_downloader.py    # Full UNHCR API downloader (all endpoints)
│   ├── enrich_downloader.py   # Targeted per-country enrichment downloader
│   ├── query_data.py          # Runtime query layer (used by agent tools)
│   └── refresh_data.py        # Staleness check + re-download
├── raw/                       # Raw API responses (gitignored, regenerate)
│   └── .gitkeep
└── processed/                 # Merged flat JSON per endpoint (gitignored)
    └── .gitkeep

Setup

cd data/scripts

# First run — downloads all UNHCR data (~5-7 min):
python3 unhcr_downloader.py --all

# Then enrich countries.json with live stats (~4 min):
python3 enrich_downloader.py
# Output: specs/data/countries_enriched.json

# Annual refresh:
python3 refresh_data.py

Data license

All UNHCR data is published under CC BY 4.0. Source: UNHCR Refugee Statistics API Attribution required in any public-facing use.