get_balance
Trade balance of one reporter for a product and partner country (default: world total) by month: export value, import value and balance (exports minus imports), in the reporter's currency and in US dollars. A month with trade in one direction only shows the other side as 0 only when that direction is published for the month, has no source gap, AND the chapter has no undisclosed (withheld) amount that month; otherwise the other side and the balance are null (months_unknown counts them; never treat null as 0). For the United Kingdom (GB) most one-direction chapter-months are null for this reason. Available at HS6, HS4 and HS2 only, because national import and export codes are different numbering systems. This tool combines both flows, so it takes no flow argument. Use from/to (YYYY-MM, or just YYYY for a whole year) for the range. Use it for "does the United Kingdom run a surplus or a deficit with Germany in vehicles and parts (chapter 87)?"; for one direction alone, with quantities and prices, use get_series. Customs trade statistics of several reporting countries (Japan JP, United States US, United Kingdom GB, European Union (27 member states) EU) from their official customs data, monthly, by HS product code and partner country. value fields are in the reporter's currency (currency: JPY, USD, GBP or EUR) and _usd fields in US dollars; ratios and shares are fractions precomputed from the full dataset; every answer carries reporter, currency, data_through (latest published month), the reporter's attribution, and notes. Maximum 200 rows per answer. Numbers in answers are rounded once, at the end: amounts (value, _usd, v12 ...) to 2 decimals, quantity and kg to 3, unit prices (unit_price) to 4 significant digits below 100 and 2 decimals from 100 up (never rounded to 0), and ratios, shares and growth rates (yoy, mom*, share*, hhi*, chg3y) to 6; whole numbers and null are left as they are. A null quantity, kg or unit price comes with a *_unavailable_reason (mixed_units, weight_only, no_quantity_in_source, no_weight_in_source, source_gap, withheld; get_catalog lists them in null_reasons), and a missing seasonality with seasonality_unavailable_reason. The national level (JP 9-digit, US 10-digit, GB 8-digit codes) differs between reporters and between import and export; EU has no national level (HS6 only); HS6, HS4 and HS2 are shared. Import and export are separate datasets, so reporter and flow are always required for product figures. Rankings (limit) are limited to the top 20 without an API key (more is refused with out_of_scope) and to 100 with a free API key. Start with get_catalog (coverage, your access limits, which tool to use) or, when you already know the code, get_item_summary for a one-call overview of a product.
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>",
"level": "<level>",
"code": "<code>"
},
"name": "get_balance"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Last month, YYYY-MM, or a year, YYYY (read as YYYY-12). Default: the latest month published for both flows. | |
| code | Yes | HS code with the number of digits of level (e.g. "87" with hs2, "8486" with hs4, "850760" with hs6); dots are ignored. | |
| from | No | First month, YYYY-MM, or a year, YYYY (read as YYYY-01). Default: the first month with data. | |
| level | Yes | HS level of code: hs6, hs4 or hs2 (national codes are not combined, because import and export numbering differ there). | |
| country | No | Partner country: ISO 3166 alpha-2 code (e.g. "CN", "DE", "VN") or the name as published; omit for the world total (WLD). | |
| reporter | Yes | Required. The reporting country whose customs statistics are read: "JP" (Japan), "US" (United States), "GB" (United Kingdom) or "EU" (European Union (27 member states)). Partners are the other countries. |