UN Comtrade Scraper

Extract international trade statistics from the United Nations Comtrade database — the world's most comprehensive repository of bilateral trade flow data. Covers 200+ countries, 5,000+ HS commodity codes, and annual/monthly series going back decades.

No API key is required. This actor uses the public preview endpoint.

---

What Can It Do?

• Fetch commodity trade flows — imports and exports between any country pair for any HS/BEC/SITC commodity code
• Get all-commodity totals — aggregate trade value for a country's full trade
• List reporter countries — get all valid country codes for use in queries
• Annual & monthly data — choose your time granularity
• Commodity classification — HS (Harmonized System), BEC, or SITC

---

Input

Field	Type	Description	Example
mode	select	getCommodityTrade or listReporters	getCommodityTrade
typeCode	select	C (Commodity) or S (Service)	C
freqCode	select	A (Annual) or M (Monthly)	A
clCode	select	HS, BEC, or SITC	HS
reporterCode	string	Numeric country code (842=USA, 36=AUS, 826=UK)	842
partnerCode	string	Partner country code; 0 = World	0
cmdCode	string	HS commodity code or TOTAL	8471
period	string	Year (2022) or year-month (202201)	2022
maxItems	integer	Records cap (1–500)	100

Common Country Codes

Code	Country
842	United States
36	Australia
826	United Kingdom
156	China
276	Germany
392	Japan
381	Italy
251	France
124	Canada
356	India

Common HS Commodity Codes

Code	Description
TOTAL	All commodities
8471	Automatic data processing machines (computers)
2709	Crude petroleum oils
8703	Passenger motor vehicles
8517	Telephones and smartphones
8542	Integrated circuits
1001	Wheat
2601	Iron ores
3004	Medicaments
7108	Gold

---

Output

Each record contains:

Field	Type	Description
period	string	Year (e.g. "2022") or year-month
reporterCode	integer	Numeric country code of reporter
reporterISO	string	ISO-3 code (e.g. "USA")
reporterDesc	string	Country name
flowCode	string	M=Import, X=Export, DX=Re-export
flowDesc	string	Human-readable flow description
partnerCode	integer	Numeric partner country code
partnerISO	string	Partner ISO-3 code
partnerDesc	string	Partner country name
cmdCode	string	HS commodity code
cmdDesc	string	Commodity description
tradeValue	float	Trade value in USD
netWgt	float	Net weight in kg
grossWgt	float	Gross weight in kg
qty	float	Quantity
qtyUnitCode	integer	Quantity unit code
qtyUnitAbbr	string	Quantity unit abbreviation
isReporter	boolean	Whether this is a reporter country
sourceUrl	string	Source URL
recordType	string	"trade" or "reporter"
scrapedAt	string	ISO timestamp of scrape

---

Example Use Cases

1. US Computer Imports from All Partners (2022)

{
  "mode": "getCommodityTrade",
  "reporterCode": "842",
  "partnerCode": "0",
  "cmdCode": "8471",
  "period": "2022",
  "maxItems": 100
}

2. Total Trade for Germany (Annual 2023)

{
  "mode": "getCommodityTrade",
  "reporterCode": "276",
  "cmdCode": "TOTAL",
  "period": "2023",
  "freqCode": "A"
}

3. Monthly Oil Trade (January 2023)

{
  "mode": "getCommodityTrade",
  "reporterCode": "842",
  "cmdCode": "2709",
  "period": "202301",
  "freqCode": "M"
}

4. List All Reporter Countries

{
  "mode": "listReporters",
  "maxItems": 500
}

---

Frequently Asked Questions

Do I need an API key? No. This actor uses the UN Comtrade public preview endpoint which is free and requires no registration.

How many records can I get? The public API returns up to 500 records per request. Set maxItems accordingly.

What are reporter vs. partner countries? The reporter is the country submitting the trade data (the one whose customs records are used). The partner is the country they traded with.

What does partnerCode=0 mean? Code 0 means "World" — all trade partners aggregated together.

What if data comes back empty? The public preview API has limited coverage. Some country/commodity/period combinations may not be in the preview dataset. Try a more common country like USA (842) or a recent year.

What is the HS classification? The Harmonized System (HS) is an international standard for classifying traded goods. 6-digit codes identify specific products; 2-digit "chapters" group related goods.

Can I get service trade data? Yes, set typeCode to S. Service data is less granular than commodity data.

---

Data Source

Data comes from the UN Comtrade database, maintained by the United Nations Statistics Division. It is the largest repository of international merchandise trade data.