Trade Map APIbeta.trademap.org ↗
Access ITC Trade Map goods and services trade statistics, HS/EBOPS codes, time series, and trade indicators for 200+ countries via 8 structured endpoints.
What is the Trade Map API?
The ITC Trade Map API provides 8 endpoints covering international goods and services trade data, including yearly time series, trade indicators (value, balance, growth rates), and full HS and EBOPS product classifications. The goods_time_series endpoint returns paginated import/export values by reporter country, partner, and HS code across a configurable year range, while goods_trade_indicators delivers VAL, BAL, GV5, and GV2 metrics for a given reference year.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/9f9021d2-26de-464e-a412-80acf4d30519/get_countries' \ -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 beta-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.
"""Walkthrough: Trade Map SDK — explore international trade data, bounded and re-runnable."""
from parse_apis.trade_map_api import (
TradeMap, TradeFlow, GoodsBreakdown, HsLevel, DataType, InvalidInput
)
client = TradeMap()
# List countries with trade data coverage
for country in client.countries.list(limit=3):
print(country.country_cd, country.label)
# Get goods trade time series for US exports, broken down by HS chapter
record = client.goodstraderecords.time_series(
country="842", trade_flow=TradeFlow.EXPORTS,
hs_level=HsLevel.CHAPTER, period_from="2020", period_to="2024",
limit=1
).first()
if record:
print(record.product_cd, record.reporter_cd)
for pv in record.data[:3]:
print(f" {pv.period}: {pv.value}")
# Get goods trade indicators by product for US imports
for ind in client.goodsindicatorrecords.list(
country="842", trade_flow=TradeFlow.IMPORTS,
by=GoodsBreakdown.BY_PRODUCT, limit=3
):
print(ind.product_cd, ind.country_cd, [iv.indicator_cd for iv in ind.data[:2]])
# Check data coverage with a typed error catch
try:
for entry in client.coverageentries.list(data_type=DataType.GOODS, limit=5):
print(entry.data_type, entry.nb_countries, entry.latest_period)
except InvalidInput as exc:
print(f"invalid input: {exc}")
print("exercised: countries.list / goodstraderecords.time_series / goodsindicatorrecords.list / coverageentries.list")
Returns all countries and territories recognized by Trade Map with their data coverage periods for goods (yearly, quarterly, monthly) and services. Each country includes first/last available period per data frequency. The full list is returned in a single response with no pagination.
No input parameters required.
{
"type": "object",
"fields": {
"total": "integer total number of countries",
"countries": "array of country objects with countryCd, label, and coverage period info"
},
"sample": {
"data": {
"total": 254,
"countries": [
{
"ti": false,
"nes": false,
"label": "United States of America",
"monthly": {
"lastPeriod": 202604,
"firstPeriod": 200001
},
"countryCd": "842",
"quarterly": {
"lastPeriod": 202601,
"firstPeriod": 200101
},
"yearly10D": {
"lastPeriod": 2024,
"firstPeriod": 2001
},
"yearly246": {
"lastPeriod": 2025,
"firstPeriod": 2001
},
"yearlyReexport": {
"lastPeriod": 2025,
"firstPeriod": 2001
},
"yearlyServices": {
"lastPeriod": 2024,
"firstPeriod": 2000
},
"quarterlyServices": {
"lastPeriod": 202304,
"firstPeriod": 200501
}
}
]
},
"status": "success"
}
}About the Trade Map API
Coverage and Classification
The API exposes the full ITC Trade Map dataset. The get_countries endpoint returns every country and territory with its trade data coverage period for both goods and services. The get_country_groups endpoint lists economic groupings (BRICS, OECD, LDCs), geographic regions (Africa, Asia), and customs unions (EU, MERCOSUR, ASEAN) with id, label, type, and note fields. Product classification is handled by two separate endpoints: get_products_hs delivers HS codes at the 2-digit (chapter), 4-digit (heading), and 6-digit (subheading) levels including revision metadata, while get_services_ebops returns EBOPS codes with productCd, label, displayCd, and maxLevel.
Goods Trade Data
The goods_time_series endpoint accepts a 3-digit reporter country code (country), a partner code (partner, use 000 for all partners), an HS product code or ALL, and a by parameter to pivot results either byProduct or byCountry. The hs_level parameter controls granularity at 2, 4, or 6 digits. Responses include paginated records arrays where each record carries reporterCd, partnerCd, productCd, and a data array of period/value pairs, alongside aggregateRecords for totals. Note that country=000 (World) is not supported as a reporter; a specific country code is required. The goods_trade_indicators endpoint follows the same parameter pattern and adds a refYear field to the response, with indicator codes VAL (trade value), BAL (trade balance), GV5 (5-year growth), GV2 (2-year growth), and GV5W (world 5-year growth).
Services Trade Data
The services_time_series endpoint mirrors the goods time series structure but uses EBOPS service codes instead of HS codes and a byService pivot option. A page_size parameter (max 500) controls response volume. The sort_dir parameter accepts desc or asc; using asc on large datasets is documented to cause timeouts, so desc or omitting the parameter is recommended. The get_coverage endpoint queries either goods or services via the data_type parameter and returns the number of reporting countries and the latest available period for each data frequency (yearly, quarterly, monthly).
The Trade Map API is a managed, monitored endpoint for beta.trademap.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when beta.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 beta.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?+
- Build an export market dashboard showing a country's top trade partners using
goods_time_seriesfiltered by reporter andbyCountry. - Track bilateral trade balances over time by pairing
goods_trade_indicatorsBAL values for a specific country-partner-product combination. - Generate HS chapter-level trade breakdowns by querying
goods_time_serieswithhs_level=2andby=byProduct. - Identify fast-growing product categories by sorting
goods_trade_indicatorson GV5 (5-year growth rate) for a given reporter country. - Map services trade flows across EBOPS categories using
services_time_serieswithby=byServicefor a specific country. - Populate a country-selector UI with trade coverage dates from
get_countriesso users know which periods are available. - Filter analysis to EU or ASEAN members by retrieving group membership from
get_country_groupsand cross-referencing with trade records.
| 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 `goods_trade_indicators` return, and how is it different from `goods_time_series`?+
goods_trade_indicators returns summary metrics for a single reference year (refYear): trade value (VAL), trade balance (BAL), 5-year value growth (GV5), 2-year value growth (GV2), and world 5-year growth (GV5W). goods_time_series returns annual period/value pairs across a range of years without computed growth indicators — it's for raw trend data rather than pre-calculated performance metrics.Can I use `country=000` to retrieve aggregate World-level trade data as the reporter?+
goods_time_series and goods_trade_indicators require a specific 3-digit reporter country code. The World aggregate (000) is only valid as a partner code meaning all partners combined. You can fork this API on Parse and revise it to add a dedicated world-aggregate endpoint if your use case requires it.Does the API expose quarterly or monthly trade data, not just yearly figures?+
get_coverage endpoint reports that quarterly and monthly data frequencies exist in the source (dataType codes Q and M alongside Y for yearly), but the time series endpoints (goods_time_series and services_time_series) return yearly figures. Sub-annual granularity is not currently served. You can fork this API on Parse and revise it to add endpoints targeting those frequencies.Are there any known timeout or performance issues to be aware of?+
services_time_series endpoint is documented to timeout when sort_dir=asc is used on large result sets. The recommended approach is to omit the parameter or set sort_dir=desc. Using page_size (max 500) and requesting specific service codes rather than ALL also reduces response size and latency.