API Reference
Everything you need to integrate the TradeFacts.io API into your application.
https://tradefacts.io
All API endpoints are served over HTTPS. HTTP requests are redirected to HTTPS.
All API endpoints (except /request-access) require a valid API key passed
in the X-API-Key request header. API keys are issued when you request a trial
or subscribe to a plan.
curl https://tradefacts.io/api/hts/0101.30.00.00 \
-H "X-API-Key: your_api_key_here"
Requests without a valid API key return HTTP 401 with {"detail": "Invalid or missing API key"}.
Returns a single HTS record by its full code. The code can be passed with or without periods.
| Parameter | Type | Description |
|---|---|---|
code required |
string | Full HTS code, e.g. 0101.30.00.00 or 0101300000 |
curl https://tradefacts.io/api/hts/0101.30.00.00 \
-H "X-API-Key: your_api_key"
{
"htsno": "0101.30.00.00",
"indent": "1",
"description": "Asses",
"superior": null,
"units": ["No."],
"general": "6.8%",
"special": "Free (A+,AU,BH,CL,CO,D,E,IL,JO,KR,MA,OM,P,PA,PE,S,SG)",
"other": "15%",
"footnotes": [
{
"columns": ["general"],
"value": "See 9903.88.15.",
"type": "endnote"
}
],
"quotaQuantity": null,
"additionalDuties": null
}
Full-text search across all HTS record descriptions. Returns matching records up to the specified limit.
| Parameter | Type | Default | Description |
|---|---|---|---|
q required |
string | — | Search keyword(s) |
limit optional |
integer | 50 | Max results to return. Maximum: 200. |
curl "https://tradefacts.io/api/search?q=copper&limit=10" \
-H "X-API-Key: your_api_key"
Returns all HTS records for a given chapter number. Useful for bulk sync of specific commodity categories.
| Parameter | Type | Description |
|---|---|---|
chapter required |
string | Two-digit chapter number, e.g. 01, 76, 99 |
curl https://tradefacts.io/api/chapter/76 \
-H "X-API-Key: your_api_key"
Submit a trial access request. We'll respond with an API key within one business day.
| Field | Type | Description |
|---|---|---|
name required | string | Your full name |
company required | string | Company or organization name |
email required | string | Email address for your API key delivery |
All endpoints return records conforming to this schema. Fields are consistent across all chapters and will not change without advance notice to subscribers.
The nightly pipeline diffs the incoming dataset against the previous version. When changes are detected, a change log entry is created. Tier 2 subscribers receive webhook push notifications.
{
"timestamp": "2026-02-28T02:00:14Z",
"changes_detected": 2,
"changes": [
{
"htsno": "7606.12.30.30",
"field": "general",
"old": "3.0%",
"new": "10.0%"
}
]
}
The special field contains preferential rates with trade agreement codes. Common codes include: