Tariffs
Endpoints for looking up and searching tariff codes.
GET /api/v1/tariff/{hts_code}
Get full tariff details for an 8-digit HTS code, including all FTA rate columns.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
hts_code | string | 8-digit HTS code |
Response 200
{
"hts8": "02013080",
"brief_description": "Other",
"quantity_1_code": "kg",
"quantity_2_code": null,
"mfn_text_rate": "26.4%",
"mfn_ad_val_rate": 26.4,
"mfn_specific_rate": null,
"begin_effect_date": "2024-01-01",
"end_effective_date": null,
"usmca_text_rate": "Free",
"usmca_ad_val_rate": 0.0
}Errors
| Status | Condition |
|---|---|
400 | Code is not 8 digits |
404 | Code not found in database |
GET /api/v1/tariff
Search tariffs by description using lexical (ILIKE) matching.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
description | string | - | Search text (required) |
limit | integer | 20 | Maximum results (1-100) |
Response 200
[
{
"hts8": "02013080",
"brief_description": "Other",
"mfn_text_rate": "26.4%",
"mfn_ad_val_rate": 26.4,
"begin_effect_date": "2024-01-01",
"end_effective_date": null
}
]GET /api/v1/search
Multi-strategy search with semantic, lexical, or hybrid scoring. This is the primary search endpoint.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
query | string | - | Search query (required) |
strategy | string | "hybrid" | "hybrid", "semantic", or "lexical" |
limit | integer | 10 | Maximum results (1-50) |
min_similarity | float | - | Minimum similarity threshold (0-1) |
include_related | boolean | false | Include cross-reference data |
level | string | "hts8" | "chapter", "hts4", "hts6", "hts8" |
variant | string | "full" | "full" or "short" |
Response 200
{
"matches": [
{
"code": "02013080",
"description": "Meat of bovine animals, fresh or chilled: Boneless: Other",
"level": "hts8",
"mfn_rate": "26.4%",
"score": 0.87,
"match_type": "hybrid",
"semantic_score": 0.91,
"lexical_score": 0.78,
"related_codes": null
}
],
"metadata": {
"query": "fresh boneless beef",
"strategy": "hybrid",
"level": "hts8",
"variant": "full",
"limit": 10,
"min_similarity": 0.3,
"processing_time_ms": 145,
"total_matches": 8
}
}Rate Limit
30 requests per minute when rate limiting is enabled.
GET /api/v1/tariff/{hts_code}/references
Get all codes referenced in a tariff’s description text.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
hts_code | string | 8-digit HTS code |
Response 200
{
"hts8": "02013080",
"references": [
{
"referenced_code": "0202.30",
"referenced_code_clean": "020230",
"code_length": 6
}
],
"count": 1
}Errors
| Status | Condition |
|---|---|
503 | References table unavailable |
GET /api/v1/tariff/{code}/referenced-by
Find tariffs whose descriptions reference a given code. Uses prefix matching.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
code | string | HTS code (4-8 digits) |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 20 | Maximum results |
Response 200
{
"code": "0206",
"referenced_by": [
{
"source_hts8": "02013080",
"source_description": "Meat of bovine animals, fresh or chilled: Boneless: Other"
}
],
"count": 1
}Errors
| Status | Condition |
|---|---|
400 | Code must be 4-8 digits |