get_ranking
Rankings of one reporter for a month. kind "items_for_country": the largest products (at the chosen level) for a partner country (default: world total). kind "countries_for_item": the largest partner countries for one product code. kind "movers_up" / "movers_down": the products with the largest US-dollar increase / decrease versus the same month a year earlier (for a partner, default world; kept for the world total and some partners), with previous-year value, change and year-over-year percent. month defaults to the latest. Results are precomputed ranks; limit is capped by your key tier (default top 20 without a key). Use it for "what does Japan buy from Vietnam?" (items_for_country) or "which products from China jumped this month?" (movers_up with country). get_ranking looks at a single month; for one product's partners over the latest 12 months, with growth and concentration, use get_partners instead; for one product's overview use get_item_summary. 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>",
"flow": "<flow>",
"level": "<level>",
"kind": "<kind>"
},
"name": "get_ranking"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Product code with the number of digits of level (e.g. "8542" with level hs4, "300490" with hs6). Required for kind countries_for_item; ignored otherwise. | |
| flow | Yes | Required. "import" (goods entering the reporting country) or "export" (goods leaving it); there is no combined view: "both" does not exist. For a comparison across countries use compare_countries, for exports minus imports use get_balance. | |
| kind | Yes | What to rank. items_for_country: largest products for country (or the world). countries_for_item: largest partner countries for code. movers_up / movers_down: products with the largest US-dollar increase / decrease versus the same month a year earlier, for country (or the world). | |
| level | Yes | Level of the products being ranked: the reporter's national level (JP hs9, US hs10, GB cn8; EU has none), hs6, hs4 or hs2; with countries_for_item it is the level of code. | |
| limit | No | Rows to return (default 20). Without an API key the maximum is 20 (more is refused with out_of_scope); with a free API key 100; never more than 200 rows per answer. | |
| month | No | Month YYYY-MM. Default: latest. | |
| country | No | Partner country for items_for_country and the movers kinds: ISO 3166 alpha-2 code (e.g. "VN") or the name as published. Omit for the world total. Ignored for countries_for_item. | |
| 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. |