get_partners
Trading partners of one reporter for one product. window 12 (default) covers the latest 12 months: each partner's 12-month value (and value_usd), share, year-over-year change against the previous 12 months, the 3-year change and rank; sort "growth" ranks by growth instead of size and, unless min_value is given, leaves out partners below a default floor (the larger of US$ 1,000,000 and 1% of the world 12-month value) because small bases give large percentages; min_value (US dollars) sets another floor (0 shows every partner). window 1 gives one month (any month, with month). Both include other (the world total minus the partners shown), country-concentration measures (HHI, number of partners, top partner and its share) and partner_count (every partner with trade in the window, whatever limit or min_value), partners_returned, truncated (limit cut off partners) and partners_below_floor (partners under min_value or the default growth floor). Use it to see who buys from or supplies the reporter, how concentrated the supply is and who is growing (e.g. where the United Kingdom's lithium-ion batteries 850760 come from and China's share). get_partners covers one product across all its partners over 12 months (or one month); use get_ranking instead to rank the products of one partner, or to find the biggest month-on-year movers; use get_new_markets for partners that are new or have doubled. Not included: partner history over time (use get_series with country). 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>",
"code": "<code>"
},
"name": "get_partners"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | HS product code with 2, 4 or 6 digits, or the reporter's national code (JP 9 digits, US 10, GB 8; a reporter without a national level, such as EU, has HS6 as its finest level); dots are ignored (e.g. "85", "8507", "850760" or "8507.60"). National codes differ between reporters and between import and export; find codes with search_items. On a build that serves HS6 and above a national code without a series answers fine_digits_not_served: retry with its 6-digit parent. | |
| 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. | |
| sort | No | value (default) ranks by size; growth ranks by year-over-year growth of the 12-month total (window 12 only; without min_value it leaves out partners below the larger of US$ 1,000,000 and 1% of the world 12-month value). | |
| limit | No | Number of partners (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. With window 12 it must be the latest month; use window 1 for others. | |
| window | No | 12 (default): the latest 12 months, latest month only. 1: a single month (use month for any other month). | |
| 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. | |
| min_value | No | Drop partners whose value (12-month total, or the month for window 1) is below this many US dollars. With sort growth it replaces the default floor; 0 shows every partner. |