undata

UN data in Python, without the guessing.

Ten examples, with real output →

Type a country's name, get a table. undata is a Python package for the UN System Data Commons, which holds statistics from 26 UN System entities. It is written for colleagues who need numbers for a report, not a course in APIs.

Alpha. It works today; the API may still change before 1.0. Unofficial. A Nerd Lab experiment, not affiliated with or endorsed by the United Nations. The data belongs to the agencies that publish it.

Three lines to a spreadsheet

pip install undata

import undata as un

table = un.get("undata/sdg/SH_STA_MORT.SEX--F", ["Bangladesh", "Viet Nam"])
un.save(table, "maternal-mortality.xlsx")  # data on one sheet, citations on the next

In Google Colab, run !pip install undata in the first cell. For the latest unreleased changes: pip install "git+https://github.com/nerd-factory/undata".

Don't know the indicator's id? un.search("maternal mortality") lists matching indicators with their names. Copy the id from the first column.

Everything on one screen

Wherever a function asks for countries you can write names the way you would in an email ("Viet Nam", "Vietnam", "VNM"), a list of them, or a region such as "Southern Asia" or "Africa". Every function explains itself: help(un.get).

Every table has the same columns:

country  iso3  year  value  unit  indicator_name  indicator  source  source_url

The careful parts are built in

• It never guesses a place. data.un.org's search box answers a question about "Bengal" with figures for the United States. undata stops and says it does not know "Bengal".
• Gaps are named, never zero. Countries without data are left out of the table and listed in a MissingDataWarning, so a chart cannot show them as zeros.
• UN names in, UN names out. Tables say Türkiye, Viet Nam and Côte d'Ivoire, whatever spelling you typed.
• The source is on every row. The same statistic can come from several agencies with different numbers.
• Mixed years are flagged. "Latest" means each country's own latest year; a MixedYearsWarning says when those differ.
• It works where other clients fail. The platform's firewall blocks Google's official datacommons-client (any POST body containing "select") and any GET request that mentions Western Sahara (ESH, mistaken for a shell command). undata routes around both.

Each behaviour is pinned by a test in tests/live/ that runs against the real platform every night and opens an issue if the platform changes. Most of them were found while writing the UN Data Commons Field Guide.

Examples

Ten runnable scripts in examples/: a first table, comparing a region, a whole continent, an SDG target to its numbers, gaps, names, the search box, sources, Excel and citations, and checking an indicator. They run against the live platform every night, and the examples page shows each with its real output.

For developers

The friendly functions sit on three layers you can use directly: undata.Transport (the only code that touches the network), undata._endpoints (one thin wrapper per API route), and undata.dcid (the identifier grammar). PLAN.md covers the design and the road to 1.0.

git clone https://github.com/nerd-factory/undata && cd undata
uv sync                     # Python 3.11+, installs dev tools
uv run pytest               # unit tests and doctests, offline
uv run pytest -m live       # pins the live platform's behaviour (network)
uv run ruff check . && uv run ruff format --check . && uv run mypy

See CONTRIBUTING.md. Questions that feel too basic are welcome in Nerd Lab Discussions; they are not too basic.

Licence

Code: MIT. Data fetched with it is governed by the UN Data Commons terms of use and by each contributing agency's own terms.