get_seasonality
Seasonal pattern of one product of one reporter: for the 3 latest full calendar years before the year of the latest published month (data through 2026-08 gives 2023 to 2025; the years are stated in the answer), each calendar month's share of the 3-year value total and of the 3-year quantity total, the lowest and highest share of that month in any single year, and the peak and trough months (adjacent months merged, e.g. Oct-Nov, with their share of the year). Covers the world total and the 5 largest partners by latest-12-month value, or one partner with country. Not produced where the 3-year annual average is below min_value (default 1,000,000 US dollars) or trade is missing in any of the 3 years; seasonality_unavailable_reason then says not_enough_history, below_threshold, or (no month beyond 0.8x to 1.2x of an even share) no_peak_or_trough. Months are the months goods left (exports) or entered (imports) the reporting country. Use it for "when is the busy season?" or "which months are weak?" (e.g. knitted sweaters 6110 or frozen shrimp 030617); for month-by-month history 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>",
"flow": "<flow>",
"code": "<code>"
},
"name": "get_seasonality"
}
}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. | |
| level | No | Optional. The level of the code: the reporter's national level (JP hs9, US hs10, GB cn8; EU has none), hs6, hs4 or hs2; it follows from the number of digits, and a value that disagrees is rejected. | |
| country | No | Partner country: ISO 3166 alpha-2 code (e.g. "VN") or the name as published. Omit for the world total plus the 5 largest partners. Only those partners have seasonality; another country is reported as not produced. | |
| 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 | Smallest 3-year annual average in US dollars for a partner to be shown (default 1000000; a lower value does not add partners). |