Bilateral Trade Statistics Database — UN Comtrade

Pull bilateral merchandise trade statistics straight from UN Comtrade, the UN's official global trade database. Returns reporter/partner country pairs, annual or monthly periods, import/export flows, and HS commodity detail from chapter level down to 6-digit subheadings — with every row carrying human-readable country and commodity names instead of raw codes.

---

UN Comtrade Scraper Features

• Walks the full reporter x partner x period x flow matrix in one run — pull one country's entire trade book, or the whole dataset, without scripting hundreds of individual queries.
• Selects any combination of 243 reporting countries and 292 trading partners by name or ISO3 code.
• Covers both annual and monthly periods, going back decades.
• Supports Import, Export, Re-Import and Re-Export flows, selectable independently.
• Returns HS commodity detail at four levels: Total, 2-digit chapter, 4-digit heading, and 6-digit subheading.
• Ships human-readable reporter, partner, flow, and commodity names on every row — no code lookup tables required on your end.
• Flags whether a figure was directly reported by the country or estimated/mirrored from its trading partner, so you can tell a filed number from an estimate.

---

Who Uses UN Comtrade Trade Data?

• Trade analysts and economists — build country-level import/export models, track trade balances, or study commodity flows over time.
• Supply chain and sourcing teams — size a country's export capacity for a given HS category before committing to a lane.
• Import/export compliance teams — cross-check declared trade values against the official record. It's the same database customs brokers reference, minus the manual query-building.
• Market researchers — quantify a country's dependence on a trading partner for a specific commodity, or spot shifts in trade flows year over year.
• Journalists and policy researchers — pull the underlying figures behind a trade-balance headline, with the reported-vs-estimated flag attached.
• Data teams building trade dashboards — feed a structured, joined dataset directly into a BI tool instead of post-processing raw codes.

---

How the UN Comtrade Scraper Works

1. Pick your reporters, partners, years, flows, and commodity detail level — or leave any of them blank to include everything available.
2. The scraper walks every combination of your selections, pacing requests to stay within the data source's rate limits.
3. Each result is joined against the official reference tables for reporter names, partner names, and commodity descriptions, then saved as a clean row.
4. The run stops once it hits your maxItems cap or its timeout — pass the resumeCursor from the output back in to keep going from exactly where it left off.

---

Input

{
  "reporters": ["USA"],
  "partners": ["CHN"],
  "flows": ["M", "X"],
  "freqCode": "A",
  "classificationLevel": "AG2",
  "startYear": 2023,
  "endYear": 2023,
  "maxItems": 1000
}

Field	Type	Default	Description
maxItems	integer	100	Maximum records to save. 0 or blank pulls without a cap, bounded only by the run's timeout.
reporters	array	[] (all 243)	Reporting countries by ISO3 code (e.g. USA, CHN, DEU). Empty means every reporter UN Comtrade publishes.
partners	array	[] (all 292)	Trading partners by ISO3 code. Empty means every partner UN Comtrade publishes.
flows	array	["M", "X"]	Trade flows: M (Import), X (Export), RM (Re-Import), RX (Re-Export).
freqCode	string	"A"	A for annual periods, M for monthly.
classificationLevel	string	"AG2"	Commodity detail: TOTAL, AG2 (HS chapter), AG4 (HS heading), or AG6 (HS subheading).
startYear	integer	2023	Earliest year to include.
endYear	integer	2023	Latest year to include (inclusive).

Leaving reporters and partners both blank with the default classificationLevel pulls the full bilateral matrix for the selected years — a large, complete corpus rather than a single lookup.

Resuming a large crawl

Every run emits a resumeCursor value in its Output. To continue a crawl that stopped — because it hit maxItems, a spend cap, or your own timeout — start a new run with the same input plus that resumeCursor. You are not re-charged for records you already received. Resume promptly: the previous run's queue expires with your account's data-retention window.

---

UN Comtrade Scraper Output Fields

{
  "reporter_code": 842,
  "reporter_iso": "USA",
  "reporter_desc": "USA",
  "partner_code": 156,
  "partner_iso": "CHN",
  "partner_desc": "China",
  "period": "2023",
  "ref_year": 2023,
  "ref_month": 52,
  "freq_code": "A",
  "flow_code": "M",
  "flow_desc": "Import",
  "classification_code": "H6",
  "cmd_code": "84",
  "cmd_desc": "Nuclear reactors, boilers, machinery and mechanical appliances",
  "aggr_level": 2,
  "is_leaf": false,
  "qty": null,
  "qty_unit_code": -1,
  "qty_unit_abbr": null,
  "net_wgt": 12345678.0,
  "gross_wgt": null,
  "cif_value": 98765432.0,
  "fob_value": null,
  "primary_value": 98765432.0,
  "is_reported": true,
  "is_aggregate": false,
  "legacy_estimation_flag": 0,
  "customs_code": "C00",
  "mot_code": 0
}

Field	Type	Description
reporter_code	integer	UN M49 numeric reporter code.
reporter_iso	string	Reporter ISO3 code.
reporter_desc	string	Reporter country/territory name.
partner_code	integer	UN M49 numeric partner code.
partner_iso	string	Partner ISO3 code.
partner_desc	string	Partner country/territory name.
period	string	YYYY for annual, YYYYMM for monthly.
ref_year / ref_month	integer	Reference year and month.
freq_code	string	A (annual) or M (monthly).
flow_code / flow_desc	string	Import/Export/Re-Import/Re-Export, code and name.
classification_code	string	HS classification vintage in force for this row (e.g. H6).
cmd_code / cmd_desc	string	Commodity code and name — TOTAL, or an HS chapter/heading/subheading.
aggr_level	integer	Digit-depth of the commodity code (0 = Total, 2/4/6 = HS digits).
is_leaf	boolean	true when the commodity code has no finer breakdown beneath it.
qty / qty_unit_abbr	number/string	Quantity and its unit, when reported.
net_wgt / gross_wgt	number	Net and gross weight in kilograms.
cif_value	number	CIF value in USD (imports).
fob_value	number	FOB value in USD (exports).
primary_value	number	The primary trade value in USD — CIF for imports, FOB for exports.
is_reported	boolean	true when the reporter itself filed the figure; false means mirrored/estimated.
is_aggregate	boolean	true when the row is an aggregate rather than a directly reported line.
legacy_estimation_flag	integer	UN Comtrade's estimation-method flag.
customs_code	string	Customs procedure code.
mot_code	integer	Mode-of-transport code.

---

FAQ

Does this cover every country UN Comtrade publishes?

Yes — 243 reporting countries/territories and 292 trading partners, including historical entities UN Comtrade still carries in its records. Leave reporters/partners blank to include all of them.

What's the difference between a "reported" and an "estimated" figure?

is_reported tells you whether the country itself filed the trade figure. When it's false, the value was mirrored or estimated from the partner country's own filing — useful for knowing how much to trust a specific number.

Can I pull just one country's entire trade book?

Yes. Set reporters to that one country, leave partners blank, pick a commodity detail level, and set maxItems high (or 0) — the run walks every partner and commodity code for that reporter.

Why does a very detailed (AG6) query sometimes return fewer commodity codes than expected?

Extremely detailed, high-volume bilateral relationships (two large economies at 6-digit HS detail) can occasionally return a partial commodity breakdown for that specific combination — a limit of the free public data tier, not a filter you set.

What's the difference between annual and monthly data?

freqCode: "A" returns one row per year per combination; freqCode: "M" returns one row per calendar month, which multiplies the number of periods by up to 12x for the same year range.

---

Need More Features?

Have a request — a new field, a bulk-export mode, additional reference joins? Open an issue and we'll take a look.

Why Use This UN Comtrade Scraper?

• Full bilateral matrix in one run — no scripting hundreds of individual reporter/partner/period queries by hand.
• Names, not just codes — reporter, partner, and commodity descriptions are joined in on every row.
• Reported-vs-estimated transparency — is_reported and legacy_estimation_flag let you tell a filed figure from an estimate, which most trade-data tools don't surface at all.