comtrade_get_bilateral_flows
Retrieve bilateral trade flows between a reporter and partner by product code and period, with values from UN Comtrade for exports, imports, re-exports, or re-imports.
Instructions
Trade between one reporter and one partner, one row per product code and period.
One data/v1/get call for goods (typeCode C), pinned to the total of every
breakdown (partner2Code 0, customsCode C00, motCode 0, breakdownMode
classic) and with descriptions (includeDesc), so each row is UN Comtrade's figure
for the reporter's side of the trade in one product code and period. At TOTAL
and chapter level these are mostly UNSD aggregates (is_aggregate true,
is_reported false) with no quantity (qty 0, qty_unit_abbr "N/A",
net_wgt 0 or None): read the trade values. Rows are TradeFlowRecord,
sorted by period, then product code; a code or period upstream holds nothing for has
no row. Bounded by construction at product codes times periods rows (at most 12
periods), so there is no count call; a bound above 100,000 raises QueryTooLarge
before the call. Arguments are resolved and checked before the call; an unknown area
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 that were sent, codes resolved.
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).
partner: The partner area, as code or ISO alpha-3 code: "842" or "USA"
(842, the code the USA reports under, not 840), "276" or "DEU", "0"
or "W00" World, the total over all partners; list_partners(search=...)
finds them.
commodities: Product codes of cl_code, comma-separated, each naming one code:
"TOTAL" all goods, an HS chapter "27", heading "2709" or subheading
"270900", e.g. "TOTAL,27". Levels such as "AG2" and wildcards such
as "27??" are for get_data. list_commodities("HS", search="crude")
finds codes.
periods: Years "2022,2023" (annual data) or months "202301,202302" (monthly
data), comma-separated, at most 12, one format: the format sets freqCode.
flow: One trade flow: "X" exports, "M" imports, "RX" re-exports,
"RM" re-imports.
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>",
"partner": "<partner>",
"commodities": "<commodities>",
"periods": "<periods>",
"flow": "<flow>"
},
"name": "comtrade_get_bilateral_flows"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| flow | Yes | ||
| cl_code | No | HS | |
| partner | Yes | ||
| periods | Yes | ||
| reporter | Yes | ||
| commodities | Yes |