search_items
Find product codes of one reporter by words from the product name (customs wording, e.g. "lithium-ion", "frozen shrimp", "integrated circuits") or by a code prefix (digits, e.g. "8708" or "30"). Use it first when you do not know the exact code; when you know the code, go straight to get_item_summary. Returns code, description, unit, and the first and last month with data. level defaults to hs6 on a build that serves HS6 and above (national-level series exist there only for a few listed codes; each hit says series_available, and for false gives hs6_parent), and to the reporter's national level (most detailed) on a build with full national series; use hs6/hs4/hs2 for broader groups (a code prefix with level hs4 or hs6 lists the codes under a chapter or heading, in code order and capped at limit, so a long list is cut off). Matching ignores case, hyphens and simple plurals, and knows common spelling variants (aluminum/aluminium, sulfur/sulphur, color/colour, tire/tyre) and one product synonym (passenger cars = motor cars); there are no other synonyms. Each hit says in available_in whether the code exists for import and/or export (with the period) and whether net trade (get_balance) is available. It returns codes, not trade values. 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>",
"query": "<query>",
"flow": "<flow>"
},
"name": "search_items"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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 | Code level to search: the reporter's national level (JP hs9, US hs10, GB cn8; EU has none), hs6, hs4 or hs2. Default: hs6 on a build that serves HS6 and above, otherwise the national level (most detailed; numbering differs between import and export). | |
| limit | No | Maximum results (default 20, max 50). | |
| query | Yes | Words from the product name, all of which must match (e.g. "frozen shrimp", "semiconductor machines"), or digits for a code prefix (e.g. "8507", "3004"). Up to 6 words are used. | |
| 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. |