Search HS Commodity Codes
comtrade_search_commoditiesRead-only
Find HS commodity codes by keyword, partial description, or known code prefix. Returns matched codes at the requested aggregation level (2-, 4-, or 6-digit) with full descriptions, parent code, leaf status, and a recommended_query_code field indicating the best code level for subsequent trade queries (2-digit chapter for broad analysis, 4- or 6-digit for specific products). This is the critical resolution step — agents cannot derive HS codes from product names without this tool. Use aggr_level 2 to start broad; narrow with aggr_level 4 or 6 once you have a chapter. To get all commodities for an entire chapter, pass the 2-digit code as cmd_code in trade tools.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return; above 200 returns all matching codes. | |
| query | Yes | Keyword, partial description, or HS code prefix to search for. Examples: "motor vehicles", "8471", "coffee", "84" (chapter 84 = machinery). | |
| aggr_level | No | Aggregation level: 2 = HS chapter (most general), 4 = heading, 6 = subheading (most specific). Omit to return all matching levels. | |
| classification | No | HS classification version. "HS" covers the combined dataset across all editions (H0–H6). Use a specific edition (e.g. "H6") for version-specific lookups. | HS |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of codes returned in this response. | |
| notice | No | Recovery hint when no matches are found or results are truncated. Absent when results are non-empty and not truncated. | |
| matches | No | HS codes matching the query. | |
| truncated | No | True when matches were capped at the limit (totalMatches exceeds shown). | |
| totalMatches | No | Total matching codes (before limit truncation). |