Metadata-Version: 2.1
Name: hts-lookup
Version: 0.1.0
Summary: Offline lookup and validation of US Harmonized Tariff Schedule (HTS) codes: official descriptions, duty rates, closest valid code. No dependencies.
Author: Anders Lee
License: MIT (code); public domain US government data (see DATA-LICENSE.md)
Project-URL: Homepage, https://hs-code.net/
Keywords: hts,hs code,harmonized tariff schedule,tariff,customs,duty rate,import,trade,classification,usitc
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# hts-lookup

Offline lookup and validation of US Harmonized Tariff Schedule (HTS) codes. The current schedule is bundled
(about 0.5 MB compressed), so it works without network access or API keys. Pure Python, no dependencies.

```
pip install hts-lookup
```

```python
import hts_lookup as hts

hts.TITLE                               # 'Revision 21 (2026)'
line = hts.lookup("6201.40.70")
line.description                        # 'Water resistant (634)'
line.general                            # '7.1%'
[c for c, _ in line.path]               # ['6201', '6201.40', '', '', '', '', '', '6201.40.70.00']

hts.lookup("6109.10.00.12").general     # '16.5%'  (10-digit lines inherit the 8-digit rate)
hts.lookup("6201.40").declarable        # False   (a subheading with lines under it)
hts.lookup("8471.30").code              # '8471.30.01.00' (only one line under it, so that line)

hts.is_valid("6201.40.99.99")           # False
hts.closest("6201409999").code          # '6201.40'

[l.code for l in hts.children("8507.60")]
hts.search("lithium ion", limit=5)
```

Command line:

```
$ hts-lookup 6201.40.70
$ hts-lookup --search "vinyl stickers"
$ hts-lookup --children 4202.92
```

## Why validate codes

HS and HTS codes copied from supplier invoices, old spreadsheets or AI chat answers are often out of date or do not exist.
`is_valid()` and `closest()` catch those before a shipment does.

## Notes

- `general` is the column 1 general (MFN) rate. Extra duties under Chapter 99 depend on the country of origin and are not applied.
- The first six digits are the international HS code; digits 7 to 10 are US-specific.
- The bundled schedule is updated with new USITC revisions; check `hts_lookup.TITLE` for the edition you have.

Step-by-step product guides, UK and EU rates, and the customs rulings behind each code: [hs-code.net](https://hs-code.net/)

Code: MIT. Data: public domain US government work, see DATA-LICENSE.md. Not affiliated with USITC or CBP.
