HS code API reference
Read one HS code of an edition with its name, level, parent and the codes one level down.
Overview
GET /
GET / 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_. 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_ 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",
"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
| Parameter | Where | Type | Required | Default | Allowed values and meaning |
|---|---|---|---|---|---|
code | path | string | Yes | None | An HS code of 2, 4 or 6 digits, such as 85, 8517 or 851713, without dots. Any other form answers 400. |
edition | query | string | No | 2022 | 2007, 2012, 2017 or 2022. Any other value answers 400. |
Response
The answer holds these fields.
| Field | Meaning |
|---|---|
code | The code. |
level | 2 for a chapter, 4 for a heading, 6 for a subheading. |
label | The code's name in the edition's words. |
parent | The code one level up. null for a chapter. |
classification | HS. |
edition | The edition. |
children | The 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"{
"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_. 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 | code is not 2, 4 or 6 digits, or edition is not 2007, 2012, 2017 or 2022. |
404 | hs_code_not_found | The edition has no such code, for example HS 2017 has no code 851713. |
Was this page helpful?