HS Code API

Overview

The HS Code (Harmonized System Code) API provides access to the international commodity classification system maintained by the World Customs Organization (WCO). It includes sections, headings, subheadings, and product descriptions.

Note: This API provides read-only access to HS Code data. Data synchronization is managed internally by scheduled tasks.

Base Endpoint: /api/hs-code

API Endpoints

1. List All Sections

Retrieve all HS Code sections.

Endpoint: GET /api/hs-code/sections

Request:

curl "https://api.alaikis.com/std/api/hs-code/sections" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response:

{
  "code": 200,
  "msg": "Request successful",
  "data": [
    {
      "id": 1,
      "section": "I",
      "name": "Live animals; animal products"
    },
    {
      "id": 2,
      "section": "II",
      "name": "Vegetable products"
    },
    {
      "id": 3,
      "section": "III",
      "name": "Animal or vegetable fats and oils"
    }
  ]
}

---

2. Get Section by Code

Retrieve a specific section by its section code.

Endpoint: GET /api/hs-code/sections/{section}

Parameters:

Parameter	Type	Required	Description
section	String	Yes	Section code (e.g., I, II, III)

Request:

curl "https://api.alaikis.com/std/api/hs-code/sections/I" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

---

3. List HS Codes (Paginated)

Retrieve a paginated list of all HS Code records.

Endpoint: GET /api/hs-code

Parameters:

Parameter	Type	Required	Description
page	Integer	No	Page number, starting from 0 (default: 0)
size	Integer	No	Page size (default: 20)

Request:

curl "https://api.alaikis.com/std/api/hs-code?page=0&size=20" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response:

{
  "code": 200,
  "msg": "Request successful",
  "data": {
    "content": [
      {
        "id": 1,
        "hsCode": "0101",
        "description": "Live horses, asses, mules",
        "parent": "01",
        "level": 2,
        "unit": "kg",
        "type": "base",
        "version": "2022",
        "section": {
          "id": 1,
          "section": "I",
          "name": "Live animals; animal products"
        }
      }
    ],
    "totalElements": 15000,
    "totalPages": 750,
    "number": 0,
    "size": 20
  }
}

---

4. Search by HS Code

Search records by HS code (exact match).

Endpoint: GET /api/hs-code/code/{hsCode}

Parameters:

Parameter	Type	Required	Description
hsCode	String	Yes	HS code (e.g., 0101, 8471)

Request:

curl "https://api.alaikis.com/std/api/hs-code/code/8471" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

---

5. List HS Codes by Section

Retrieve a paginated list of HS Codes under a specific section.

Endpoint: GET /api/hs-code/section/{section}/codes

Parameters:

Parameter	Type	Required	Description
section	String	Yes	Section code (e.g., I, II)
page	Integer	No	Page number, starting from 0 (default: 0)
size	Integer	No	Page size (default: 20)

Request:

curl "https://api.alaikis.com/std/api/hs-code/section/I/codes?page=0&size=20" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

---

6. List HS Codes by Level

Retrieve a paginated list of HS Codes at a specific level.

Endpoint: GET /api/hs-code/level/{level}

Parameters:

Parameter	Type	Required	Description
level	Integer	Yes	Level (2 = chapter, 4 = heading, 6 = subheading)
page	Integer	No	Page number, starting from 0 (default: 0)
size	Integer	No	Page size (default: 20)

Request:

curl "https://api.alaikis.com/std/api/hs-code/level/2?page=0&size=20" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

---

Data Model

HsCode Fields

Field	Type	Description
id	Integer	Record ID
section	Object	Associated section
hsCode	String	HS code
description	String	Product description
parent	String	Parent code
level	Integer	Level (2=chapter, 4=heading, 6=subheading)
unit	String	Unit of measurement
type	String	Type (default: base)
version	String	Version (default: 2022)

HsCodeSections Fields

Field	Type	Description
id	Integer	Record ID
section	String	Section code (I-XXI)
name	String	Section name

HS Code Levels

Level	Digits	Description
2	2-digit	Chapter (e.g., 01, 84)
4	4-digit	Heading (e.g., 0101, 8471)
6	6-digit	Subheading (e.g., 010121, 847130)

Sections Reference

Section	Description
I	Live animals; animal products
II	Vegetable products
III	Animal or vegetable fats and oils
IV	Prepared foodstuffs; beverages, spirits and vinegar; tobacco
V	Mineral products
VI	Products of the chemical or allied industries
VII	Plastics and articles thereof; rubber and articles thereof
VIII	Raw hides and skins; leather; travel goods
IX	Wood and articles of wood; wood charcoal; cork
X	Pulp of wood; paper and paperboard
XI	Textiles and textile articles
XII	Footwear, headgear, umbrellas, walking-sticks
XIII	Articles of stone, plaster, cement, asbestos, mica
XIV	Natural or cultured pearls, precious or semi-precious stones, precious metals
XV	Base metals and articles of base metal
XVI	Machinery and mechanical appliances; electrical equipment
XVII	Vehicles, aircraft, vessels
XVIII	Optical, photographic, cinematographic, measuring, checking instruments
XIX	Arms and ammunition; parts and accessories thereof
XX	Miscellaneous manufactured articles
XXI	Works of art, collectors' pieces and antiques

Data Update Frequency

HS Code data is automatically synchronized on a monthly basis. You can check the sync task status via the Scheduler Status API.