UN Comtrade International Trade Data Scraper

Here is one real result, with every field the actor returns:

{
  "reporterCode": 842,
  "reporter": "USA",
  "reporterISO": "USA",
  "partnerCode": 0,
  "partner": "World",
  "partnerISO": "W00",
  "flowCode": "X",
  "flow": "Export",
  "period": "2023",
  "refYear": 2023,
  "refMonth": null,
  "frequency": "Annual",
  "classification": "HS",
  "commodityCode": "TOTAL",
  "commodity": "Total - All H6 commodities",
  "aggregateLevel": null,
  "isAggregate": true,
  "tradeValueUsd": 2018542583771,
  "fobValueUsd": 2018542583771,
  "cifValueUsd": null,
  "netWeightKg": null,
  "grossWeightKg": null,
  "quantity": null,
  "quantityUnitCode": null,
  "quantityUnit": null,
  "isQuantityEstimated": false,
  "isNetWeightEstimated": true,
  "customsCode": "C00",
  "modeOfTransportCode": 0,
  "isReported": false,
  "source": "UN Comtrade",
  "observedAt": "2026-08-10T14:35:45.109Z"
}

The most complete UN Comtrade trade-data scraper available. It returns clean, labelled rows (the source feed returns only numeric codes; this actor joins the official reference tables to add real country names, ISO codes and commodity descriptions), and gives you six filters to target exactly the trade flows you need.

📥 Input · 📤 Output · 💰 Pricing · ▶️ Examples

Table of contents

• What it does
• Quickstart
• Input reference
• Output reference
• Example output record
• Run via API and CLI
• Fetch results
• Billing and limits
• FAQ and troubleshooting

What it does

The actor pulls international merchandise trade statistics from UN Comtrade, applies the filters you pass as input (reporter countries, partner countries, trade flow, frequency, periods, commodity HS codes), and writes one normalized record per trade flow to the run's dataset. You can enter countries by name, ISO2, ISO3 or numeric code. Because the upstream feed returns only numeric codes with country and commodity names left null, the actor joins the official reference tables so every record has a real country name, ISO code and commodity description. Trade values are in USD; net weight and quantity are included when reported. Missing source values are returned as null.

By default the actor uses the free public preview (recent data). Provide your own free UN Comtrade access key in apiToken to unlock full historical data and higher volume.

Quickstart

Open the actor, paste this into the input, and press Run. It returns the United States total goods exports to the world for 2023.

{
  "reporters": ["USA"],
  "partners": ["World"],
  "flow": "export",
  "frequency": "annual",
  "periods": ["2023"],
  "commodityCodes": ["TOTAL"],
  "maxRecords": 10
}

Every field has a sensible default. Use World as the partner to get each reporter's total trade, or list specific partners. Use TOTAL for all goods, or HS codes such as 27 (mineral fuels) or 85 (electronics) to break trade down by product.

Input reference

Field	Type	Required	Default	Description
reporters	string[]	no	["USA"]	Countries that report the trade (exporter for exports, importer for imports). Name, ISO2, ISO3 or numeric code, for example USA, DEU, CHN. One run covers every reporter listed.
partners	string[]	no	["World"]	Trade counterpart countries. Use World for each reporter's total, or list partners such as China, Canada, MEX.
flow	enum	no	export	Which flow to return: export, import, both, reexport or reimport.
frequency	enum	no	annual	annual totals or monthly figures. For monthly, enter periods as YYYYMM.
periods	string[]	no	["2023"]	Years (for example 2023) for annual, or months as YYYYMM (for example 202401) for monthly. List several to compare over time.
commodityCodes	string[]	no	["TOTAL"]	HS commodity codes. TOTAL for all goods, a 2-digit chapter (for example 27, 85), or a more detailed code.
maxRecords	integer	no	200	Maximum number of trade records to return across the whole run.
apiToken	string (secret)	no	(empty)	Optional UN Comtrade access key. Leave empty for the free public preview; provide your own free key to unlock full historical data and higher volume.

Reporters and periods are combined into one query each; filters combine with logical AND.

Output reference

One dataset item per trade flow. Types: string, number, integer, boolean, or null when the source value is absent.

Field	Type	Description
reporterCode	integer	Numeric UN Comtrade code of the reporting country.
reporter	string	Reporting country name.
reporterISO	string	ISO3 code of the reporting country.
partnerCode	integer	Numeric code of the partner (0 for World).
partner	string	Partner country name, or World.
partnerISO	string	ISO3 code of the partner, or W00 for World.
flowCode	string	Raw flow code, for example X (export), M (import).
flow	string	Human-readable flow label, for example Export, Import, Re-export.
period	string	Period as reported: a year (2023) or a month (202401).
refYear	integer	Reference year.
refMonth	integer	Reference month (1 to 12) for monthly data, else null.
frequency	string	Annual or Monthly.
classification	string	Commodity classification, typically HS.
commodityCode	string	HS commodity code, or TOTAL.
commodity	string	Commodity description.
aggregateLevel	integer	HS aggregation level of the code, or null.
isAggregate	boolean	Whether the row is an aggregate, or null.
tradeValueUsd	number	Primary trade value in USD.
fobValueUsd	number	Free-on-board value in USD, or null.
cifValueUsd	number	Cost-insurance-freight value in USD, or null.
netWeightKg	number	Net weight in kilograms, or null.
grossWeightKg	number	Gross weight in kilograms, or null.
quantity	number	Reported quantity, or null.
quantityUnitCode	integer	Numeric code of the quantity unit, or null.
quantityUnit	string	Quantity unit abbreviation, or null.
isQuantityEstimated	boolean	Whether the quantity is estimated, or null.
isNetWeightEstimated	boolean	Whether the net weight is estimated, or null.
customsCode	string	Customs procedure code, or null.
modeOfTransportCode	integer	Mode-of-transport code, or null.
isReported	boolean	Whether the flow was directly reported, or null.
source	string	Always UN Comtrade.
observedAt	string	ISO 8601 timestamp of when the record was collected.
error	string	Present only on a failed or empty run; a single item with this field is written instead of trade records.

Example output record

Real record from a live run (input {"reporters":["USA"],"partners":["World"],"flow":"export","periods":["2023"],"commodityCodes":["TOTAL"]}):

{
  "reporterCode": 842,
  "reporter": "USA",
  "reporterISO": "USA",
  "partnerCode": 0,
  "partner": "World",
  "partnerISO": "W00",
  "flowCode": "X",
  "flow": "Export",
  "period": "2023",
  "refYear": 2023,
  "refMonth": null,
  "frequency": "Annual",
  "classification": "HS",
  "commodityCode": "TOTAL",
  "commodity": "Total - All H6 commodities",
  "aggregateLevel": null,
  "isAggregate": true,
  "tradeValueUsd": 2018542583771,
  "fobValueUsd": 2018542583771,
  "cifValueUsd": null,
  "netWeightKg": null,
  "grossWeightKg": null,
  "quantity": null,
  "quantityUnitCode": null,
  "quantityUnit": null,
  "isQuantityEstimated": false,
  "isNetWeightEstimated": true,
  "customsCode": "C00",
  "modeOfTransportCode": 0,
  "isReported": false,
  "source": "UN Comtrade",
  "observedAt": "2026-08-10T14:35:45.109Z"
}

Run via API and CLI

Start a run and wait for it to finish, then read the dataset. Replace <TOKEN> with your Apify API token.

Run synchronously and get dataset items in one call:

curl -X POST "https://api.apify.com/v2/acts/scrapers_lat~un-comtrade-trade-data-scraper/run-sync-get-dataset-items?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"reporters":["USA"],"partners":["World"],"flow":"export","periods":["2023"],"commodityCodes":["TOTAL"]}'

Start a run asynchronously:

curl -X POST "https://api.apify.com/v2/acts/scrapers_lat~un-comtrade-trade-data-scraper/runs?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"reporters":["CHN"],"partners":["USA"],"flow":"import","frequency":"monthly","periods":["202401"],"commodityCodes":["85"],"maxRecords":100}'

Apify CLI:

apify call scrapers_lat/un-comtrade-trade-data-scraper \
  --input '{"reporters":["DEU"],"partners":["World"],"periods":["2023"],"commodityCodes":["27"]}'

Fetch results

Every run writes to a dataset. Fetch items as JSON, CSV, or Excel by changing format:

# JSON
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&clean=true&format=json"

# CSV
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&clean=true&format=csv"

# Paginate large datasets
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&offset=1000&limit=1000"

<DATASET_ID> is returned as defaultDatasetId in the run object. Use offset and limit to page through large result sets. clean=true drops empty and internal fields.

Billing and limits

• Pay per result. You are charged per trade record returned (result event). See the pricing tab for the current per-result price.
• No charge on failure. If a run errors or matches nothing, the actor writes a single item with an error field and does not charge for it. Empty runs cost nothing.
• Spend cap respected. Set maxTotalChargeUsd on the run; once reached, the actor stops emitting and charging further billable results.
• Free Apify plans are capped at 10 records per run. Upgrade for a higher maxRecords.
• Preview vs full data. Without apiToken the actor uses the free public preview (recent data). Add your own free UN Comtrade key for full historical coverage and higher volume.

FAQ and troubleshooting

A run returned only an error record. Why? No trade matched the selected countries, period, flow and commodities, or the request failed. Loosen the filters or check the codes. These cases are not charged.

How do I get total trade rather than by product? Set commodityCodes to ["TOTAL"]. To break trade down by product, use HS codes such as 27 or 85, or several codes at once.

My access key was rejected. What now? Remove apiToken to use the free preview, or provide a valid UN Comtrade subscription key. A rejected key stops the run with an explanatory error item and is not charged.

How do I compare several years or months? List them in periods. For monthly data set frequency to monthly and use YYYYMM values such as 202401, 202402.

Why are weight and quantity null? UN Comtrade does not report those for every flow, especially aggregates. Missing source values are returned as null, never invented.

Is this an official UN tool? No. This actor is independent and has no affiliation with the United Nations or UN Comtrade. It reads only data UN Comtrade publishes. Use it in accordance with the UN Comtrade terms.

Related scrapers

• IMF Data Scraper: IMF macroeconomic and financial indicators.
• BLS Labor Statistics Scraper: US labor market and price statistics.
• Exchange Rates Scraper: Daily foreign exchange rates.
• EU TED Tenders Scraper: EU public procurement notices.
• GLEIF LEI Company Records Scraper: Global legal entity identifiers.

More scrapers at scrapers.lat

Built and maintained by scrapers.lat, where we publish scrapers for US, UK, European and Latin American public platforms: company registries, government data, finance, e-commerce and more. Browse the catalog or request a custom scraper at scrapers.lat.

---

Independent tool, not affiliated with the United Nations or UN Comtrade. Accesses only publicly available UN Comtrade data. Use in accordance with the UN Comtrade terms.