UN Comtrade

What You're Getting

UN Comtrade is the definitive source for bilateral merchandise trade flows — exports and imports between country pairs at HS (Harmonized System) commodity code level, annual and monthly, 1962–present. Data dimensions: reporter country, partner country, trade flow (export/import), HS revision (H0/H1/H2/H3/H4/H5/H6), HS commodity code, year/period, trade value (USD), quantity, and net weight. The new Comtrade+ API launched 2023 replaced the legacy API.

Ingestion Strategy

Use the Comtrade+ API with a subscription key. Free tier allows 100 requests/day (limited to recent years and aggregate data). Paid subscription unlocks historical HS-6 level data. For bulk loads, request data by reporter country + HS revision to stay within response size limits.

import requests

headers = {"Ocp-Apim-Subscription-Key": "your_key"}
url = "https://comtradeapi.un.org/data/v1/get/C/A/HS"
params = {
    "reporterCode": "842",      # USA
    "period": "2022",
    "partnerCode": "156,276",   # China, Germany
    "cmdCode": "TOTAL",
    "flowCode": "X,M",          # exports and imports
    "customsCode": "C00",
    "motCode": "0",
    "maxRecords": 5000,
    "format": "JSON",
    "breakdownMode": "classic"
}
r = requests.get(url, params=params, headers=headers)

Rate Limits & API Details

• Free: 100 requests/day, max 500 records/request, 2020+ data only
• Subscription: higher limits, full historical HS-6 data, bulk data access
• API docs: comtradeapi.un.org/api-documentation
• Bulk data: comtradeplus.un.org — available for subscribers

Schema Stability

HS codes change every 5 years (H0=1988, H1=1996, H2=2002, H3=2007, H4=2012, H5=2017, H6=2022). Critical: store the HS revision alongside commodity codes — a code means different things across revisions. Country codes use UN M49 numeric codes. Reporter data quality varies enormously.

Data Quality Gotchas

• Mirror asymmetry: reported exports from A to B often don't match B's reported imports from A — often 10–30% discrepancy; document which direction you use
• HS revision breaks: time series spanning multiple HS revisions require concordance tables (UN provides these)
• Missing reporters: many countries have 1–3 year reporting lags; expect significant nulls in recent years
• Re-exports: some countries (e.g. Netherlands, Singapore) have high re-export volumes that inflate bilateral figures
• SITC vs HS: legacy data uses SITC classification; choose your classification standard and stick to it

Tool Compatibility

• Python: comtradeapicall PyPI package wraps the new API
• R: comtradr package (being updated for Comtrade+)
• Airbyte: no official connector
• dbt: model HS concordance as a dimension table for cross-revision analysis

Benchmarking Approach

US total merchandise exports should be ~$2.1T for 2022. Global total exports ≈ $24T. For any given reporter/year, verify total matches country's national trade statistics (customs authority). Alert if a major reporter (China, US, Germany, Japan) is missing for a period. Track reporter count per year — should be 150+ for recent years.