undata

UN data in Python, without the guessing.

Nine use cases, 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, a region such as "Southern Asia" or "Africa", or a UN group: "LDCs", "LLDCs", "SIDS". Wherever it asks for an indicator, an SDG number such as "3.1.1" works when one series reports it. Every function explains itself: help(un.get).

From a terminal

The same, without writing Python:

undata search "maternal mortality"
undata totals 3.1.1 World LDCs SIDS --latest
undata change 3.1.1 "Southern Asia" --start 2015 --end 2023 --describe
undata get 3.1.1 LDCs --years 2015-2023 --to maternal-mortality.xlsx
undata powerquery 3.1.1 "Southern Asia" > query.m

Every table has the same columns:

country  iso3  year  value  unit  indicator_name  indicator  source  source_url

The country list is the UN's own

Countries, regions and groups come from UN M49, the UN Statistics Division's standard, shipped with the package and checked against the UN's current table every night. Tables use official UN names, regions follow M49, and the LDC, LLDC and SIDS groups are the current UN lists (44, 32 and 53 countries), not the platform's older copies. Places the platform holds outside M49 are left out of every list, region and group; they can still be asked for by platform code, such as country/XKS.

Taking it to an AI assistant

table = un.latest("3.1.1", "LDCs", within=10)
un.ai_pack(table, "maternal-mortality.zip")  # upload, then paste prompt.md
print(un.for_ai(table, task="brief"))  # or paste this as one message

The pack holds data.csv, metadata.md (what each column means; each indicator's unit, source and citation; how complete the data is; the caveats) and prompt.md (rules that keep the assistant to these numbers, and a task). Tasks: explain, brief, trends, gaps, chart.

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, Greece or Slovenia (ESH, GRC, SVN, mistaken for command names). undata routes around all of them.

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.

Use cases

Nine requests as they arrive in UN work, each a runnable script in examples/ that ends with a sentence ready for the report:

They run against the live platform every night. The use-cases page shows each with its code, a chart, the real output and the sentence.

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.