/wcohs/nomenclature

POST /api/wcohs/nomenclature

Price: 5 credits

Get one Harmonized System node — its official text, its legal notes, the section/chapter/heading chain above it and the subdivisions below it, in the chosen HS edition and language

How to use it

Use this to read the official WCO wording and, above all, the Legal Notes that decide classification — legal_notes is filled on sections and chapters, and empty on headings and subheadings, where the governing note lives on the chapter above. Walk the tree with descendants, which lists everything under the node with dash_level giving the '-' depth the HS prints; ancestors gives the chain up to the section. The edition matters: a code can be present in one edition and deleted in another, so pass the edition that matches the trade data you are reading. For duty rates on a US import, use us_hts/lines instead.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• hs_code string required — Harmonized System code — a section as a Roman numeral, a chapter number, a 4-digit heading or a 5/6-digit subheading (examples: "0901.11", "0901", "09", "II"; minLength: 1)
• edition string — Harmonized System edition whose text to read (default: "2022"; one of: "2022", "2017", "2012", "2007", "2002")
• language string — Language of the nomenclature text and legal notes (default: "en"; one of: "en", "fr", "es", "it")

Response

• @type string (default: "WcohsNode")
• internal_code string required
• hs_code string (default: "")
• node_id string (default: "")
• level string (default: "")
• section string (default: "")
• chapter string (default: "")
• dash_level integer (default: 0)
• description string (default: "")
• legal_notes string (default: "")
• edition string (default: "")
• language string (default: "")
• url string (default: "")
• ancestors array (default: [])
  • @type string (default: "WcohsNodeRef")
  • internal_code string required
  • hs_code string (default: "")
  • node_id string (default: "")
  • level string (default: "")
  • dash_level integer (default: 0)
  • description string (default: "")
  • url string (default: "")
• descendants array (default: [])
  • @type string (default: "WcohsNodeRef")
  • internal_code string required
  • hs_code string (default: "")
  • node_id string (default: "")
  • level string (default: "")
  • dash_level integer (default: 0)
  • description string (default: "")
  • url string (default: "")

Errors

• 422 — The request body did not validate Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.
• 412 — The code carries no node in the requested Harmonized System edition Retrying will not help: either the entity does not exist, or the input points at a different one.
• 429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.
• 500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.
• 529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
• X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
• X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
• X-Retry-After — Seconds to wait before retrying. Present only on 429.