Documentation

What can you do with this API?

A plain-English overview of every query type. Click any card to jump to the full documentation and code example.

Python SDK

Drop tradefacts.py into your project. No manual header construction required.

pip install requests

from tradefacts import TradeFacts
client = TradeFacts("your-api-key")
record  = client.hts("0901.11.00")
record  = client.ca("0901.11.00")
results = client.search("green coffee")
changes = client.changes()

Download tradefacts.py →

Base URL

https://tradefacts.io

All API endpoints are served over HTTPS. HTTP requests are redirected to HTTPS.

Authentication

All endpoints (except /request-access) require a valid API key in the X-API-Key request header.

curl https://tradefacts.io/api/hts/8471.30.01.00 \
  -H "X-API-Key: your_api_key_here"

Invoke-WebRequest -Uri "https://tradefacts.io/api/hts/8471.30.01.00" `
  -Headers @{"X-API-Key"="your_api_key"}

Missing or invalid key returns HTTP 401. Expired or cancelled subscription, or a plan attempting to access a restricted endpoint, returns HTTP 403.

Error Codes

Error Response Format

All error responses return JSON with a detail field describing the error.

{ "detail": "Invalid or missing API key" }

Rate Limits

No hard rate limits are enforced. If syncing the full dataset, batch chapter retrieval during off-peak hours.

HTS Code Lookup

curl https://tradefacts.io/api/hts/8471.30.01.00 \
  -H "X-API-Key: your_api_key"

Invoke-WebRequest -Uri "https://tradefacts.io/api/hts/8471.30.01.00" `
  -Headers @{"X-API-Key"="your_api_key"}

{
  "htsno": "8471.30.01.00",
  "indent": "1",
  "description": "Portable automatic data processing machines, weighing not more than 10 kg, consisting of at least a central processing unit, a keyboard and a display",
  "superior": null,
  "units": ["No."],
  "general": "Free",
  "special": "",
  "other": "35%",
  "footnotes": [],
  "quotaQuantity": null,
  "additionalDuties": null
}

Keyword Search

curl "https://tradefacts.io/api/search?q=copper&limit=10" \
  -H "X-API-Key: your_api_key"

Invoke-WebRequest -Uri "https://tradefacts.io/api/search?q=copper&limit=10" `
  -Headers @{"X-API-Key"="your_api_key"}

Chapter Retrieval

curl https://tradefacts.io/api/chapter/76 \
  -H "X-API-Key: your_api_key"

Invoke-WebRequest -Uri "https://tradefacts.io/api/chapter/76" `
  -Headers @{"X-API-Key"="your_api_key"}

Change Log

curl "https://tradefacts.io/api/changes" \
  -H "X-API-Key: your_api_key"

Invoke-WebRequest -Uri "https://tradefacts.io/api/changes" `
  -Headers @{"X-API-Key"="your_api_key"}

IEEPA Overlay

The IEEPA Overlay provides provisional tariff rates sourced directly from Federal Register proclamations — bridging the gap between a new executive order and USITC codification, which can lag by days to weeks. Rates are manually verified by TradeFacts editorial before publication and are clearly marked PROVISIONAL. Always verify with CBP before filing.

The overlay is maintained in near-real time: the FR monitor checks for new presidential proclamations every 4 hours. When a new tariff action is detected, proposed rates are extracted and reviewed before going live. The ieepa_overlay_notice field on base HTS lookups flags when overlay entries exist that are not yet reflected in HTS footnotes.

{
  "code": "9903.01.25",
  "rate_provisional": "10%",
  "description": "Temporary import surcharge...",
  "source_document": "FR Doc 2026-03824",
  "effective_date": "2026-02-24",
  "verified_date": "2026-03-31",
  "verified_by": "TradeFacts editorial",
  "rate_status": "PROVISIONAL",
  "disclaimer": "Sourced from Federal Register..."
}

Full 2026 Canadian Customs Tariff sourced from CBSA — 22,461 records across all 99 chapters (11,668 primary 8-digit tariff items plus 10,793 10-digit statistical subdivisions). Every record includes the MFN rate plus all applicable preferential treatment columns from Canada's full FTA network: CUSMA/USMCA, CETA (EU), CPTPP, Canada–UK, and 15 bilateral agreements. Use the treatment parameter on search and chapter endpoints to filter by any agreement code.

Canada endpoints mirror the US HTS endpoints and use the same X-API-Key authentication. The base path is /api/ca/ instead of /api/hts/.

Note: Retaliatory surtax overlay (separate CBSA notices on top of MFN rates) is on the roadmap and not yet included.

CA Tariff Lookup

curl https://tradefacts.io/api/ca/0101.21.00 \
  -H "X-API-Key: your_api_key"

Invoke-WebRequest -Uri "https://tradefacts.io/api/ca/0101.21.00" `
  -Headers @{"X-API-Key"="your_api_key"}

CA Keyword Search

# Filter aluminum records with CPTPP preferential rate
curl "https://tradefacts.io/api/ca/search?q=aluminum&treatment=CPTPT" \
  -H "X-API-Key: your_api_key"

Invoke-WebRequest -Uri "https://tradefacts.io/api/ca/search?q=aluminum&limit=10" `
  -Headers @{"X-API-Key"="your_api_key"}

CA Chapter Retrieval

curl https://tradefacts.io/api/ca/chapter/84 \
  -H "X-API-Key: your_api_key"

Invoke-WebRequest -Uri "https://tradefacts.io/api/ca/chapter/84" `
  -Headers @{"X-API-Key"="your_api_key"}

UST Rate Filter

# Get all tariff lines where US goods enter Canada duty-free
curl "https://tradefacts.io/api/ca/ust?rate=Free" \
  -H "X-API-Key: your_api_key"

Invoke-WebRequest -Uri "https://tradefacts.io/api/ca/ust?rate=Free" `
  -Headers @{"X-API-Key"="your_api_key"}

CA Change Log

curl "https://tradefacts.io/api/ca/changelog" \
  -H "X-API-Key: your_api_key"

Invoke-WebRequest -Uri "https://tradefacts.io/api/ca/changelog" `
  -Headers @{"X-API-Key"="your_api_key"}

Mexico Tariff (TIGIE) Tier 2+

Full 2026 Mexico TIGIE (Tarifa de la Ley de los Impuestos Generales de Importación y de Exportación) sourced from SNICE (Secretaría de Economía) — 8,183 fracciones arancelarias across 97 chapters. Includes the IGI (general import rate / MFN), export rate, and unit of measure for every fraction. Updated when SNICE publishes a new bulk release. All descriptions are in Spanish as published by the official authority.

Mexico endpoints mirror the US and Canada endpoints and use the same X-API-Key authentication. The base path is /api/mx/.

MX Lookup

curl "https://tradefacts.io/api/mx/7201.10.01"   -H "X-API-Key: your_api_key"

Invoke-WebRequest -Uri "https://tradefacts.io/api/mx/7201.10.01" `
  -Headers @{"X-API-Key"="your_api_key"}

{
  "fraccion": "7201.10.01",
  "chapter": "72",
  "description": "Fundición en bruto sin alear con un contenido de fósforo inferior al 0,5% en peso",
  "unit": "Kg",
  "igi": "35",
  "ige": "Ex."
}

MX Search

curl "https://tradefacts.io/api/mx/search?q=acero+laminado"   -H "X-API-Key: your_api_key"

MX Chapter

curl "https://tradefacts.io/api/mx/chapter/72"   -H "X-API-Key: your_api_key"

MX Change Log

curl "https://tradefacts.io/api/mx/changelog"   -H "X-API-Key: your_api_key"

Webhooks Tier 3 & 4

Webhooks eliminate polling. Instead of querying /api/changes each night, register an HTTPS endpoint once. TradeFacts POSTs a signed payload automatically whenever the nightly update detects a rate change — US HTS or Canadian Customs Tariff.

Delivery fires after each nightly ingest: ~02:00 UTC for US changes, ~02:30 UTC for CA changes. No changes detected = no POST sent.

Every POST is signed with HMAC-SHA256 using the secret you set at registration — the same pattern used by Stripe and GitHub webhooks.

Register a Webhook Endpoint

curl -X POST "https://tradefacts.io/api/webhook/register" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/hooks/tradefacts","secret":"your-secret-min-16-chars"}'

{
  "status": "registered",
  "url": "https://your-app.com/hooks/tradefacts",
  "note": "Fires nightly 02:00-02:30 UTC when changes detected."
}

Webhook Payload Schema

Every POST body is JSON. The top-level envelope:

Each object in changes has a type field:

Example payload (US rate modification):

{
  "source": "US",
  "event": "tariff_change",
  "timestamp": "2026-03-19T02:14:37Z",
  "change_count": 1,
  "changes": [
    {
      "type": "modified",
      "code": "7606.12.30",
      "description": "Of aluminum alloys, not alloyed",
      "changed_fields": {
        "additionalDuties": {
          "old": "25% (Section 232)",
          "new": "25% (Section 232) + 10% (IEEPA)"
        }
      }
    }
  ]
}

Verifying the Signature

Every POST includes an X-TradeFacts-Signature header. The value is sha256=<hex> — HMAC-SHA256 of the raw request body using your secret.

Always verify before processing. Use a constant-time comparison to prevent timing attacks.

import hmac, hashlib

def verify_tradefacts_signature(raw_body: bytes, secret: str, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

# Flask example
from flask import request, abort
@app.route("/hooks/tradefacts", methods=["POST"])
def handle_webhook():
    sig = request.headers.get("X-TradeFacts-Signature", "")
    if not verify_tradefacts_signature(request.get_data(), SECRET, sig):
        abort(400, "Invalid signature")
    payload = request.get_json()
    for change in payload["changes"]:
        print(change["code"], change.get("changed_fields", {}))
    return "", 200

const crypto = require("crypto");

function verifySignature(rawBody, secret, header) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(header)
  );
}

// Express example
app.post("/hooks/tradefacts", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-tradefacts-signature"] || "";
  if (!verifySignature(req.body, process.env.TRADEFACTS_SECRET, sig)) {
    return res.status(400).send("Invalid signature");
  }
  const payload = JSON.parse(req.body);
  payload.changes.forEach(c => console.log(c.code, c.changed_fields));
  res.sendStatus(200);
});

Retry behaviour: If your endpoint does not respond with HTTP 2xx, TradeFacts retries 3 times with exponential backoff (5s, 15s, 45s). After all attempts fail, Rick receives an alert email.

Idempotency: Each nightly run generates one POST per source (US, CA). There is no deduplication guarantee across retries — your endpoint should be idempotent (safe to receive the same payload twice).

US HTS Data Schema

All US HTS endpoints return records conforming to this schema.

Rate field format reference

The general, special, and other fields are free-text strings from USITC. Parsers must handle all of the following formats:

Note: Chapter 99 IEEPA and Section 301 rates reflect the USITC schedule and may lag recent executive orders by days to weeks. The chapter_99_additional_duties field surfaces all cross-references present in the published schedule. For the most current IEEPA rates ahead of USITC codification, use GET /api/ieepa/{code} to look up a specific Chapter 99 code, or GET /api/discrepancies to see all known gaps between the overlay and the published HTS schedule.

CA Data Schema

Canadian tariff records include the tariff code, description, and all 23 preferential rate columns from the CBSA schedule.

Canadian Preferential Treatment Codes

The preferential object in Canadian tariff records contains rates keyed by treatment code. Pass any code to the treatment parameter on /api/ca/search or /api/ca/chapter/{chapter} to filter records with a rate under that agreement.

Trade Agreement Codes

The special field in US HTS records contains preferential rates with trade agreement codes in parentheses.