un-comtrade-sdk 1.0.3

Python SDK for the UN Comtrade (UNSD) trade statistics API

un-comtrade-sdk

Production-ready Python SDK for the UN Comtrade (UNSD) trade statistics API. Typed. Documented. Tested. Validated on every push to main.

Status

The latest stable release is published on PyPI. The same source builds cleanly on every push; CI is the gate. Releases are driven by git tags (v*.*.*) on main.

Quality gate	What it proves	Last run on main
Quality	ruff, mypy, automated test suite	passing
Documentation	mkdocs build --strict	passing
Package	python -m build (wheel + sdist), twine check	passing
Security	TruffleHog secret scan, pip-audit across Python 3.11–3.13	passing
Release	tag-driven PyPI publication (TestPyPI + production)	passing

Install

pip install un-comtrade-sdk

Check the import:

>>> import un_comtrade

If the import succeeds, the install worked. The package version is exposed via un_comtrade.__version__ and is also reported by the un-comtrade --version console script.

Quick start

from un_comtrade import ComtradeClient

# Reads UN_COMTRADE_KEY from the environment by default.
client = ComtradeClient()

# Reference metadata.
countries = client.metadata.get_countries()
classifications = client.metadata.get_classifications()

# Trade flows.
exports = client.trade.get_exports(reporter_code=699, period="2022")
imports  = client.trade.get_imports(reporter_code=699, period="2022")

The single public entry point is un_comtrade.client.ComtradeClient. Endpoints are grouped by domain: metadata, trade, etl, analytics, storage. See the SDK specification for the full surface.

A minimal CLI is shipped as the un-comtrade console script:

un-comtrade --version     # prints the installed version
un-comtrade metadata countries

Documentation

• API reference + cookbook — built with mkdocs from website/. Local preview:

  cd website && python -m mkdocs serve
  

• Design documents — docs/: specification, architecture, ADRs, ETL / storage / packaging / testing standards.

• Release notes — historical record of changes shipped in the v1.x series.

• Engineering change log — every CHG entry since project start.

Project metadata

Field	Value
Distribution name	un-comtrade-sdk
License	MIT
Python	>= 3.11
Classifier	Development Status :: 5 - Production/Stable
Latest release	GitHub Releases
Homepage	https://github.com/Horizon-Labs-Building-AI-Systems/un-comtrade-sdk
Repository	https://github.com/Horizon-Labs-Building-AI-Systems/un-comtrade-sdk
Issues	https://github.com/Horizon-Labs-Building-AI-Systems/un-comtrade-sdk/issues
Changelog	https://github.com/Horizon-Labs-Building-AI-Systems/un-comtrade-sdk/blob/main/docs/CHANGELOG.md
Release notes (v1.x series)	https://github.com/Horizon-Labs-Building-AI-Systems/un-comtrade-sdk/blob/main/docs/032_v1_RELEASE_NOTES.md
PyPI index	https://pypi.org/project/un-comtrade-sdk/
Documentation site	https://horizon-labs-building-ai-systems.github.io/un-comtrade-sdk/

License

MIT.