UN Comtrade Trade Data Scraper

Pull official United Nations international trade statistics at scale — import and export values in USD, quantities, net and gross weight, and CIF/FOB figures — for 255 reporting countries and 300+ partner areas, across goods and services, annual or monthly. Built for trade economists, market-research and supply-chain analysts, policy researchers, and export/import consultants who need a clean, spreadsheet-ready trade series without clicking through the UN's query builder one country at a time.

Why This Scraper?

• 255 reporting countries and 300+ partner areas — the complete UN Comtrade reporter list, plus a World partner that collapses a country's entire import or export book into a single row.
• Type a country name, not a numeric code — "Germany", "DE", "DEU" and "276" all resolve to the same country, with built-in aliases so "United States", "South Korea", "Russia" and "UK" work too. Competing extractors accept UN numeric codes only.
• Five classification systems in one actor — HS (Harmonized System), SITC Revision 4 and BEC Revision 5 for merchandise, plus EBOPS 2002 and EBOPS 2010 for services.
• Services trade, not just merchandise — 12 main EBOPS 2010 service categories (transport, travel, construction, insurance and pension, financial, charges for intellectual property, telecoms and computing, and more) and 11 under EBOPS 2002, alongside physical goods.
• HS series back to 1988 — nearly four decades of annual figures, plus monthly data from 2000 for the countries that publish it.
• Five trade directions — Imports, Exports, Re-imports, Re-exports and Domestic exports, so you can separate genuine domestic production from goods that merely passed through a country.
• Commodity detail from 2-digit chapter to 6-digit line — pass "84" (machinery), "8703" (motor cars) or "870380" (electric cars) directly, or use AG2 / AG4 / AG6 to pull every code at that level of detail in one run.
• Optional customs-procedure, transport-mode and origin breakdowns — split any headline figure by customs regime, by sea/air/road/rail, and by second partner country, for the reporters that publish at that depth.
• 49 fields per record — CIF and FOB values side by side, primary and alternate quantity with units, net and gross weight, and six data-quality flags telling you exactly which figures the country reported and which the UN estimated.

Use Cases

Market Entry & Sizing

• Size an addressable export market by measuring what a target country already imports in your product category
• Rank the top 20 destination markets for a 6-digit product line by trade value
• Track a market's import growth year over year to time an entry
• Compare unit values (value ÷ quantity) across destinations to find the highest-price markets

Supply Chain & Sourcing

• Identify which countries are the largest suppliers of a component before qualifying vendors
• Measure supplier concentration risk by seeing how much of a country's imports come from one partner
• Spot sourcing shifts as production migrates between countries month by month
• Use net weight alongside value to model freight cost and container volume

Trade Policy & Compliance

• Quantify the trade exposure of a proposed tariff line before it takes effect
• Measure bilateral trade balances between any two countries at product level
• Separate re-exports from domestic exports to see what a hub economy actually produces
• Compare a partner's reported imports with the reporter's exports to detect mirror-statistics gaps

Competitive & Country Intelligence

• Benchmark a country's export performance in your category against its regional peers
• Watch export volumes out of a competitor's home market as a leading indicator of their shipment activity
• Map which transport modes and customs procedures dominate a given trade corridor
• Build country trade profiles combining goods and services flows in one dataset

Academic & Economic Research

• Assemble multi-decade panel datasets for gravity models and trade-elasticity studies
• Study commodity dependence using BEC broad economic categories
• Analyse the services-versus-goods composition of an economy over time
• Reproduce published trade findings with full provenance on every row

Getting Started

Simple Country Totals

The smallest useful run — total imports and exports for two countries:

{
    "reporters": ["USA", "China"],
    "partners": ["World"],
    "periods": ["2023"]
}

Product-Level Trade by Partner

German car exports broken out by every destination country, entered by country name:

{
    "dataset": "goods_hs",
    "reporters": ["Germany"],
    "partners": [],
    "tradeFlows": ["X"],
    "commodityCodes": ["8703"],
    "periods": ["2023", "2022"],
    "maxResults": 2000
}

Services Trade

All EBOPS 2010 service categories for two economies — leave the commodity codes empty to get every category:

{
    "dataset": "services_eb10",
    "reporters": ["United Kingdom", "Ireland"],
    "partners": ["World"],
    "tradeFlows": ["M", "X"],
    "commodityCodes": [],
    "periods": ["2022"]
}

Monthly Series with Full Breakdowns

Monthly machinery imports split by customs procedure, transport mode and country of origin:

{
    "dataset": "goods_hs",
    "reporters": ["FRA", "NLD", "BEL"],
    "partners": ["China"],
    "tradeFlows": ["M"],
    "commodityCodes": ["AG2"],
    "frequency": "M",
    "periods": ["202401", "202402", "202403"],
    "recordDetail": "breakdowns",
    "maxResults": 10000
}

Input Reference

What to Extract

Parameter	Type	Default	Description
dataset	string	"goods_hs"	Which trade dataset to pull and how commodities are classified. See the options table below.
reporters	array	["USA", "China"]	The countries whose customs authorities reported the trade. Enter country names (Germany, Japan, Brazil), ISO codes (USA, DEU, JP), or UN numeric codes (842, 276). Around 255 reporters are available.
partners	array	["World"]	The countries traded with. Use "World" for each reporter's overall totals — the fastest option and what most analyses need. Leave empty to return every partner country individually.
tradeFlows	array	["M", "X"]	Direction of trade. Imports and exports are published by nearly every country; the other three only by some.
commodityCodes	array	["TOTAL", "84", "85", "87"]	Which products to return. Use "TOTAL" for all-commodity totals, "84" for a 2-digit chapter, "8703" for a 4-digit heading, "870380" for a 6-digit line, or "AG2" / "AG4" / "AG6" for every code at that level. Leave empty on Services to get all categories.

dataset options

Value	Shown as
goods_hs	Goods — HS (Harmonized System, recommended)
goods_sitc	Goods — SITC Revision 4
goods_bec	Goods — BEC Revision 5 (broad economic categories)
services_eb02	Services — EBOPS 2002
services_eb10	Services — EBOPS 2010

tradeFlows options

Value	Shown as
M	Imports
X	Exports
RM	Re-imports
RX	Re-exports
DX	Domestic exports

Time Period

Parameter	Type	Default	Description
frequency	string	"A"	A = Annual (one figure per year), M = Monthly (more granular, published by a subset of countries).
periods	array	["2023", "2022"]	Years as "2023" for annual data, or year plus month as "202301" for January 2023. Leave empty to use the most recent period that is normally published in full.

Coverage floors differ by dataset: Goods HS reaches back to 1988 (most countries from 1991), SITC Revision 4 starts in 2007, BEC Revision 5 in 2017, both Services datasets around 2000, and monthly data in 2000.

Detail & Limits

Parameter	Type	Default	Description
recordDetail	string	"totals"	totals gives one clean figure per country, partner, product and period. breakdowns additionally splits each figure by customs procedure, transport mode and country of origin.
maxResults	integer	1000	Stop the run once this many trade records have been collected. Set to 0 to remove the limit. Records arrive in batches of up to 500 and a batch already on its way is never thrown away, so the final count can exceed this number by up to about 500. Every run also has a built-in safety limit of 4,000 queries to the data source; a run that reaches it stops early and says so in its final status.

recordDetail options

Value	Shown as
totals	Headline totals only (recommended)
breakdowns	Full breakdowns (customs procedure, transport mode, origin)

Output

Every row is one trade record. Fields with no reported value are omitted rather than filled with zeros, so a missing weight or quantity never looks like a real measurement of zero.

{
    "datasetType": "Goods",
    "frequency": "Annual",
    "period": "2023",
    "refYear": 2023,
    "refPeriodId": 20230101,
    "reporterCode": 276,
    "reporterIso": "DEU",
    "reporterName": "Germany",
    "partnerCode": 842,
    "partnerIso": "USA",
    "partnerName": "USA",
    "partner2Code": 0,
    "partner2Name": "World",
    "flowCode": "X",
    "flowName": "Export",
    "classification": "HS",
    "classificationCode": "H6",
    "isOriginalClassification": true,
    "commodityCode": "8703",
    "commodityName": "Motor cars and other motor vehicles; principally designed for the transport of persons (other than those of heading no. 8702), including station wagons and racing cars",
    "aggregateLevel": 4,
    "isLeaf": false,
    "customsCode": "C00",
    "customsName": "TOTAL CPC",
    "transportModeCode": 0,
    "transportModeName": "TOTAL MOT",
    "mosCode": "0",
    "tradeValueUsd": 25539504450.777,
    "fobValueUsd": 25539504450.777,
    "quantity": 418071.0,
    "quantityUnit": "u",
    "quantityUnitCode": 5,
    "altQuantity": 418071.0,
    "altQuantityUnit": "u",
    "altQuantityUnitCode": 5,
    "netWeightKg": 836272370.0,
    "isReported": false,
    "isAggregate": true,
    "isQuantityEstimated": false,
    "isAltQuantityEstimated": false,
    "isNetWeightEstimated": false,
    "isGrossWeightEstimated": false,
    "legacyEstimationFlag": 0,
    "sourceUrl": "https://comtradeapi.un.org/public/v1/preview/C/A/HS?reporterCode=276&partnerCode=842&flowCode=X&cmdCode=8703&period=2023&customsCode=C00&motCode=0&partner2Code=0&includeDesc=true",
    "scrapedAt": "2026-07-24T09:14:02.118Z"
}

Dataset & Period

Field	Type	Description
datasetType	string	Goods or Services
frequency	string	Annual or Monthly
period	string	The period as reported — 2023 for annual, 202401 for monthly
refYear	number	Reference year of the record
refMonth	number	Reference month, on monthly records only
refPeriodId	number	UN reference-period identifier

Reporter & Partner

Field	Type	Description
reporterCode	number	UN numeric code of the reporting country
reporterIso	string	ISO alpha-3 code of the reporting country
reporterName	string	Name of the reporting country
partnerCode	number	UN numeric code of the partner country (0 = World)
partnerIso	string	ISO alpha-3 code of the partner country
partnerName	string	Name of the partner country
partner2Code	number	UN numeric code of the second partner — country of origin for imports, country of consignment for exports
partner2Iso	string	ISO alpha-3 code of the second partner
partner2Name	string	Name of the second partner

Trade Flow & Commodity

Field	Type	Description
flowCode	string	M, X, RM, RX or DX when you pick a direction. Leave the direction empty and records can also carry FM (foreign import), MIP / XIP (inward processing) and MOP / XOP (outward processing) for the countries that publish them
flowName	string	Human-readable flow, e.g. Import, Export, Re-export
classification	string	Classification family — HS, S4, B5, EB02 or EB10
classificationCode	string	Exact revision used, e.g. H6 for HS 2022 — figures are always served in the current revision of the family you pick, with older reporting converted forward
isOriginalClassification	boolean	Whether the country reported in this classification or it was converted
commodityCode	string	Product or service code, e.g. 8703
commodityName	string	Full official description of the code
aggregateLevel	number	Number of digits of detail — 2, 4 or 6 for HS
isLeaf	boolean	Whether the code is a terminal line with no sub-codes

Trade Values

Field	Type	Description
tradeValueUsd	number	Headline trade value in current US dollars — the figure most analyses use
cifValueUsd	number	Value including cost, insurance and freight, on import records
fobValueUsd	number	Value free on board, excluding freight and insurance, on export records

Quantities & Weight

Field	Type	Description
quantity	number	Primary quantity in the unit the country reported
quantityUnit	string	Unit abbreviation, e.g. u (units), kg, l, m³
quantityUnitCode	number	UN numeric code for the quantity unit
altQuantity	number	Alternate quantity, where a second measure is published
altQuantityUnit	string	Unit abbreviation for the alternate quantity
altQuantityUnitCode	number	UN numeric code for the alternate unit
netWeightKg	number	Net weight of the goods in kilograms
grossWeightKg	number	Gross weight including packaging, in kilograms

Breakdown Dimensions

Field	Type	Description
customsCode	string	Customs procedure code, e.g. C00 for the all-procedures total
customsName	string	Customs procedure description
transportModeCode	number	Mode of transport code, e.g. 0 for all modes
transportModeName	string	Mode of transport description, e.g. sea, air, road, rail
mosCode	string	Mode of supply, used on services records

Data Quality & Provenance

Field	Type	Description
isReported	boolean	Whether the figure came directly from the country's own submission
isAggregate	boolean	Whether the figure is an aggregate rather than a single reported line
isQuantityEstimated	boolean	Whether the primary quantity was estimated by the UN
isAltQuantityEstimated	boolean	Whether the alternate quantity was estimated
isNetWeightEstimated	boolean	Whether the net weight was estimated
isGrossWeightEstimated	boolean	Whether the gross weight was estimated
legacyEstimationFlag	number	UN's legacy estimation indicator for the record
sourceUrl	string	Official UN Comtrade source reference for this exact record — full provenance for citations and audit trails
scrapedAt	string	ISO 8601 timestamp of when the record was collected

Tips for Best Results

• Set partners to ["World"] for country-level totals. It is by far the fastest and cheapest way to get a country's headline import or export figure, and it is what most market-sizing work actually needs. Only leave partners empty when you genuinely need the bilateral split.
• Step down the detail ladder gradually. Start at AG2 for the 2-digit chapter view, find the categories that matter, then re-run at AG4 or AG6 for just those chapters. Jumping straight to AG6 across every partner produces tens of thousands of rows.
• Skip the current year. Countries report on their own schedules, so the most recent year is always partial. For a complete annual series, end two years back — and remember services figures typically lag goods by about a year.
• Keep recordDetail on totals unless you need the splits. Most EU reporters publish customs-procedure, transport-mode and origin detail, which can multiply a single figure into several hundred rows. The United States does not, so the same query costs wildly different amounts across reporters unless totals are pinned.
• Use "TOTAL" for goods and "200" — or nothing at all — for services. TOTAL is a goods-only code and returns no rows on EBOPS datasets. Leaving commodityCodes empty on a Services run returns every service category, while 200 gives you the single all-services total.
• Compare mirror statistics to spot gaps. Pull country A's exports to B and country B's imports from A in the same run, then compare. Persistent gaps flag under-reporting, transit routing or valuation differences — a standard technique in trade-integrity research.
• Expect empty results for some flows. Re-imports, re-exports and domestic exports are only published by some countries — the United States publishes re-exports and domestic exports but not re-imports, while China and Brazil publish re-imports but not re-exports. An empty result there is a coverage fact, not a failure.

Pricing

From $0.02 per 1,000 results — among the lowest rates on the platform for official trade statistics. No compute or time-based charges — you pay per result, plus a small fixed per-run start fee. Bronze, Silver, and Gold subscribers pay progressively less; the table below shows total cost at each discount tier.

Results	No discount	Bronze	Silver	Gold
100	$0.0024	$0.00225	$0.00215	$0.0020
1,000	$0.024	$0.0225	$0.0215	$0.020
10,000	$0.24	$0.225	$0.215	$0.20
100,000	$2.40	$2.25	$2.15	$2.00

A flat $0.005 start fee applies to each run, on top of the per-result cost above. A "result" is one trade record pushed to your dataset. Standard Apify platform fees apply on top.

Integrations

Export data in JSON, CSV, Excel, XML, or RSS. Connect to 1,500+ apps via:

• Zapier / Make / n8n — Workflow automation
• Google Sheets — Direct spreadsheet export
• Slack / Email — Notifications on new results
• Webhooks — Trigger custom APIs on run completion
• Apify API — Full programmatic access

Legal & Ethical Use

UN Comtrade is the United Nations' official repository of international merchandise and services trade statistics, published as public data for research, policy and commercial analysis. This actor collects only those published aggregate statistics — no personal data is involved at any point. Users remain responsible for complying with applicable laws and with the United Nations' terms of use, including attribution requirements when republishing figures. Cite UN Comtrade as the source in any published analysis.