COMTRADE

Retrieve one monthly bilateral goods-trade series from the UN Comtrade public preview: a reporting country, a partner, an HS product, a trade direction, and a value or weight measure.

Syntax

series=COMTRADE(reporter.partner.hsCode.flow.measure.firstMonth.lastMonth)

Enter the seven fields as one dotted argument, without spaces or quoted strings. Month bounds use YYYYMM; both endpoints are included. The first month must precede or equal the last, and the last cannot be in the future.

Field	Accepted value	Meaning
`reporter`	Numeric UN M49 code, such as `398`	Country whose trade is reported. `398` is Kazakhstan.
`partner`	Numeric UN M49 code, such as `643`	Trading partner. `643` is Russia.
`hsCode`	Exact 2-, 4-, or 6-digit HS code	Selected goods category. This command does not accept eight-digit CN product codes.
`flow`	`EXPORT` or `IMPORT`	Exports by the reporter to the partner, or imports by the reporter from the partner.
`measure`	`VALUE` or `WEIGHT`	`VALUE` is reported in USD; `WEIGHT` is net weight in kg when reported.
`firstMonth`, `lastMonth`	`YYYYMM`	Requested inclusive monthly window.

Worked example: Kazakhstan to Russia

Request Kazakhstan's reported exports of HS product 854231 to Russia from January 2021 through December 2025.

kzRu=COMTRADE(398.643.854231.EXPORT.VALUE.202101.202512)

Once this returns a series, use the following script to label and chart it:

kzRu=COMTRADE(398.643.854231.EXPORT.VALUE.202101.202512)
kzRu=SET_NAME(kzRu,"Kazakhstan exports to Russia: HS 854231")
chart=SET_TITLE(LINE_CHART(kzRu),"Monthly Kazakhstan exports to Russia (USD)")
chart

Run the chart after the data is ready. On the first request, a long date range can return COMTRADE loaded 10/60 months, which is a progress message, not a series. Rerun the kzRu=COMTRADE(...) line later, then run the chart lines. A script that tries to chart the progress message cannot yet produce a trade chart.

What happens during a long request?

RainbowStats checks its disk cache for the requested reporter, partner, product, flow, measure, and each month.
A background worker asks Comtrade only for months that have not already been checked. It saves each completed month, including a month with no reported observation.
While the backfill runs, the command returns a progress message. A rate-limit response causes the worker to wait and retry.
When all requested months have been checked, the same command returns the complete available monthly series. A later request with an overlapping or extended date range reuses months already checked for that trade key.

Users of the same RainbowStats server process share the monthly cache and its download worker. Restarting the server resumes from saved months if its data directory persists. Completed months are reused rather than automatically refreshed for later source revisions; expanding the date range downloads only newly requested months.

Interpret the series

Values refer to the reporter's exports or imports. 398.643...EXPORT records Kazakhstan-reported exports to Russia; it does not identify the country where the goods originated.
Only reported observations become points. A missing month is not zero. A query may have every month checked yet return fewer observations than months requested.
The adapter keeps official reported records and avoids multiple overlapping classifications within the response. It reports an error if the public preview response reaches its 500-record limit instead of silently using a truncated result.
These filtered public-preview requests require no API key. The preview has usage limits, so a long first request can take time.

Use the series in a sanctions study

A change in KZ → RU exports can motivate further investigation. Check the share of missing months, product classification, mirror reporting by Russia, and a comparable control trade route. Test pretreatment trends before a difference-in-differences analysis. Shipment routing, re-exports, valuation, reporting delays, and changes in sanctions rules are distinct questions: a visible increase in this series alone does not establish sanctions evasion.

Align before comparing. EUROSTAT reports trade value in EUR and weight in 100 kg; COMTRADE reports USD and kg. The two series may also describe different reporters and trade stages. Do not subtract raw levels or treat them as interchangeable controls.

Common checks

Symptom	What to check
`COMTRADE loaded 0/60 months`	The server has started a background backfill. Rerun the same command to check progress.
Fewer points than requested months	Some months had no retained reported observation. Inspect coverage before computing growth rates or fitting a model.
`Invalid trade code`	Reporter and partner must be numeric M49 codes; the HS code must be 2, 4, or 6 digits.
No observations after completion	Verify that the reporter, partner, flow, product, and period have reported data. An empty result is not a string of zeroes.

Source

UN Comtrade, international merchandise trade data, data preview guidance, and data availability. Consult Comtrade's current metadata and revision notes for a formal study.