Trade & Customs
UN Comtrade data via two sub-APIs:
- HS Code resolver — free, find commodity codes by name
- Comtrade queries — BYOK (Bring Your Own Key), requires your UN Comtrade subscription key
The HS resolver uses our own data and is always free. The Comtrade query endpoints require a Comtrade API key linked to your MarketDX account.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /v1/ext/hs/find | Resolve a commodity name to HS codes (free) |
GET | /v1/ext/comtrade/search | Bilateral trade flow series |
GET | /v1/ext/comtrade/top-partners | Top trading partners for a country + commodity |
GET | /v1/ext/comtrade/balance | Trade balance between two countries |
GET | /v1/ext/comtrade/top-traders | Largest global importers or exporters |
GET /v1/ext/hs/find
Resolve a commodity description to Harmonized System (HS) codes. Free — uses our own index, no Comtrade key required.
Supports both goods (HS chapters) and services (EBOPS).
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | ✅ | Commodity description (e.g. "electric vehicles", "semiconductor chips", "soybeans"). |
limit | integer | — | Max candidates. Default 15. |
revision | string | — | HS revision: HS2022 (default), HS2017, HS2012. |
type | string | — | goods (default, HS codes) or services (EBOPS). |
Find EV-related HS codes
GET /v1/ext/hs/find?q=electric+vehicles
Semiconductor services
GET /v1/ext/hs/find?q=chip+design+services&type=services
Response shape
{
"query": "electric vehicles",
"revision": "HS2022",
"candidates": [
{ "code": "8703.80", "description": "Motor vehicles — electric", "chapter": "87" },
{ "code": "8706", "description": "Chassis fitted with engines, for motor vehicles", ... }
]
}
GET /v1/ext/comtrade/search
:::info BYOK required Comtrade query endpoints require a UN Comtrade API key. Link your key in account settings. :::
Bilateral trade flow time series — how much a reporter country trades with a partner in specific commodity codes.
| Parameter | Type | Required | Description |
|---|---|---|---|
reporter | string | ✅ | ISO-2 country code of the reporting country (e.g. US, CN, DE). |
codes | string | — | Comma-separated HS codes to filter (e.g. 8703.80,8706). Omit for all commodities. |
partner | string | — | ISO-2 partner country. Default World (aggregated). |
flow | string | — | export (default) or import. |
freq | string | — | annual (default) or monthly. |
period | string | — | last10 (default annual), last12 (default monthly), or a specific year like 2023. |
mirror | string | — | true — use partner's reported data instead of reporter's. |
type | string | — | goods (default, HS) or services (EBOPS). |
US semiconductor exports to China (annual)
GET /v1/ext/comtrade/search?reporter=US&partner=CN&codes=8542&flow=export
Germany auto exports — monthly, last 12 months
GET /v1/ext/comtrade/search?reporter=DE&codes=8703&flow=export&freq=monthly
GET /v1/ext/comtrade/top-partners
Top trading partners for a country and commodity set, for a given year.
| Parameter | Type | Required | Description |
|---|---|---|---|
reporter | string | ✅ | Reporting country (ISO-2). |
codes | string | — | Comma-separated HS codes. Omit for all. |
flow | string | — | export (default) or import. |
period | string | — | latest (default), or a specific year. |
limit | integer | — | Number of partners to return. Default 10. |
Top 10 destinations for US agricultural exports
GET /v1/ext/comtrade/top-partners?reporter=US&codes=10,12&flow=export&limit=10
GET /v1/ext/comtrade/balance
Trade balance (exports minus imports) between a reporter and partner.
| Parameter | Type | Required | Description |
|---|---|---|---|
reporter | string | ✅ | Reporting country (ISO-2). |
partner | string | — | Partner country (ISO-2). Default World. |
codes | string | — | Comma-separated HS codes. Omit for all. |
period | string | — | latest (default), or a specific year. |
US-China trade balance
GET /v1/ext/comtrade/balance?reporter=US&partner=CN
US-China semiconductor trade balance
GET /v1/ext/comtrade/balance?reporter=US&partner=CN&codes=8542
GET /v1/ext/comtrade/top-traders
Largest global importers or exporters for a commodity set, optionally ranked by growth or streak rather than absolute value.
| Parameter | Type | Description |
|---|---|---|
codes | string | Comma-separated HS codes to analyze. Omit for all. |
flow | string | import (default) or export. |
scope | string | world (default) or a regional scope. |
rank_by | string | value (default) — by total trade value. growth — by CAGR. streak — by years of consecutive growth. |
order | string | desc (default) or asc. |
limit | integer | Number of countries to return. Default 10. |
min_value_usd | number | Minimum annual trade value (USD). Defaults to $1M for growth/streak, 0 for value. |
period | string | For value: latest (default). For growth: last5. For streak: last10. |
Largest EV importers globally
GET /v1/ext/comtrade/top-traders?codes=8703.80&flow=import&rank_by=value
Fastest-growing chip exporters (5-year CAGR)
GET /v1/ext/comtrade/top-traders?codes=8542&flow=export&rank_by=growth