HS code search API reference
Search or list Harmonized System codes of one edition at 2, 4 and 6 digits by name, level or parent.
Overview
GET /
GET / lists the Harmonized System (HS) codes of one edition. HS codes name what is traded: 2 digits are a chapter, 4 a heading and 6 a subheading. The trade routes return these codes, and this route finds the one you need.
q searches the names. Chapters come first, then headings, then subheadings, and inside a level the best match comes first. parent lists the children of a code and level keeps one length. The four editions are 2007, 2012, 2017 and 2022. Editions are never converted into each other, so a code that appeared in 2022 is not in the 2017 list. The 2022 edition has 96 chapters, 1,228 headings and 5,612 subheadings. The MCP tool is trade_ and takes the same parameters.
Request
A search for cheese in the 2022 edition, first page of three, and the real response:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/hs-codes?q=cheese&limit=3"{
"classification": "HS",
"edition": "2022",
"total": 6,
"codes": [
{
"code": "0406",
"level": 4,
"label": "Cheese and curd",
"parent": "04"
},
{
"code": "040690",
"level": 6,
"label": "Cheese (excl. fresh cheese, incl. whey cheese, curd, processed cheese, blue-veined cheese and other cheese containing veins produced by \"Penicillium roqueforti\", and grated or powdered cheese)",
"parent": "0406"
}
],
"next_cursor": "eyJiIjoiaHM6MjAyMjpjaGVlc2U6Tm9uZTpOb25lOjMiLCJvIjozfQ"
}The page shows the first two of the three codes. total is 6, so next_ is set. Heading 0406 comes before its subheading 040690 because headings rank above subheadings.
Parameters
| Parameter | Where | Type | Required | Default | Allowed values and meaning |
|---|---|---|---|---|---|
q | query | string, 2 to 100 characters | No | None | Text to find in the code names. |
edition | query | string | No | 2022 | 2007, 2012, 2017 or 2022. Any other value answers 400. |
level | query | integer | No | All levels | 2, 4 or 6. Only codes of this length. |
parent | query | string | No | None | An HS code of 2, 4 or 6 digits. Only the children of this code. A chapter and a heading have children, a subheading has none. |
limit | query | integer | No | 100 | From 1 to 1000. The most codes in one page. |
cursor | query | string | No | None | The next_ of the previous page, with every other parameter unchanged. |
Response
The answer holds these fields.
| Field | Meaning |
|---|---|
classification | HS. |
edition | The edition of the list. |
total | The number of codes that match, over all pages. |
codes | The codes of this page. Each has code, level (2, 4 or 6), label (the code's name in the edition's words) and parent (the code one level up, null for a chapter). |
next_ | The cursor of the next page. null on the last page. |
More examples
No match
A search with no match answers 200 with an empty list, and is free:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/hs-codes?q=zzzzqqq"{
"classification": "HS",
"edition": "2022",
"total": 0,
"codes": [],
"next_cursor": null
}Sources
This route lists codes and holds no trade figures, so no source applies.
Currency
The route returns no values, so no currency applies.
Paging
limit sets the most codes in one page, from 1 to 1000, and defaults to 100. When more codes match, next_ holds the cursor of the next page: send it as cursor with every other parameter unchanged. A cursor from a different request answers 400 invalid_. total counts the matching rows over all pages. The MCP tool returns at most 200 rows in one result.
Price
Each request that returns at least one code is one call, at $2 per 1,000 calls, and every page of a long list is one call. A search with no match is free, and so is every error.
Errors
These errors use the shared problem shape with a request_. A missing or invalid key (401), a balance below the price of the call (402) and too many requests a minute (429) are the account errors every route shares: see Errors and credits.
| Status | Code | When it happens |
|---|---|---|
400 | invalid_query | edition, level or limit is outside its allowed values, q is shorter than 2 characters, or parent is not a code of 2, 4 or 6 digits. |
400 | invalid_cursor | The cursor is not one this request returned, or another parameter changed since. |
Was this page helpful?