get_series
Monthly time series for one product (HS2/4/6 or national code) of one reporter and partner country (default: world total). Per month: value and value_usd, quantity, kilograms, unit price (per unit and per kg), year-over-year and month-over-month change, share of the country total and trailing-12-month share, flags for months whose changes are not comparable because of a reclassification or definition change. When available it also includes precomputed signals: 3- and 6-month moving averages, deviation from them, acceleration, 12-month volatility and a 36-month anomaly score, each with the number of months used. Use from/to (YYYY-MM, or just YYYY for a whole year) to choose the range; the latest 200 months are returned at most. A monthly answer also carries totals, the sums over the rows returned (months_with_value, value, value_usd, quantity only when every row has one in a single unit, kg, unit_price = value / quantity and unit_price_kg as ratios of sums; complete says whether every month of the range has a row and nothing was cut by the 200-row limit). When quantity, kg or unit_price is null the row says why (quantity_unavailable_reason, kg_unavailable_reason, unit_price_unavailable_reason; for mixed_units also child_units, the units below the code). freq "year" returns calendar-year totals instead (value, quantity, unit price, year-over-year changes; the current year is flagged ytd). Use it for history, trends and quantity or unit-price questions (e.g. frozen shrimp 030617 by year, or lithium-ion batteries 850760 from one country by month). For a quick overview of the latest figures use get_item_summary instead; for the busy and slow months use get_seasonality. Not included: forecasts, partner detail (see get_partners). 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_series"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Last month, YYYY-MM, or a year, YYYY (e.g. "2025", read as YYYY-12). Default: latest published month. | |
| 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. | |
| freq | No | month (default): one row per month. year: calendar-year totals (value, quantity, unit price, year-over-year changes; the current year is flagged ytd); from/to select the years. | |
| from | No | First month, YYYY-MM (e.g. "2024-01"), or a year, YYYY (e.g. "2000", read as YYYY-01). With freq "year" the year of this month is the first year. Default: the first month with data. | |
| limit | No | Optional, monthly rows only. Number of NEWEST months to return (default and maximum 200); earlier months are cut off and complete is false. Use from/to to choose a range instead. | |
| 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. | |
| include_signals | No | Include precomputed signals (moving averages, acceleration, volatility, anomaly score) for monthly rows (default true). Set false for a smaller answer. |