UN Comtrade Trade Data Scraper — Import/Export Stats

$0.20 per run + $0.0025 per result row — about $2.70 per 1,000 results. Pay only for results that land, no credit card required to try.

UN Comtrade's free preview API answers real trade statistics, but only if you already know its numeric reporter/partner codes and raw HS digit strings. This Actor does that lookup work for you: type United States, USA, or 840 and get the same answer, then get back a flat, labelled row with names filled in even where the raw API leaves them null — no second live lookup call, no code-table spreadsheet open in another tab.

🌍 What this scrapes

UN Comtrade's public Preview API (Comtrade Plus public tier, comtradeapi.un.org/public/v1/preview/...) — the same free, keyless endpoint family that powers Comtrade Plus's own quick-look UI. Every combination of reporter country, partner country, period, commodity, and trade flow you request comes back as one flat row with trade value, net weight, and quantity fields, when Comtrade reports them.

🔥 Features

• Human-friendly input resolution — country name, ISO2, ISO3, or numeric code; plain import/export/both words; HS code, TOTAL, or a free-text commodity description — all resolved locally against an embedded reference table, no second network call per lookup.
• Bounded multi-dimensional fan-out — query multiple reporters, partners, periods, and commodities in a single run (capped at 200 combinations so a run never gets away from you on cost).
• Null-free labels — reporter_name, partner_name, and hs_description are always filled from the embedded reference table, even when Comtrade's own API response leaves those fields null.
• 🛡️ We rotate browser fingerprints (curl-cffi impersonation across Chrome, Firefox, and Safari profiles) on every request.
• 🔁 We retry with exponential backoff on 408/429/5xx and honour Retry-After, up to 5 attempts per combination.
• 🧱 One bad combination never crashes the run. A transport error or an unresolved country name is logged and skipped; every other combination still lands in the dataset.
• 🧊 A zero-match combination still succeeds. A narrow filter that matches nothing finishes with a clear status message, not a failed run and a wasted charge.

💡 Use cases

• Trade and supply-chain analysis — pull import/export flows for a reporter-partner pair across multiple years without leaving a spreadsheet full of numeric country codes.
• Customs and commodity research — check trade value and volume for a specific HS chapter or heading across several partner countries in one run.
• Sourcing and procurement due diligence — compare a candidate supplier country's export profile against its declared trade partners.
• Academic and journalistic trade datasets — build a clean, reproducible reporter/partner/period/commodity table without hand-resolving Comtrade's numeric codes first.

⚙️ How to use it

1. List one or more reporters and partners — names, ISO codes, or numeric codes all work.
2. Set periods (years for annual, YYYYMM for monthly) and commodities (HS codes, TOTAL, or free text).
3. Pick flow (import, export, or both) and frequency (annual or monthly).
4. Run the Actor — the dataset fills with one row per resolved reporter × partner × period × commodity × flow combination.

No API key. No account. Just the countries, periods, and commodities you want.

📥 Input

Field	Type	Required	Default	Description
reporters	array of strings	yes	["United States"]	Reporting countries — name, ISO2, ISO3, or UN numeric code.
partners	array of strings	yes	["World"]	Trade partner countries — same accepted formats; World/0 = all partners.
periods	array of strings/numbers	yes	[2023]	Years (annual) or YYYYMM (monthly), matched against frequency.
commodities	array of strings	yes	["TOTAL"]	HS code, TOTAL, or a free-text description.
flow	select	yes	both	import, export, or both (fans out into separate rows per direction).
frequency	select	yes	annual	annual or monthly.
proxyConfiguration	object	no	Apify Proxy on	Kept on despite the keyless API — the preview tier is documented as rate-limited.

Example input:

{
  "reporters": ["United States"],
  "partners": ["World"],
  "periods": [2023],
  "commodities": ["TOTAL"],
  "flow": "export",
  "frequency": "annual",
  "proxyConfiguration": { "useApifyProxy": true }
}

📤 Output

One row per resolved reporter × partner × period × commodity × flow combination:

{
  "reporter_code": "842",
  "reporter_name": "United States of America",
  "reporter_iso2": "US",
  "reporter_iso3": "USA",
  "partner_code": "0",
  "partner_name": "World",
  "partner_iso2": null,
  "partner_iso3": null,
  "period": "2023",
  "frequency": "annual",
  "flow": "export",
  "hs_code": "TOTAL",
  "hs_description": "All commodities",
  "trade_value_usd": 2018756349021.0,
  "net_weight_kg": null,
  "qty": null,
  "qty_unit": null,
  "is_preview_capped": false,
  "scraped_at": "2026-09-03T06:58:00Z"
}

trade_value_usd, net_weight_kg, qty, and qty_unit come back null when Comtrade itself reports none for that combination — never a missing key, never a crashed row.

💰 Pricing

This Actor bills Pay-Per-Event, so the invoice matches what you actually received:

Event	Price
Actor start	$0.20 per run
Result emitted	$0.0025 per trade-statistics row written to the dataset

That works out to roughly $2.70 per 1,000 results. A combination that returns nothing costs you nothing extra — no per-row charge without a per-row result.

🚧 Limitations

• The Preview API's free tier caps rows returned per single (reporter, partner, period, commodity, flow) combination at roughly 500 — rows from a capped combination are flagged is_preview_capped: true and summarized in the run's status message, never silently dropped.
• The full cartesian product of your inputs (reporters × partners × periods × commodities × flow-expansion) is capped at 200 combinations per run — a larger fan-out fails fast before anything is charged.
• Goods trade only (typeCode=C, HS classification) — services trade and other classifications (SITC, BEC) are out of scope for this version.
• The embedded country and HS reference tables are static data shipped with the Actor and refreshed manually — an unmapped free-text commodity description falls back to a literal HS-code lookup, which Comtrade itself may reject or return empty for.

❓ FAQ

Do I need a UN Comtrade API key? No — the Preview API is public and keyless. You don't need an account either.

What happens if a combination matches nothing? The run finishes successfully with zero rows for that combination and a status message describing what was searched — you're never charged a per-row fee for rows that don't exist.

What does flow: "both" actually return? Two separate row sets — one for imports, one for exports — never a single ambiguous row. Every emitted row's flow field is unambiguously import or export.

Why did my run fail instead of returning nothing? A run fails loud only when every requested combination hits a real error (unreachable endpoint, retries exhausted) — not when a combination simply has no trade observations. Those two cases are handled differently on purpose.

Can I query monthly data? Yes — set frequency: "monthly" and give periods as YYYYMM strings, e.g. 202301.

🙌 Your feedback

Found an issue or have a feature request for the UN Comtrade Trade Data Scraper? Reach out via https://apify.com/DevilScrapes — we read every message and ship fixes fast.