Browse all documentation

HS code API reference

Read one HS code of an edition with its name, level, parent and the codes one level down.

Overview

GET /v1/trade/hs-codes/{code}

GET /v1/trade/hs-codes/{code} returns one HS code of an edition: its name, its level, its parent and the codes one level down. code has 2, 4 or 6 digits.

A code that the edition does not have answers 404 hs_code_not_found. The same 6-digit code can exist in one edition and not in another, because editions are never converted into each other. The MCP tool is trade_get_hs_code and takes the same parameters.

Request

Subheading 851713, smartphones, in the 2022 edition, and the real response:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/hs-codes/851713"
Code 851713
{
  "code": "851713",
  "level": 6,
  "label": "Smartphones for wireless networks",
  "parent": "8517",
  "classification": "HS",
  "edition": "2022",
  "children": []
}

A subheading has no codes below it, so children is empty.

Parameters

ParameterWhereTypeRequiredDefaultAllowed values and meaning
codepathstringYesNoneAn HS code of 2, 4 or 6 digits, such as 85, 8517 or 851713, without dots. Any other form answers 400.
editionquerystringNo20222007, 2012, 2017 or 2022. Any other value answers 400.

Response

The answer holds these fields.

FieldMeaning
codeThe code.
level2 for a chapter, 4 for a heading, 6 for a subheading.
labelThe code's name in the edition's words.
parentThe code one level up. null for a chapter.
classificationHS.
editionThe edition.
childrenThe codes one level down, each with code, level, label and parent. Empty for a subheading.

More examples

A code the edition does not have

Code 851713 is new in the 2022 edition. The 2017 edition does not have it, so the request answers 404 and is free:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/hs-codes/851713?edition=2017"
Code 851713 in the 2017 edition
{
  "type": "https://narwhalapi.com/problems/hs-code-not-found",
  "title": "HS code not found",
  "status": 404,
  "detail": "HS 2017 has no code 851713.",
  "code": "hs_code_not_found",
  "request_id": "d8c40c41-aeaf-4b83-a315-c855697eafc3"
}

Sources

This route holds codes and no trade figures, so no source applies.

Currency

The route returns no values, so no currency applies.

Paging

The route has no paging. All children come in one answer.

Price

Each request that finds the code is one call, at $2 per 1,000 calls. A code that is not found and every other error are free.

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_querycode is not 2, 4 or 6 digits, or edition is not 2007, 2012, 2017 or 2022.
404hs_code_not_foundThe edition has no such code, for example HS 2017 has no code 851713.

Errors and credits · Trade API reference · Trade countries

Was this page helpful?