---
title: "HS Code Lookup"
method: GET
path: "/api/hs"
tags: ["Reference Data"]
---

# HS Code Lookup

`GET /api/hs`

## Request

- Base URL: `https://www.freightutils.com`
- URL: `https://www.freightutils.com/api/hs`
- Auth: none declared

Search and browse Harmonized System (HS 2022) commodity codes. Supports text search by product description, exact code lookup with ancestor chain, and section browsing. Covers 6,937 codes across 21 sections and 96 chapters.

## Query parameters

- `q` string
- `code` string
- `section` string

## Response `200`

HS code data. Response shape varies by query mode.

- union
  - HsSearchResponse
    - `query` string, required
    - `results` HsCode[], required
      - `hscode` string, required: HS code (2, 4, or 6 digits).
      - `description` string, required: Product description.
      - `level` integer, required: Hierarchy level: 2=chapter, 4=heading, 6=subheading.
      - `parent` string, required: Parent code or TOTAL for chapters.
      - `section` string, required: Section Roman numeral.
    - `count` integer, required
    - `_source` SourceEnvelope: Additive provenance citation for the dataset or method behind this response, from FreightUtils' single provenance source of truth. Shapes: reference, methodology (calculators), or reference with provenance_status:'pending-verification'. Fields appear only when a real value exists.
      - `type` 'reference' | 'methodology', required
      - `authority` string
      - `dataset` string
      - `source_url` string
      - `data_vintage` string
      - `licence` string
      - `retrieved_via` string
      - `standard` string
      - `reference` string
      - `computed_by` string
      - `provenance_status` 'pending-verification'
      - `dataset_edition` string: Edition this response is served from (editioned reference datasets only), e.g. 'UN/LOCODE 2025-1'.
      - `authority_current_edition` string: The authority's current in-force edition at the last check. Differs from dataset_edition only when the served data lags the authority.
      - `checked_at` string: YYYY-MM-DD of the last served-vs-authority edition comparison (on-demand checker, staleness-guarded).
    - `matched_via` object: Present only when the HS 2022 descriptions found nothing and HMRC's UK Trade Tariff search references named the code(s).
      - `source` string, required
      - `url` string, required
      - `matches` object[], required
        - `tariff_code` string, required: The tariff line HMRC names.
        - `reference` string: HMRC's reference title, when the search returns one.
        - `hscode` string, required: The code in this dataset the line falls under.
  - HsCodeDetail
    - `hscode` string, required
    - `description` string, required
    - `level` integer, required
    - `parent` string, required
    - `section` string, required
    - `ancestors` HsCode[], required
      - `hscode` string, required: HS code (2, 4, or 6 digits).
      - `description` string, required: Product description.
      - `level` integer, required: Hierarchy level: 2=chapter, 4=heading, 6=subheading.
      - `parent` string, required: Parent code or TOTAL for chapters.
      - `section` string, required: Section Roman numeral.
    - `children` HsCode[], required
      - `hscode` string, required: HS code (2, 4, or 6 digits).
      - `description` string, required: Product description.
      - `level` integer, required: Hierarchy level: 2=chapter, 4=heading, 6=subheading.
      - `parent` string, required: Parent code or TOTAL for chapters.
      - `section` string, required: Section Roman numeral.
    - `sectionName` string, required
    - `_source` SourceEnvelope: Additive provenance citation for the dataset or method behind this response, from FreightUtils' single provenance source of truth. Shapes: reference, methodology (calculators), or reference with provenance_status:'pending-verification'. Fields appear only when a real value exists.
      - `type` 'reference' | 'methodology', required
      - `authority` string
      - `dataset` string
      - `source_url` string
      - `data_vintage` string
      - `licence` string
      - `retrieved_via` string
      - `standard` string
      - `reference` string
      - `computed_by` string
      - `provenance_status` 'pending-verification'
      - `dataset_edition` string: Edition this response is served from (editioned reference datasets only), e.g. 'UN/LOCODE 2025-1'.
      - `authority_current_edition` string: The authority's current in-force edition at the last check. Differs from dataset_edition only when the served data lags the authority.
      - `checked_at` string: YYYY-MM-DD of the last served-vs-authority edition comparison (on-demand checker, staleness-guarded).
  - HsSectionResponse
    - `section` object, required
      - `numeral` string
      - `name` string
    - `chapters` HsCode[], required
      - `hscode` string, required: HS code (2, 4, or 6 digits).
      - `description` string, required: Product description.
      - `level` integer, required: Hierarchy level: 2=chapter, 4=heading, 6=subheading.
      - `parent` string, required: Parent code or TOTAL for chapters.
      - `section` string, required: Section Roman numeral.
    - `count` integer, required
    - `_source` SourceEnvelope: Additive provenance citation for the dataset or method behind this response, from FreightUtils' single provenance source of truth. Shapes: reference, methodology (calculators), or reference with provenance_status:'pending-verification'. Fields appear only when a real value exists.
      - `type` 'reference' | 'methodology', required
      - `authority` string
      - `dataset` string
      - `source_url` string
      - `data_vintage` string
      - `licence` string
      - `retrieved_via` string
      - `standard` string
      - `reference` string
      - `computed_by` string
      - `provenance_status` 'pending-verification'
      - `dataset_edition` string: Edition this response is served from (editioned reference datasets only), e.g. 'UN/LOCODE 2025-1'.
      - `authority_current_edition` string: The authority's current in-force edition at the last check. Differs from dataset_edition only when the served data lags the authority.
      - `checked_at` string: YYYY-MM-DD of the last served-vs-authority edition comparison (on-demand checker, staleness-guarded).

## Other responses

- `400`: Missing or invalid parameters.
- `404`: Code or section not found.

---

[API](https://skmtc.dev/freightutils/apis/freightutils-api.md) · [All operations](https://skmtc.dev/freightutils/apis/freightutils-api/llms.txt) · [OpenAPI document](https://skmtc.dev/freightutils/apis/freightutils-api/revisions/6607bb3cea90?raw)