comtrade_get_commodity_series
Fetches one reporter's trade in a single commodity with the World across multiple periods, returning joined, period-sorted rows for exports, imports, re-exports, or re-imports.
Instructions
A reporter's trade in one product with the World over many periods, oldest first.
data/v1/get for goods (typeCode C) with partner 0, World (the total over all
partners), pinned to the total of every breakdown (partner2Code 0, customsCode
C00, motCode 0, breakdownMode classic), with descriptions (includeDesc).
Upstream takes at most 12 periods per call, so the periods are sent in chunks of 12,
one call after the other in the order given (14 periods: two calls, 1.5 s apart), and
the rows are joined and sorted by period; a period upstream holds nothing for has no
row. A period the reporter has not released yet has no row either, which cannot be
told from a period without trade; get_data_availability names the periods a
reporter has released. One row per period at most, so there is no count call. Every
chunk is a keyed call and a free key allows 500 calls a day, so one series takes at
most 120 periods (ten calls); more raise InvalidRequestError before any call:
split the series. Arguments are resolved and checked before any call; an unknown
reporter raises UnknownCode, an InvalidRequestError naming the packaged list
and the closest area, another mistake InvalidRequestError naming the closest valid
value. meta.request holds the get_data arguments with every period; they were
sent 12 at a time.
Args:
reporter: The reporting area, as UN Comtrade's code or its ISO alpha-3 code:
"757" or "CHE" Switzerland, "842" or "USA", "276" or "DEU"
Germany, "156" or "CHN" China; list_reporters(search=...) finds them.
Codes are UN Comtrade's, not ISO numeric (Switzerland is 757, not 756). An
alpha-3 code that several codes share resolves to the one still in use
("DEU" is 276, not 280 Fed. Rep. of Germany until 1990).
commodity: One product code of cl_code: "TOTAL" all goods, an HS chapter
"27", heading "0901" or subheading "090111".
list_commodities("HS", search="coffee") finds codes.
flow: One trade flow: "X" exports, "M" imports, "RX" re-exports,
"RM" re-imports.
periods: Years (annual data) or months (monthly data), comma-separated, one
format, each once, at most 120: "2018,2019,2020,2021,2022,2023",
"202201,202202,202203"; every year from 2010 to 2023 is 14 periods, two
calls.
cl_code: Product classification, "HS" by default: all HS editions as each
reporter reported them (rows name the edition in classification_code, e.g.
"H6"); an edition "H0" to "H5", SITC "SS" or "S1" to "S4",
BEC "B4", "B5" also work. "H6" is valid but upstream answered HTTP 500
to every try on 2026-10-23, so "HS" stays the default. EBOPS "EB",
"EB02", "EB10", "EB10S" (services), "BE" and "TM" are
accepted but untested with the pinned typeCode C.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"reporter": "<reporter>",
"commodity": "<commodity>",
"flow": "<flow>",
"periods": "<periods>"
},
"name": "comtrade_get_commodity_series"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| flow | Yes | ||
| cl_code | No | HS | |
| periods | Yes | ||
| reporter | Yes | ||
| commodity | Yes |