Cookbook

The Cookbook is the executable source of runnable examples for the SDK. Every recipe is a self-contained Python file in recipes/ with a matching regression test in tests/test_recipes_*.py. Recipes are organised by category:

Category	Recipes	Difficulty range
Metadata	5	beginner
Trade	5	beginner
Analytics	5	beginner – intermediate
Storage	6	beginner – intermediate
CLI	6	beginner – intermediate
End-to-end	2	intermediate

The website does not duplicate recipe content. Each category page links to the recipe files in recipes/<category>/<file>.py and surfaces the recipe's frontmatter (title, difficulty, runtime, API-key flag) as a card.

Path

1. Metadata — country / partner / HS code / unit catalogues. No API key required.
2. Trade — annual / monthly flows, balance, tariffline. Requires UN_COMTRADE_KEY for the authenticated endpoints.
3. Analytics — country, partner, commodity, time-series, balance.
4. Storage — ETL pipeline, CSV / Parquet / DuckDB exports, reload, analytics on stored data.
5. CLI — drive every command from the terminal.
6. End-to-end — full pipelines from query to report.

Run a recipe

Each recipe is a single Python file:

python recipes/metadata/01_list_countries.py

Or with mock mode (no network):

UN_COMTRADE_MOCK=1 python recipes/metadata/01_list_countries.py

The regression tests live in tests/test_recipes_verification.py plus per-category modules; they enforce the recipe contract (no private imports, deterministic output, mock-mode execution).

Related API

• un_comtrade.ComtradeClient — the single public entry point used by every recipe.

Related Guides

• Getting Started — install the SDK.
• Python SDK → Trade — the most common recipe family.

Next steps

• Metadata — start with the simplest recipe (RECIPE-001).
• End-to-end — full pipelines from query to report.