comtrade
by xippios
README.md
# xippios-comtrade
Typed Python client, MCP server and FastAPI routes for
[UN Comtrade](https://comtradeplus.un.org), part of the
[xippios SDK family](https://github.com/xippios). Names and semantics follow the
upstream documentation; every response carries release metadata (source, endpoint,
retrieved_at, published_at, vintage).
## Install
```bash
uv add xippios-comtrade # client only
uv add "xippios-comtrade[mcp]" # + MCP server
uv add "xippios-comtrade[http]" # + FastAPI router
```
Set `COMTRADE_API_KEY` in the environment. Nothing is read from files. The public
operations (`get_comtrade_releases`, `get_world_share`) and the reference files need no
key and send none.
## 30-second example
```python
from xippios.comtrade import get_counts, get_data
# Switzerland (reporter 757) exports to the World (partner 0) in 2023, all products.
query = {
"reporter_code": "757",
"partner_code": "0",
"period": "2023",
"cmd_code": "TOTAL",
"flow_code": "X",
}
get_counts("C", "A", "HS", **query).data # 32: every customs procedure and mode of transport
result = get_data("C", "A", "HS", **query)
total = next(r for r in result.data if (r.customs_code, r.mot_code) == ("C00", 0))
total.primary_value # Decimal('419922543423.509'); JSON: a number
result.meta.endpoint, result.meta.request # 'data/v1/get', the arguments above
```
Parameters are upstream's (`typeCode`, `reporterCode`, ...) in snake_case and take
upstream's codes, several of them comma-separated as upstream takes them (`"757,842"`).
Reporter and partner codes are UN Comtrade's, not ISO numeric: Switzerland is 757.
Every argument is checked before the call: coded ones (`type_code`, `cl_code`,
`flow_code`, `customs_code`, `mot_code`, `aggregate_by`, `breakdown_mode`) against
the lists packaged from upstream's reference files and spec (`xippios.comtrade.enums`;
`list_codes` gives each value with upstream's words for it),
`reporter_code` against the packaged copy of upstream's `Reporters.json`
(`reference/Reporters.json`) and `partner_code` and `partner2_code` against that of
`partnerAreas.json`, the others by shape. An unknown area, customs or transport code
raises `UnknownCode`, an `InvalidRequestError` naming the packaged list, its fetch date
and the closest code (`756` names `757`, Switzerland; `C16` names `C15`, Relief
consignments); any other mistake raises `InvalidRequestError` naming the closest valid
value.
```python
from xippios.comtrade import (
list_classifications,
list_codes,
list_commodities,
list_partners,
list_reporters,
)
list_reporters().data # 255 reporters, packaged with this version: no call
list_reporters(search="switz").data # code, ISO alpha-3 or name, any case: 757
list_partners().data # 310 partner areas, 0 World among them
list_commodities("HS", search="coffee").data # from 8,262 HS codes, fetched keyless once
list_codes("motCode").data[3] # MotCodeValue(mot_code='2100', text='Sea'): packaged
list_classifications("cmd:H6").data[0].variable # 'Product [HS 2022]': upstream's index
```
Four task-shaped slices on `data/v1/get` answer the common questions in one call each
(the series in one call per 12 periods), at the total of every breakdown, one row per
reporter × partner × product code × period. Areas are UN Comtrade's codes or ISO alpha-3
codes; `YYYY` periods ask for annual data, `YYYYMM` for monthly:
```python
from xippios.comtrade import (
get_bilateral_flows,
get_commodity_series,
get_top_partners,
get_world_trade,
)
get_bilateral_flows("CHE", "USA", "TOTAL,27", "2022,2023", "X").data # 4 rows
years = ",".join(str(year) for year in range(2010, 2024))
get_commodity_series("757", "27", "X", years).data # 14 years, two calls, by period
get_world_trade("27", "2023", "M").data[0].reporter_desc # 'China': largest first
[r.partner_desc for r in get_top_partners("CHE", "TOTAL", "2023", "X", 3).data]
# ['USA', 'Germany', 'China']: World, the total, is dropped
```
Release dates are per dataset, so they sit on the rows, not in `meta.published_at`.
Upstream prints `first_released`, `last_released`, `publication_date` and `date_release`
without a zone, so they are naive datetimes:
```python
from xippios.comtrade import (
get_comtrade_releases,
get_data_availability,
get_live_update,
get_metadata,
get_world_share,
)
[dataset] = get_data_availability("C", "A", "HS", reporter_code="757", period="2023").data
dataset.first_released, dataset.last_released # first publication and latest revision
notes = get_metadata("C", "A", "HS", reporter_code="757", period="2023").data[0].notes
[note.publication_date for note in notes] # "New Data", then each "Revised Data"
get_live_update().data # the 50 most recent releases, newest first
get_comtrade_releases().data # upstream's recent releases (newest first when recorded); keyless
[share] = get_world_share("C", "A", period="2023", reporter_code="757").data # keyless
share.world_share, share.last_released # Decimal('0.01651852126450239'), its release
```
Two Tools operations, which upstream's spec marks "EXPERIMENTAL - USE SPARINGLY", put
exports beside imports and a reporter's figures beside its partners' mirror figures:
```python
from xippios.comtrade import get_bilateral_data, get_trade_balance
ch = {"reporter_code": "757", "period": "2023", "cmd_code": "TOTAL"}
[row] = get_trade_balance("C", "A", "HS", partner_code="0", breakdown_mode="classic", **ch).data
row.primary_value_x, row.primary_value_m # Switzerland's 2023 exports and imports
row.primary_value_bal # upstream's "X - M", as sent
bilateral = get_bilateral_data("C", "A", "HS", partner_code="842", flow_code="X", **ch).data
bilateral.note # upstream's data-gap note: 'EXPERIMENTAL: We have good news! ...'
[row] = bilateral.data
row.primary_value, row.mirror_primary_value # exports to the USA; the USA's imports
```
Both need `reporter_code` or `partner_code`, and `cmd_code`, since upstream offers no
count to check a query's size first. A mirror of 0 is no sign of no trade: the mirror
depends on whether the partner reported. So `get_bilateral_data` returns upstream's
`note`, which counts the partners with a data gap without naming them, and its
`timestamp_requested`, with the rows: its `data` is one `BilateralData`, not a list.
A fifth slice, `get_mirror_flows`, asks getBilateralData the slices' way: one reporter and
one partner as codes or ISO alpha-3, single product codes, up to 12 periods of one
format, one flow. Each row holds the reporter's figures beside the partner's mirror of
them, and the result keeps the note:
```python
from xippios.comtrade import get_mirror_flows
mirror = get_mirror_flows("CHE", "USA", "27", "2022,2023", "X").data
mirror.note # 'EXPERIMENTAL: We have good news! There is no data gap ...'
[(r.period, r.primary_value, r.mirror_primary_value) for r in mirror.data]
# Switzerland's chapter 27 exports to the USA beside the USA's reported imports of them
```
`get_data` counts first with upstream's `countOnly`: a count of zero returns an empty
result without a second call, and a count above 100,000 raises `QueryTooLarge` with the
count before anything is fetched, because upstream would cut the answer at 100,000 rows
without saying so. A free key allows 1 call per second and 500 calls per day, and
`countOnly` calls count; the client spaces calls 1.5 s apart (upstream's gateway refuses
some calls spaced exactly 1 s apart) and counts no calls, so the daily quota is yours to
track: once upstream answers that it is spent, the client sends nothing more until the
time upstream names and raises `RateLimitError` instead.
## MCP
```json
{
"mcpServers": {
"comtrade": {
"command": "uvx",
"args": ["--from", "xippios-comtrade[mcp]", "xippios-comtrade-mcp"],
"env": { "COMTRADE_API_KEY": "..." }
}
}
}
```
Tools are read-only and named `comtrade_<verb>_<noun>`. Results are capped at
200 rows or 64 KB with a note on how to narrow the query; `comtrade_list_reporters` and
`comtrade_list_partners` have a cap of their own, 400 rows or 100 KB, so their whole
tables reach the agent. `comtrade_list_commodities` has the same cap, but a
classification is larger (8,262 HS codes), so its note says to search. All three take
`search`: `{"search": "switz"}` returns 757 Switzerland. `comtrade_get_world_share` has the
same cap too, so one period for every reporter (214 rows for 2023) reaches the agent
whole; its note says to narrow by `reporter_code` or `period`. `--http` serves streamable
HTTP instead of stdio.
## Status
| Upstream operation | Task function | MCP tool | Status |
| --- | --- | --- | --- |
| `data/v1/get/{typeCode}/{freqCode}/{clCode}` with `countOnly=true` | `get_counts(type_code, freq_code, cl_code, *, reporter_code=, partner_code=, ...)` | `comtrade_get_counts` | alpha |
| `data/v1/get/{typeCode}/{freqCode}/{clCode}` | `get_data(type_code, freq_code, cl_code, *, reporter_code=, partner_code=, ...)` | `comtrade_get_data` | alpha |
| `data/v1/getDa/{typeCode}/{freqCode}/{clCode}` | `get_data_availability(type_code, freq_code, cl_code, *, reporter_code=, period=, published_date_from=, published_date_to=)` | `comtrade_get_data_availability` | alpha |
| `data/v1/getMetadata/{typeCode}/{freqCode}/{clCode}` | `get_metadata(type_code, freq_code, cl_code, *, reporter_code=, period=)` | `comtrade_get_metadata` | alpha |
| `data/v1/getLiveUpdate` | `get_live_update()` | `comtrade_get_live_update` | alpha |
| `public/v1/getComtradeReleases`, keyless | `get_comtrade_releases()` | `comtrade_get_comtrade_releases` | alpha |
| `public/v1/getWorldShare/{typeCode}/{freqCode}`, keyless | `get_world_share(type_code, freq_code, *, period=None, reporter_code=None)` | `comtrade_get_world_share` | alpha |
| `data/v1/get/C/{A,M}/{clCode}`, total row, one reporter and partner | `get_bilateral_flows(reporter, partner, commodities, periods, flow, *, cl_code="HS")` | `comtrade_get_bilateral_flows` | alpha |
| `data/v1/get/C/{A,M}/{clCode}`, total row, partner World, 12 periods per call, at most 120 | `get_commodity_series(reporter, commodity, flow, periods, *, cl_code="HS")` | `comtrade_get_commodity_series` | alpha |
| `data/v1/get/C/{A,M}/{clCode}`, total row, every reporter, partner World | `get_world_trade(commodity, period, flow, *, cl_code="HS")` | `comtrade_get_world_trade` | alpha |
| `data/v1/get/C/{A,M}/{clCode}`, total row, every partner, ranked | `get_top_partners(reporter, commodity, period, flow, n, *, cl_code="HS")` | `comtrade_get_top_partners` | alpha |
| `tools/v1/getTradeBalance/{typeCode}/{freqCode}/{clCode}` | `get_trade_balance(type_code, freq_code, cl_code, *, reporter_code=, partner_code=, cmd_code=, ...)` | `comtrade_get_trade_balance` | alpha; experimental upstream |
| `tools/v1/getBilateralData/{typeCode}/{freqCode}/{clCode}` | `get_bilateral_data(type_code, freq_code, cl_code, *, reporter_code=, partner_code=, cmd_code=, flow_code=, ...)`, returns `BilateralData` (`note`, `timestamp_requested`, the rows as `data`) | `comtrade_get_bilateral_data` | alpha; experimental upstream |
| `tools/v1/getBilateralData/C/{A,M}/{clCode}`, one reporter and partner, at most 12 periods | `get_mirror_flows(reporter, partner, commodities, periods, flow, *, cl_code="HS")`, returns `MirrorFlows` (`note`, `timestamp_requested`, the rows as `data`) | `comtrade_get_mirror_flows` | alpha; experimental upstream |
| `files/v1/app/reference/Reporters.json`, packaged | `list_reporters(search=None)` | `comtrade_list_reporters` | alpha |
| `files/v1/app/reference/partnerAreas.json`, packaged | `list_partners(search=None)` | `comtrade_list_partners` | alpha |
| `files/v1/app/reference/{clCode}.json`, keyless | `list_commodities(cl_code, search=None)` | `comtrade_list_commodities` | alpha |
| `files/v1/app/reference/` code lists and the spec's enums, packaged | `list_codes(param)` | `comtrade_list_codes` | alpha |
| `files/v1/app/reference/ListofReferences.json`, packaged | `list_classifications(category=None)` | `comtrade_list_classifications` | alpha |
All nineteen are covered in 0.2.0: twelve came with 0.1.0, the first release, and
`get_trade_balance`, `get_bilateral_data`, `get_mirror_flows`, `get_comtrade_releases`,
`get_world_share`, `list_codes` and `list_classifications` were released in 0.2.0. Alpha:
the public surface may change in a minor version before 1.0; `CHANGELOG.md` lists every
change.
## Upstream terms and attribution
Data comes from UN Comtrade (https://comtradeplus.un.org), on the terms upstream states
for it in its [Policy on Comtrade Data Use](https://uncomtrade.org/docs/policy-on-comtrade-data-use/),
under which use of the data is subject to the license agreement at
https://comtrade.un.org/licenseagreement.html; this package adds no rights to it.
Documentation snapshot and its attribution: `docs/upstream/FETCHED.md`.
## Licence
Apache-2.0. See [LICENSE](LICENSE).
This server cannot be deployed
Maintenance
ActivityNo data
ResponsivenessOutdated data