tariff

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 21, 2026 License: MIT Imports: 5 Imported by: 0

README

us-tariff-lookup-go

Offline US import-tariff reference data for Go: HTS code search (English + 中文), the stacked ruleset overview and a machine-readable rule-change feed — data embedded, zero dependencies, no network calls, no API key.

This is the Go distribution of the same versioned snapshot that powers invoicetariff.com and the us-tariff-lookup npm package. Results are deterministic against a pinned version: every answer carries a rulesetVersion and a dataAsOf date.

Install

go get github.com/invoicetariff/us-tariff-lookup-go
# CLI (optional):
go install github.com/invoicetariff/us-tariff-lookup-go/cmd/us-tariff@latest

Use

package main

import (
    "fmt"
    tariff "github.com/invoicetariff/us-tariff-lookup-go"
)

func main() {
    meta := tariff.Meta()
    fmt.Println(meta.RulesetVersion, meta.DataAsOf) // 0.3.4 2026-10-07 (monthly rebuilds)

    // HTS search: code prefix, English description or Chinese keyword.
    // Multi-word queries are AND-tokenized across all surfaces.
    for _, hit := range tariff.SearchHTS("cotton t-shirt", 5) {
        fmt.Println(hit.Entry.HTS8, hit.Entry.General, hit.MatchedBy)
        // 61091000 16.5% en
    }

    // Machine-readable rule changes, newest first (published + upcoming).
    for _, e := range tariff.Changelog() {
        fmt.Println(e.Date, e.Layer, e.Status, e.TitleEn)
    }
}

CLI:

us-tariff meta
us-tariff search "steel screws"
us-tariff search 保温杯
us-tariff changelog 5

All commands print JSON with rulesetVersion, dataAsOf and a disclaimer attached.

What's inside (snapshot v0.3.4, as of 2026-10-07)

Surface Count Notes
Curated MFN codes 484 High-frequency HTS 8-digit codes with official USITC general rates (EN + 中文)
China Section 301 lines 25 Lists 2/3/4A + 2026 four-year-review additions
Global 301 tiers 60 The 2026 global Section 301 program tiers
Section 232 measures 8 steel / aluminium / copper / autos / furniture / pharma / semiconductors / timber
Changelog entries 57 published + upcoming + historical, each sourced officially

Need the layers this module doesn't model? tariff.RulesetSeedRaw() and tariff.ChangelogRaw() return the full bundled JSON (fees, 232 measures, IEEPA history, per-entry source URLs) for you to unmarshal directly.

Scope

v1 ships the query surface (search / meta / changelog). The full landed-cost calculation — stacked duty layers, specific/compound rates, MPF/HMF entry fees — lives in the npm package and on the web calculator.

Honest limits: the bundled search covers curated high-frequency codes, not the full 5,689-line HTS — the full table ships in the hs-codes-database repo. Most rate lines carry sample/unverified flags: planning-grade, not certified entry data. Estimates for planning only — not legal advice; your customs broker signs the entry.

Data & updates

The snapshot is rebuilt monthly (and ad-hoc when major actions land) from the open us-tariff-rates-2026 repo. This module is re-released with each snapshot; watch the repo or the Tariff Radar feed for changes.

License

MIT — see LICENSE.

Documentation

Overview

Package tariff provides offline lookup of US import tariff reference data: HTS code search (English + 中文), the stacked ruleset overview and a machine-readable changelog — the same versioned snapshot that powers https://invoicetariff.com and the us-tariff-lookup npm package.

The data ships inside the module (go:embed), so results are deterministic and reproducible: every answer carries a ruleset version and an as-of date, and nothing calls the network.

This v1 covers search / meta / changelog. The full landed-cost calculation (stacked duty layers, specific/compound rates, MPF/HMF entry fees) lives in the npm package (github.com/invoicetariff/us-tariff-lookup) and on the web calculator; this Go module intentionally ships only the query surface.

Index

Constants

View Source
const Disclaimer = "" /* 148-byte string literal not displayed */

Disclaimer is the exact string to echo to end users of anything built on this module.

Variables

This section is empty.

Functions

func ChangelogRaw

func ChangelogRaw() []byte

ChangelogRaw returns the full bundled changelog JSON.

func RulesetSeedRaw

func RulesetSeedRaw() []byte

RulesetSeedRaw returns the full bundled ruleset JSON for consumers that need layers this package does not model (fees, 232 measures, IEEPA history, …).

Types

type ChangelogEntry

type ChangelogEntry struct {
	ID      string `json:"id"`
	Date    string `json:"date"`
	Layer   string `json:"layer"`
	Status  string `json:"status"`  // "published" | "upcoming" | "historical"
	Title   string `json:"title"`   // 中文标题
	TitleEn string `json:"titleEn"` // English title
	Summary string `json:"summary"` // 中文摘要,含 FR 编号与生效细节
}

ChangelogEntry is one rule-change record: what moved, when, on which layer, and whether it is published, upcoming or historical.

func Changelog

func Changelog() []ChangelogEntry

Changelog returns every bundled rule-change entry, newest date first. "published" entries are in force, "upcoming" entries have an effective date in the future, "historical" entries are superseded layers kept for refund lookups. Entries also carry their official source in the raw JSON (see ChangelogRaw).

type DataLinks struct {
	Ruleset      string `json:"ruleset"`
	FullHTSTable string `json:"fullHtsTable"`
}

DataLinks points at the open repos the snapshot is rebuilt from.

type Hit

type Hit struct {
	Entry     MFNEntry `json:"entry"`
	MatchedBy string   `json:"matchedBy"` // "code" | "en" | "zh"
}

Hit is one search result: the matched MFN entry plus which surface matched.

func SearchHTS

func SearchHTS(query string, limit int) []Hit

SearchHTS finds codes by HTS prefix/substring, English description or Chinese keyword. Multi-word queries use AND semantics — every whitespace- separated token must match somewhere on the entry (description, code or 中文关键词). Results keep the seed's curation order; limit <= 0 defaults to 10.

type MFNEntry

type MFNEntry struct {
	HTS8          string   `json:"hts8"`
	Description   string   `json:"description"`
	DescriptionZh string   `json:"descriptionZh"`
	General       string   `json:"general"`
	KeywordsZh    []string `json:"keywordsZh"`
	Sample        bool     `json:"sample"`
}

MFNEntry is one curated high-frequency HTS 8-digit code with its official USITC Column 1 general rate. Sample flags rows not yet verified line-by-line against the Federal Register text.

type MetaInfo

type MetaInfo struct {
	RulesetVersion     string    `json:"rulesetVersion"`
	DataAsOf           string    `json:"dataAsOf"`
	MFNCuratedCodes    int       `json:"mfnCuratedCodes"`
	China301Lines      int       `json:"china301Lines"`
	Global301Tiers     int       `json:"global301Tiers"`
	Section232Measures int       `json:"section232Measures"`
	ChangelogEntries   int       `json:"changelogEntries"`
	Disclaimer         string    `json:"disclaimer"`
	Homepage           string    `json:"homepage"`
	Data               DataLinks `json:"data"`
}

MetaInfo describes the bundled snapshot. Version and AsOf are the two fields to surface next to any number derived from this module.

func Meta

func Meta() MetaInfo

Meta reports what's inside the bundled snapshot.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL