Browse all documentation

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 /v1/trade/hs-codes

GET /v1/trade/hs-codes 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_list_hs_codes 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"
Codes that match cheese
{
  "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_cursor is set. Heading 0406 comes before its subheading 040690 because headings rank above subheadings.

Parameters

ParameterWhereTypeRequiredDefaultAllowed values and meaning
qquerystring, 2 to 100 charactersNoNoneText to find in the code names.
editionquerystringNo20222007, 2012, 2017 or 2022. Any other value answers 400.
levelqueryintegerNoAll levels2, 4 or 6. Only codes of this length.
parentquerystringNoNoneAn 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.
limitqueryintegerNo100From 1 to 1000. The most codes in one page.
cursorquerystringNoNoneThe next_cursor of the previous page, with every other parameter unchanged.

Response

The answer holds these fields.

FieldMeaning
classificationHS.
editionThe edition of the list.
totalThe number of codes that match, over all pages.
codesThe 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_cursorThe 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"
No match
{
  "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_cursor 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_cursor. 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_id. 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.

StatusCodeWhen it happens
400invalid_queryedition, 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.
400invalid_cursorThe cursor is not one this request returned, or another parameter changed since.

Errors and credits · Trade API reference · Trade countries

Was this page helpful?