LandedAPI.dev

API Reference

LandedAPI gives you programmatic access to the full US Harmonized Tariff Schedule (HTS) and thousands of CBP administrative rulings — the two primary sources importers use to determine duty rates and classification precedents. All responses are JSON.

Base URLhttps://trade-hts-api-production.up.railway.app

Quick Start

Three steps to your first API response. Your API key is emailed to you automatically when your subscription activates.

Subscribe and receive your API key

After checkout, your key arrives by email within a few minutes. It looks like lapi_live_xxxxxxxxxxxx.

Add the Authorization header to every request

Pass your key as a Bearer token. No other setup required.

Make your first request

Look up any HTS code to get its full duty rate breakdown.

curl

curl https://trade-hts-api-production.up.railway.app/v1/hts/6110.20.2010 \
  -H "Authorization: Bearer lapi_live_xxxxxxxxxxxx"

JavaScript (fetch)

const res = await fetch(
  'https://trade-hts-api-production.up.railway.app/v1/hts/6110.20.2010',
  { headers: { Authorization: 'Bearer lapi_live_xxxxxxxxxxxx' } }
);
const { data } = await res.json();
console.log(data.general_rate); // "16.5%"

Authentication

Every /v1/* endpoint requires your API key in theAuthorization request header. The /health endpoint is public and requires no key.

⚠

Keep your key secret. Treat it like a password — never include it in client-side JavaScript, mobile apps, or public repositories. If your key is exposed, email hello@landedapi.dev to have it rotated immediately.

Header format

Authorization: Bearer <your-api-key>

If the header is missing or the key is invalid, the API returns a 401 Unauthorized response and your request is not counted against your plan credits.

Errors & Status Codes

The API uses standard HTTP status codes. When something goes wrong, the response body contains a single error field with a plain-English description.

Error response format

{
  "error": "HTS code not found: 9999.99.9999"
}

Status	When it occurs	What to do
200 OK	Request succeeded	Read the `data` field
400 Bad Request	Missing or invalid query parameter	Check that all required params are present and correctly formatted
401 Unauthorized	Missing, malformed, or invalid API key	Confirm the `Authorization: Bearer <key>` header is set
404 Not Found	The requested HTS code does not exist in the schedule	Verify the code format (e.g. `6110.20.2010`) and try a search
500 Server Error	Unexpected error on our end	Retry after a short delay; contact support if it persists

Look Up an HTS Code

An HTS (Harmonized Tariff Schedule) code is a 10-digit number assigned to every product category imported into the United States. It determines the duty rate your importer pays at the border. Use this endpoint when you already know the exact code and want its full duty breakdown.

GET/v1/hts/:codeAuth Required

Path parameter

Name	Type	Description
code	string	HTS code in dot-delimited format, e.g. `6110.20.2010`. Must be 10 digits with dots after the 4th and 6th digit.

Example request

GET /v1/hts/6110.20.2010
Authorization: Bearer lapi_live_xxxx

Example response

{
  "data": {
    "hts_code":        "6110.20.2010",
    "description":     "Sweaters, pullovers, sweatshirts — cotton, men's",
    "general_rate":    "16.5%",
    "special_rate":    "Free (AU, BH, CA, CL, CO, E, IL, JO...)",
    "column_2_rate":   "90%",
    "unit_of_quantity":"doz",
    "quota_quantity":  null
  }
}

Response fields

Field	Type	Description
hts_code	string	The 10-digit HTS code
description	string	Official product description from the tariff schedule
general_rate	string	Standard duty rate paid by most countries (MFN rate)
special_rate	string	Preferential rates for FTA partner countries, listed in parentheses
column_2_rate	string	Rate for non-MFN countries (e.g. goods from Cuba or North Korea)
unit_of_quantity	string	Measurement unit used for quota tracking (e.g. `kg`, `doz`, `No.`)
quota_quantity	string \| null	Quota limit if one applies; `null` for most codes

Search HTS Codes by Description

Use this when you don't know the exact HTS code. Provide a product description keyword and get back up to 50 matching codes. Useful for discovery, autocomplete, or building a classification workflow on top of the schedule.

GET/v1/hts/searchAuth Required

Query parameter

Name	Type	Description
q required	string	Keyword to match against the tariff schedule description. Case-insensitive, substring match. Returns up to 50 results.

Example request

GET /v1/hts/search?q=cotton+sweater
Authorization: Bearer lapi_live_xxxx

Example response

{
  "data": [
    {
      "hts_code":        "6110.20.2010",
      "description":     "Sweaters, pullovers, sweatshirts — cotton, men's",
      "general_rate":    "16.5%",
      "special_rate":    "Free (AU, BH, CA, CL...)",
      "column_2_rate":   "90%",
      "unit_of_quantity":"doz",
      "quota_quantity":  null
    },
    { ... }
  ]
}

ℹ

Results are ordered by their position in the tariff schedule, not by relevance. For narrow results, use specific terms like cotton knit pulloverrather than sweater alone.

Search Administrative Rulings

CBP administrative rulings are written determinations issued by U.S. Customs and Border Protection in response to classification questions. They are publicly available and represent CBP's binding interpretation of how a product should be classified. Importers and trade attorneys cite rulings as precedent to support their own classification decisions.

⚠

For research only. Rulings provide classification guidance but do not constitute legal advice or customs business under 19 U.S.C. § 1641. Always verify with a licensed customs broker before using a ruling to support a live shipment entry.

GET/v1/rulings/searchAuth Required

Query parameter

Name	Type	Description
q required	string	Keyword matched against the ruling summary text. Case-insensitive, substring match. Returns up to 50 results.

Example request

GET /v1/rulings/search?q=cotton+knit
Authorization: Bearer lapi_live_xxxx

Example response

{
  "data": [
    {
      "ruling_number": "N123456",
      "date":          "2023-04-12",
      "summary":       "Classification of a cotton knit pullover...",
      "hts_code":      "6110.20.2010",
      "port":          "New York"
    },
    { ... }
  ]
}

Response fields

Field	Type	Description
ruling_number	string	CBP ruling reference number (e.g. `N123456`, `HQ H123456`)
date	string	Date the ruling was issued, in `YYYY-MM-DD` format
summary	string	Plain-text description of the product and the classification determination
hts_code	string	The HTS code CBP assigned to the product in this ruling
port	string	Port of entry or CBP office that issued the ruling

Health Check

Use this endpoint to confirm the API is reachable before making authenticated requests. No API key required.

GET/healthNo Auth

Response

{
  "status": "ok",
  "timestamp": "2026-07-01T12:00:00.000Z"
}

Need help?

Questions about your API key, rate limits, or how to structure a specific query? We respond to all inquiries within one business day.

Email Support