Tariff Tools

Core tools for looking up and searching tariff codes.

get_tariff

Get full tariff details for an 8-digit HTS code, including all rate columns and FTA rates.

Parameters

Parameter	Type	Required	Default	Description
`hts_code`	string	Yes	-	8-digit HTS code (e.g., `"02013080"` or `"0201.30.80"`)

Response


{
  "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
}

The response includes 100+ fields covering all FTA rate programs (USMCA, CAFTA-DR, AGOA, GSP, etc.).

Example


{
  "hts_code": "0201.30.80"
}

search_tariffs

Multi-level semantic, lexical, or hybrid search across tariff codes.

Parameters

Parameter	Type	Required	Default	Description
`query`	string	Yes	-	Search query (product description or keywords)
`strategy`	string	No	`"hybrid"`	Search strategy: `"hybrid"`, `"semantic"`, or `"lexical"`
`limit`	integer	No	`10`	Maximum results (1-50)
`min_similarity`	float	No	`0.3`	Minimum similarity threshold (0-1)
`include_related`	boolean	No	`false`	Include cross-reference relationships in results
`level`	string	No	`"hts8"`	Hierarchy level: `"chapter"`, `"hts4"`, `"hts6"`, `"hts8"`
`variant`	string	No	`"full"`	Embedding text variant: `"full"` or `"short"`

Search Strategies

Strategy	Scoring	Best For
`hybrid`	0.7 × semantic + 0.3 × lexical	Most queries, best overall accuracy
`semantic`	Cosine similarity on embeddings	Vague or conceptual queries
`lexical`	ILIKE text matching	Known HTS terminology

If embeddings are unavailable, hybrid and semantic automatically fall back to lexical.

Response


{
  "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": {
        "references": ["0202.30"],
        "referenced_by_count": 3,
        "has_relationships": true
      }
    }
  ],
  "metadata": {
    "query": "fresh boneless beef",
    "strategy": "hybrid",
    "level": "hts8",
    "variant": "full",
    "limit": 10,
    "min_similarity": 0.3,
    "processing_time_ms": 145,
    "total_matches": 8
  }
}

Examples

Basic search:


{
  "query": "fresh boneless beef"
}

Category-level search with enriched descriptions:


{
  "query": "automotive parts",
  "level": "hts6",
  "strategy": "semantic",
  "limit": 5
}

With relationship data:


{
  "query": "steel pipes",
  "include_related": true,
  "min_similarity": 0.5
}