UN Comtrade Trade Normalizer

Fetch international trade statistics from the UN Comtrade database and turn the raw, code-heavy API responses into clean, human-readable records — with country names, ISO codes, HS commodity descriptions, flow direction labels and quantity units. No API key required.

The free Comtrade public preview API returns numeric codes (reporterCode, partnerCode, cmdCode) and leaves description fields empty. This actor resolves every code to a readable label, so you get "United States imports Coffee from Brazil — $1.4bn" instead of 842 → 0901 → 76.

What it does

• Resolves country codes → full country names + ISO2/ISO3 codes (200+ countries/territories, M49/Comtrade coding)
• Resolves HS commodity codes → chapter + commodity descriptions (all 99 HS chapters + 150+ curated 4-digit goods)
• Accepts keywords → "coffee", "crude oil", "cars", "wheat", "gold", "semiconductors" and 180+ more aliases
• Labels trade flows → Import / Export / Re-import / Re-export
• Labels quantity units → kilograms, litres, number of items, etc.
• Standardizes trade values → explicit tradeValueUsd, cifValueUsd, fobValueUsd fields

Input

Field	Type	Required	Description
reporter	string	✅	Reporting country (name, ISO code, or M49 code). e.g. "United States", "UK", "842"
partner	string	—	Trading partner, or "World" for all partners. Default "World"
commodity	string	✅	HS code (e.g. "0901") or keyword (e.g. "coffee")
flow	select	—	Import / Export / Re-import / Re-export. Default Import
startYear	integer	—	First year. Default 2022
endYear	integer	—	Last year (inclusive). Default 2023
maxResults	integer	—	Max records to return. Default 100

Example input

{
  "reporter": "United States",
  "partner": "World",
  "commodity": "coffee",
  "flow": "M",
  "startYear": 2021,
  "endYear": 2023,
  "maxResults": 50
}

Example output

{
  "reporter": "United States",
  "reporterIso3": "USA",
  "partner": "World",
  "flow": "Import",
  "year": 2023,
  "commodityCode": "0901",
  "commodity": "Coffee, whether or not roasted or decaffeinated; coffee husks and skins",
  "chapter": "09",
  "chapterDescription": "Coffee, tea, maté and spices",
  "tradeValueUsd": 8201729476.0,
  "cifValueUsd": 8201729476.0,
  "fobValueUsd": 7998011187.0,
  "quantity": 1389262732.253,
  "quantityUnit": "kilograms",
  "netWeightKg": 1389262732.253
}

Use cases

• Market research — track import/export volumes of any commodity by country over time
• Competitive intelligence — see who trades what with whom, and how volumes shift
• Commodity analysis — year-over-year trade flows for energy, agriculture, metals and electronics
• Supply chain / logistics — understand sourcing dependencies and trade corridors
• Academic & policy research — normalized, machine-readable trade data for analysis

Data source

Data is fetched live from the UN Comtrade public preview API (comtradeapi.un.org), the official United Nations international trade statistics database. Data covers annual merchandise trade at the HS commodity level. Attribution: United Nations Comtrade Database.

Note: the free preview API is rate-limited and returns annual data. The actor spaces requests and retries automatically. For the fullest historical coverage, a UN Comtrade subscription key unlocks the complete API.