Trade Map APItrademap.org ↗
Access ITC Trade Map data via API: bilateral trade flows, HS product time series, trade indicators, and country data availability across 200+ countries.
What is the Trade Map API?
This API exposes 5 endpoints covering ITC Trade Map's global trade statistics database, including export values, trade balances, annual growth rates, and bilateral product-level flows. The get_trade_indicators endpoint returns ranked exporter lists with value, balance, and growth for any HS code and reporter-partner combination. Alongside it, endpoints for yearly time series, product breakdowns, bilateral trade, and data availability give structured access to the full range of Trade Map reporting.
curl -X GET 'https://api.parse.bot/scraper/ce6950bd-1895-499a-828c-3af9bf6a7c80/get_trade_indicators?hs_code=TOTAL&trade_flow=2&reporter_code=842' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace trademap-org-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.itc_trade_map_api import TradeMap, TradeFlow, HsLevel
trade_map = TradeMap()
# Construct a Country for the USA
usa = trade_map.country(code="842")
# Get trade indicators for US exports of all products
for indicator in usa.indicators(trade_flow=TradeFlow.EXPORT, hs_code="TOTAL"):
print(indicator.exporters, indicator.share_in_world_exports_pct)
# Get yearly time series for US imports
for ts in usa.time_series(trade_flow=TradeFlow.IMPORT, hs_code="TOTAL"):
print(ts.exporters, ts.values_by_year)
# Get products imported by USA at 2-digit HS level
for product in usa.products(trade_flow=TradeFlow.IMPORT, hs_level=HsLevel.CHAPTER):
print(product.code, product.product_label, product.values_by_year)
# Get bilateral trade between USA and China
for bt in usa.bilateral(trade_flow=TradeFlow.IMPORT, partner_code="156", hs_code="TOTAL"):
print(bt.product_code, bt.product_label, bt.values)
Retrieve trade indicators (export value, trade balance, growth, share, concentration) for a specific product and reporter country. Returns a list of exporting countries ranked by export value. Each record includes the exporter name, value exported, trade balance, annual growth rates, world export share percentage, average distance of importing countries, and concentration index. Use trade_flow to switch between export and import perspectives. Paginates as a single page containing all ranked countries.
| Param | Type | Description |
|---|---|---|
| hs_code | string | HS product code (e.g. '8471' for computers). Use 'TOTAL' for all products aggregated. |
| trade_flow | string | Trade flow direction. '2' for Export, '4' for Import. |
| partner_code | string | Partner country numeric code to filter results. Empty string for all partners. |
| reporter_code | string | Reporter country numeric code (e.g. '842' for USA, '276' for Germany, '156' for China). |
{
"type": "object",
"fields": {
"data": "array of objects, each containing Exporters (country name), Value exported in YYYY (USD thousand), Trade balance in YYYY (USD thousand), Annual growth in value between YYYY-YYYY (%), Share in world exports (%), Average distance of importing countries (km), Concentration of importing countries"
},
"sample": {
"data": {
"data": [
{
"Exporters": "World",
"Share in world exports (%)": "100",
"Concentration of importing countries": "0.04",
"Trade balance in 2025 (USD thousand)": "-171,727,803",
"Value exported in 2025 (USD thousand)": "25,636,648,695",
"Annual growth in value between 2021-2025 (%)": "3",
"Annual growth in value between 2024-2025 (%)": "8",
"Average distance of importing countries (km)": "5,103"
},
{
"Exporters": "China",
"Share in world exports (%)": "14.7",
"Concentration of importing countries": "0.04",
"Trade balance in 2025 (USD thousand)": "1,197,126,430",
"Value exported in 2025 (USD thousand)": "3,776,380,766",
"Annual growth in value between 2021-2025 (%)": "2",
"Annual growth in value between 2024-2025 (%)": "6",
"Average distance of importing countries (km)": "6,525"
}
]
},
"status": "success"
}
}About the Trade Map API
What the API covers
The API surfaces trade data organised around four core query shapes: country-level trade indicators, yearly time series, product breakdowns by country, and bilateral trade between two specific countries. All monetary values are denominated in USD thousands. HS codes can be supplied at the 2-, 4-, or 6-digit level, and trade flow direction is controlled with a simple trade_flow parameter ('2' for exports, '4' for imports).
Endpoint details
get_trade_indicators accepts an hs_code, trade_flow, reporter_code, and optional partner_code, returning an array of exporting countries ranked by export value. Each record includes the exporter name, value exported for the latest available year, trade balance, and annual growth rate — the fields needed to benchmark one country's position against peers.
get_yearly_time_series uses the same four parameters but pivots the response to show value columns for each recent year, making it straightforward to track directional changes in trade flows over time. get_products_by_country accepts a reporter_code and hs_level ('2', '4', or '6') and returns HS code strings alongside product labels and per-year value columns — useful for profiling a country's full export or import basket.
get_bilateral_trade takes both a reporter_code and a partner_code together with an hs_code, and returns product-level rows that include reporter imports from the partner, partner exports to the world, and reporter imports from the world across recent years. This three-column structure lets you calculate the partner's share of the reporter's total imports for each product. get_data_availability requires no inputs and returns a matrix of country rows with year columns (2021–2025), where values of 0, 1, or 2 indicate no data, mirror data only, or reported data respectively.
Data identifiers
Countries are referenced by numeric codes throughout ('842' for the USA, '156' for China, '276' for Germany). The special value 'TOTAL' for hs_code aggregates across all products. Check get_data_availability first when working with smaller or less-reported economies to understand whether the years you need have reported data or only mirror estimates.
The Trade Map API is a managed, monitored endpoint for trademap.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when trademap.org changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official trademap.org API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Identify which countries are the top exporters of a given HS product and compare their trade balances using
get_trade_indicators - Build historical trend charts for a country's exports of a specific product across multiple years via
get_yearly_time_series - Profile a country's full import or export basket at the 2-, 4-, or 6-digit HS level with
get_products_by_country - Calculate a trading partner's share of a country's total imports for specific product categories using
get_bilateral_trade - Screen data coverage before analysis with
get_data_availabilityto distinguish reported data from mirror estimates - Monitor annual growth rates and concentration metrics across exporting nations for competitive market research
- Supply chain mapping — trace which country pairs have significant bilateral flows for a given product code
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does ITC Trade Map have an official developer API?+
What does `get_bilateral_trade` return that `get_trade_indicators` doesn't?+
get_trade_indicators ranks all exporting countries for a product globally. get_bilateral_trade focuses on a specific reporter-partner pair and returns three separate value series per product: the reporter's imports from that partner, the partner's total exports to the world, and the reporter's total imports from the world. This lets you compute the partner's penetration share of the reporter's market at the product level.How granular are the HS product codes supported?+
get_products_by_country accepts a hs_level parameter of '2' (HS chapters), '4' (headings), or '6' (subheadings). For the other endpoints, any HS code string can be passed, or 'TOTAL' to aggregate across all products. Sub-6-digit national tariff line codes are not currently supported.Does the API expose quantity data (tonnes, units) alongside value data?+
How do I know whether a country's data for a given year is reliable?+
get_data_availability returns a matrix covering years 2021–2025 with a code per country: 0 means no data, 1 means only mirror data (estimated from partner reports), and 2 means the country itself has reported data. For analysis requiring primary-source figures, filter to countries showing code 2 for the years in scope.