hscode

EU customs tariff (TARIC) API, SDK and CLI: classify products into HS / CN / TARIC codes and get import duties.

This is the open source client for hscode.info, an HS code API and lookup for the EU Combined Nomenclature. Call the TARIC API from Node.js, TypeScript or Python, from the shell, or from an AI agent over MCP.

Quick start

export HSCODE_KEY=...   # free key: https://hscode.info/en/account
npx @hscode/sdk classify "cotton t-shirt"

import { createClient } from '@hscode/sdk';

const { results } = await createClient().classify({ text: 'cotton t-shirt' });
console.log(results[0].goods_code);

Note

Advisory only. Only a BTI from customs is legally binding.

Why hscode.info

• HS code classification from a plain product description, in any language.
• HS code lookup and search in German, English and French: Zolltarifnummer finden, nomenclature combinée, tarif douanier.
• Import duty per origin, with preferences, quotas, anti-dumping and the legal base. Use it as a customs duty calculator input.
• Every yearly TARIC snapshot from 2016 to 2026, latest October 2026. The current snapshot has 16,742 goods codes.
• Official European Commission TARIC data.
• One REST API, one OpenAPI spec, one SDK, one CLI and an MCP server.

Browse codes by product on hscode.info/en/hs-code.

How a request flows

flowchart LR
    A[Your code<br/>TypeScript or Python SDK] -->|HTTPS + Bearer key| API
    B[Shell<br/>hscode CLI] -->|HTTPS + Bearer key| API
    C[AI agent<br/>MCP client] -->|MCP| M[hscode.info/mcp]
    D[AI agent in Chrome<br/>WebMCP] -->|same four tools| W[any hscode.info page]
    API["hscode.info/api/v1"] --> R[CN codes + import duties]
    M --> R
    W --> R

Loading

Packages

Package	Language	Install	Status
@hscode/sdk	JavaScript / TypeScript, Node.js 20+	npm i @hscode/sdk	0.1.1
hscode	Python 3.9+	pip install hscode	0.1.1
hscode/sdk	PHP 8.1+, any PSR-18 client (Guzzle in Shopware, Magento, WooCommerce)	composer require hscode/sdk	0.1.0, unreleased
Hscode.Sdk	C# / .NET (netstandard2.0, net8.0)	dotnet add package Hscode.Sdk	0.1.0, unreleased
info.hscode:hscode-sdk	Java 11+	Maven / Gradle	0.1.0, unreleased
Google Sheets	Apps Script custom functions	see folder	unreleased
Excel	Office add-in custom functions	see folder	unreleased
n8n-nodes-hscode	n8n community node	n8n community nodes	0.1.0, unreleased
Zapier	Zapier Platform app	see folder	unreleased
Make	Make custom app	see folder	unreleased

CLI

The hscode command ships with the TypeScript SDK. It reads the key from HSCODE_KEY.

hscode classify "cotton t-shirt" --accurate     # HS code classification
hscode lookup 6109100010                        # code details and import duty
hscode search "t-shirt"                         # HS code lookup by words
hscode history 6109100010                       # third-country duty per yearly snapshot
hscode validate 6109100010 && echo valid        # exit code for scripts and supplier checks
hscode batch products.csv > classified.csv      # CSV classification

Batch mode suits a Shopify export or an ERP product catalogue.

sequenceDiagram
    participant U as You
    participant C as hscode CLI
    participant A as hscode.info API
    U->>C: hscode batch products.csv
    C->>C: read CSV, pick the description column
    loop every 25 rows
        C->>A: POST /api/v1/classify/batch
        A-->>C: codes per row
        C-->>U: progress on stderr
    end
    C-->>U: CSV with hs_code, hs_description, hs_confidence

Loading

SDK

import { createClient, HscodeError } from '@hscode/sdk';

const hscode = createClient({ apiKey: process.env.HSCODE_KEY });

const { results } = await hscode.classify({ text: 'frozen shrimp, peeled', mode: 'accurate' });
const duties = await hscode.duties({ code: results[0].goods_code });

try {
  await hscode.lookup({ code: '6109 10 00 10' });
} catch (e) {
  if (e instanceof HscodeError) console.error(e.status, e.code, e.message);
}

The TypeScript SDK has no runtime dependencies. Types are generated from the OpenAPI spec. Read the package page for every method.

Python SDK

from hscode import Client, HscodeError

client = Client()  # reads HSCODE_KEY

result = client.classify("frozen shrimp, peeled", mode="accurate")
duties = client.duties(result["results"][0]["goods_code"])

try:
    client.lookup("6109 10 00 10")
except HscodeError as e:
    print(e.status, e.code, e.message)

The Python SDK uses the standard library only and ships type hints. Read the package page for every method and a pandas example.

PHP, C# and Java SDKs

All three cover the same calls as the TypeScript and Python SDKs (classify, batch classify, lookup, history, search, duties, chapters, snapshots), read the key from HSCODE_KEY, use the latest year by default and raise an error with the HTTP status, the API error code and, on 429, Retry-After and the RateLimit-* headers.

$client = new Hscode\Client();   // PHP 8.1+, reads HSCODE_KEY
$code = $client->classify('cotton t-shirt')['results'][0]['goods_code'];

using var client = new HscodeClient();   // using Hscode; netstandard2.0 / net8.0, reads HSCODE_KEY
var res = await client.ClassifyAsync("cotton t-shirt", Mode.Accurate);

HscodeClient client = HscodeClient.create();   // Java 11+, reads HSCODE_KEY
String code = client.classify("cotton t-shirt").getResults().get(0).getGoodsCode();

Package pages: php/, dotnet/, java/.

Spreadsheets

Classify products from a cell, one cell or a whole column:

• Google Sheets: =HSCODE("leather shoes, men"), =HSCODE_DESCRIPTION(B2), =HSCODE_DUTY(B2, "CN"), =HSCODE_VALID(B2). See sheets/.
• Excel add-in: =HSCODE.CODE(...), =HSCODE.DESCRIPTION(...), =HSCODE.DUTY(...), =HSCODE.VALID(...). See excel/.

Ranges go to the batch endpoint in groups of 25 and results are cached for 6 hours, so recalculating a sheet does not use quota again. Each user saves their own API key from the menu (Sheets) or the task pane (Excel).

No-code: n8n, Zapier, Make

• n8n: n8n-nodes-hscode community node with classify, batch classify, look up, search, duty history and validate.
• Zapier: Classify Product action, Look Up Code and Search Codes searches.
• Make: custom app with Classify Product, Look Up Code and Search Codes modules.

Each connection asks for an API key and checks it with GET /api/v1/snapshots.

MCP and WebMCP for AI agents

Connect any MCP client to the remote MCP server at hscode.info/mcp. One-click setup for Claude, Cursor, VS Code and Gemini CLI is on the developers page. The tools are classify, lookup_code, search_codes and duty_history.

In Chrome, the same four tools are available on every hscode.info page through WebMCP. An AI agent in the browser can classify goods without any setup.

Machine-readable site summary for LLMs: llms.txt.

Accuracy

On 1,000 real EU Binding Tariff Information (BTI, also called EBTI) rulings sampled from a pool of about 120,000, covering 94 chapters, the first suggestion is right:

Digits	Level	First suggestion correct
2	Chapter	91 %
4	Heading	87.9 %
6	Subheading	84.7 %

As of October 2026, Precise mode. Details: accuracy.

Important

Advisory only. Only a BTI from customs is legally binding.

Pricing

The free plan has 30 AI units and 100 lookups a day, with no credit card. Quick AI costs 1 unit and Precise costs 5. Paid plans start at $19 a month. See pricing.

Data

Duties, nomenclature and measures come from the official European Commission TARIC database. The API serves every yearly snapshot from 2016 to 2026 in German, English and French. Queries can be in any language.

Links

• hscode.info: HS code lookup and classification
• Developers: API, SDK, CLI and MCP setup
• API reference and OpenAPI spec
• MCP server and llms.txt
• HS codes by product
• Pricing and accuracy
• Zolltarifnummer finden: hscode.info/de

License

MIT