comtrade_get_counts
Count UN Comtrade trade records a query would return without fetching data, so you can check result size and split queries exceeding 100,000 records.
Instructions
Count the UN Comtrade trade records a query would return, without fetching them.
The same request as get_data with upstream's countOnly. One call returns at
most 100,000 records, so count first and split a larger query. A count of 0 means no
data matches: an unreported period, a code that is not a reporter, a flow the
reporter does not record. Every count costs one call of the key's daily quota (500
on a free key). Arguments are checked before the call, reporter, partner, customs and
transport codes against the packaged lists: an unknown one raises UnknownCode, an
InvalidRequestError naming the packaged list, its fetch date and the closest code
(756 names 757, Switzerland); another mistake raises InvalidRequestError naming
the closest valid value.
Args:
type_code: "C" goods or "S" services.
freq_code: "A" annual or "M" monthly.
cl_code: Product classification: "HS" (all HS editions as reported; prefer
it), an edition "H0" to "H5", SITC "SS", "S1" to "S4", BEC
"B4", "B5", for services EBOPS "EB", "EB02", "EB10",
"EB10S"; also "BE" and "TM", which the spec lists and upstream
accepts. "H6" is valid but upstream answered HTTP 500 to all five tries on
2026-10-23 (two reporters, two product codes); "HS" rows carry the edition
the reporter used, e.g. classification_code "H6" for Switzerland 2023.
reporter_code: Reporting areas as UN Comtrade's numeric codes, comma-separated,
e.g. "757" Switzerland, "842" USA, "276" Germany, "156" China,
"757,842", as list_reporters lists them. Some differ from ISO numeric
codes: Switzerland is 757, not 756. Omit for every reporter.
partner_code: Partner areas, comma-separated, as list_partners lists them:
"0" World (the total over all partners), "276" Germany. Omit for every
partner, one row each.
partner2_code: Second partner (consignment) areas, comma-separated, codes of
list_partners; "0" is the total.
period: Years "2023" (annual) or months "202305" (monthly), at most 12
comma-separated, e.g. "2021,2022,2023".
cmd_code: Product codes of cl_code, comma-separated, as
list_commodities(cl_code) lists them: "TOTAL" for all goods,
"AG2", "AG4", "AG6" for every code at that level, codes such as
"0901" or "090111", wildcards such as "27??" (every four-digit code
under 27) or "27*". For services the classification files name "200"
(EB, EB02, EB10) or "S" (EB10S) as the total; recorded counts confirm
"200" on EB10 and EB02, where "TOTAL" counted 0 (EB10). A code
upstream does not have counts 0 too, so a 0 does not prove that a code exists.
flow_code: Trade flows, comma-separated: "X" exports, "M" imports,
"RX" re-exports, "RM" re-imports, also "DX", "FM", "MIP",
"MOP", "XIP", "XOP", "MIF", "XIF"; e.g. "M,X".
mot_code: Modes of transport, comma-separated: "0" the total, "1000" air,
"2100" sea, "3100" railway, "3200" road, "9100" pipelines and
cables. Omit for every mode, one row each.
customs_code: Customs procedures, comma-separated: "C00" the total, "C01"
clearance for home use, "C03" outright exportation. Omit for every
procedure, one row each.
aggregate_by: Upstream parameters to aggregate the results over, comma-separated
from cmdCode, period, partnerCode, partner2Code,
reporterCode, customsCode, motCode; e.g. "cmdCode" sums the
products of "AG2" into one row per remaining breakdown. The aggregated
parameters come back as -2 (cmd_code "-2", partner_code -2)
with classification_code "GG"; the count matches the rows.
breakdown_mode: "plus", upstream's default (omitting it gives the same rows):
every customs procedure, mode of transport and second partner;
"classic": only the total row (partner2_code 0, customs_code
"C00", mot_code 0).
include_desc: Upstream's includeDesc, "Include descriptions of data
variables": fills the *_iso and *_desc fields of get_data rows;
sent on as given.
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": {
"type_code": "<type_code>",
"freq_code": "<freq_code>",
"cl_code": "<cl_code>"
},
"name": "comtrade_get_counts"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | ||
| cl_code | Yes | ||
| cmd_code | No | ||
| mot_code | No | ||
| flow_code | No | ||
| freq_code | Yes | ||
| type_code | Yes | ||
| aggregate_by | No | ||
| customs_code | No | ||
| include_desc | No | ||
| partner_code | No | ||
| partner2_code | No | ||
| reporter_code | No | ||
| breakdown_mode | No |