UN Comtrade Trade Flow Watch

UN Comtrade Trade Flow Watch: Bilateral Trade Data

Collect official bilateral commodity trade flows from the UN Comtrade database: import and export values in USD, net weight and quantity, for any reporter, partner country and HS commodity code. Each run returns one record per trade row plus a summary with totals per pair and flow and the change since your previous run, so a scheduled run works as a trade watch. Built for trade analysts, economists, commodity researchers and anyone monitoring who ships what to whom. Official UN open data; no account or API key is needed.

Use cases

• Trade watch: schedule a monthly run on your key country pairs and products and see when a new year's figures land or published figures are revised.
• Market sizing: import and export values and weights for one HS code between two countries, or against the World aggregate.
• Supply-chain research: compare a country's imports of a product from several partners in one run.
• Dashboards and models: feed annual trade values per pair into spreadsheets, BI tools or your own models.

Quick start

1. Open the Actor and click Start. The form is prefilled with Peru's trade with the World in HS 8517 (phones) for the latest published year.
2. Read the rows in the Output tab, or export them as JSON, CSV or Excel.

One pair for a set year:

{"reporter": "peru", "partner": "china", "cmdCode": "8517", "period": 2024}

To watch several pairs in one run, use a watchlist:

{"watchlist": [
  {"reporter": "peru", "partner": "china", "cmdCode": "8517", "period": 2024},
  {"reporter": "peru", "partner": "united states", "cmdCode": "8517", "period": 2024},
  {"reporter": "usa", "partner": "china", "cmdCode": "8517"}
]}

An empty input ({}) runs the same default pair as the prefilled form: Peru, World, HS 8517, latest published year.

Input

Name	Type	Default	Meaning
reporter	string	peru	Reporting country: ISO numeric code ("604") or name ("peru", "china", "united states").
partner	string	world	Partner country, same rules; "world" is the World aggregate.
cmdCode	string	8517	HS commodity code ("8517" phones, "2710" petroleum oils); deeper codes give more detail.
period	integer	latest	Reference year (2010 or later). When omitted, the current year and the two before it are tried, newest first; set period explicitly for older years.
watchlist	array	[]	1–25 pairs {reporter, partner, cmdCode, period}; overrides the four fields above. period may be omitted per pair; any other key in a pair is rejected by name.
requestDelaySecs	number	6	Pause between pairs, 1–60 seconds.
maxResults	integer	500	Upper bound on records kept per pair (1–500). Pairs usually return far fewer (see below).

What it returns

One dataset row per trade row. UN Comtrade's free preview data currently gives flow totals only: typically a few rows per pair (one per flow, such as imports, exports and re-exports), with no breakdown by transport mode or customs procedure.

Field	Meaning
recordKey	Stable key for the row.
period	Reference year.
reporterCode, reporter	Reporting country code and name.
flowCode	M import, X export, RX re-export, DX re-import.
partnerCode, partner	Partner country code and name.
cmdCode	HS commodity code.
primaryValue	Trade value in USD (CIF for imports, FOB for exports).
netWgt	Net weight in kg.
qty, qtyUnitAbbr	Quantity and its unit.
cifvalue, fobvalue	CIF and FOB values in USD where reported.
customsCode	Customs procedure code (C00 = all procedures).
motCode	Mode of transport (0 = all transport modes, the total).
isAggregate, isReported	UN Comtrade aggregate and reported flags.
pairKey	The watched pair this row belongs to.
sourceQuery	The UN Comtrade query that produced the row.
collectedAt	UTC time the row was collected.

The run summary (OUTPUT) reports per-pair record counts, the resolved year and totals per flow. For the import figure, take the row with flowCode == "M"; for exports, flowCode == "X".

Change since the previous run

For each pair, the summary's delta compares this run's totals per flow with the totals your previous run of this Actor collected for the same pair and year: current, previous, absChange and pctChange for value, net weight, quantity and row count, plus previousAt (when that run collected them). The first run for a pair has nothing to compare with and is marked isFirstRun: true. Later runs on your account compare with the most recent earlier run that watched the pair, whatever else that run watched. pctChange is null when the previous figure was zero or missing. When period is left empty and a newer year is published, the pair moves to that year and starts a new comparison.

If a pair fails in a run, its entry reports the error together with the last comparison on record.

Output example

The import row for USA from China, HS 8517, 2025, built from a recorded UN Comtrade response (collectedAt is an example):

{"recordKey":"2025:842:M:156:0:8517:C00:0","period":"2025","reporterCode":842,"reporter":"USA","flowCode":"M","partnerCode":156,"partner":"China","cmdCode":"8517","primaryValue":30506258399.0,"netWgt":52715091.379,"qty":0.0,"qtyUnitAbbr":null,"cifvalue":30506258399.0,"fobvalue":30205777507.0,"customsCode":"C00","motCode":0,"isAggregate":true,"isReported":false,"pairKey":"842:156:8517:2025","sourceQuery":"reporterCode=842&period=2025&cmdCode=8517&partnerCode=156","collectedAt":"2026-10-21T04:20:15+00:00"}

The same run also returned the export (X), re-export (RX) and re-import (DX) totals for the pair.

Pricing

• $0.001 per result row (one trade row).
• $0.005 per run start. The run-start event is charged per GB of memory; the default 512 MB run is one start event. The start is charged even if the run saves no rows.

Worked cost: one pair usually returns a few rows, so a single-pair run costs about $0.008. A full 25-pair watchlist at about 3 rows per pair (75 rows) costs about $0.08.

Scheduling and monitoring

• Schedule a monthly or quarterly run on the same input; each run's summary shows what changed per pair and flow since the previous run (see above). To keep the history yourself, store the rows in your own table keyed on recordKey.
• Leave period empty to follow the latest published year automatically.

FAQ

How fresh is the data? These are annual UN statistics: most reporters publish the previous calendar year, a few (such as the USA) publish current-year estimates. When period is omitted, the current year and the two before it are tried in turn and the first with published figures is used; for older years, set period explicitly.

Which flows can I watch? Any reporter/partner pair worldwide with any HS commodity code from 2010 onward, plus the World aggregate per reporter.

What are the limits? Up to 25 pairs per run. maxResults (up to 500 per pair) is only an upper bound: with flow totals only, a pair typically returns a few records. Larger watchlists take a little longer because pairs are collected one after another.

What happens if a pair fails? That pair becomes a warning in the run summary while the rest of the run completes.

Can I restart the comparison? Comparisons are kept per pair and year in a key-value store named comtrade-trade-watch-state in your Apify account. Delete that store (under Storage) to make the next run start fresh.

Export formats? JSON, CSV, Excel, XML or RSS from the dataset, or read it through the Apify API in your own pipeline.

Limits

• Annual data only (no monthly series), from 2010 onward.
• Flow totals per pair; no breakdown by transport mode or customs procedure in the current free data.
• Up to 25 pairs per run, collected one after another.

For support, contact Apify support and include the Actor run ID.