us-tariff-lookup in Go: Offline HTS Search & Changelog Tutorial

Invoice × Tariff editorial

Who this is forGo developers embedding offline HTS lookup and tariff-change tracking into services, CLIs and internal tools.

Install with go get github.com/invoicetariff/us-tariff-lookup-go — a zero-dependency Go module with the versioned ruleset embedded. Call tariff.SearchHTS for English/Chinese HTS search, tariff.Meta() for the snapshot version, and tariff.Changelog() for machine-readable rule changes. Fully offline, MIT licensed; v1 is query-only — landed-cost math lives in the npm package and the web calculator.

What the module is

us-tariff-lookup-go is the Go distribution of the same versioned snapshot that powers this site's calculators and the npm package: data embedded via go:embed, zero dependencies, no API key, no network calls. Import it as tariff and every answer is deterministic against a pinned module version — each one carries a rulesetVersion and a dataAsOf date.

MIT licensed. v1 ships the query surface: HTS search, ruleset meta and a machine-readable changelog. The stacked landed-cost calculation is intentionally not in this module — more on that at the end.

Install

Requires Go 1.22 or newer.

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

Your first program: meta, search, changelog

One main.go that touches the whole API surface:

package main

import (
	"fmt"

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

func main() {
	// Which snapshot you have — surface these two fields next to any number you show.
	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
	}

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

That first search line is the golden test case: cotton t-shirt lands on HTS 61091000 with its official USITC general rate. Chinese works the same way — tariff.SearchHTS("保温杯", 5) finds the insulated-bottle line (96170010) through the bundled 中文 descriptions and keywords, with hit.MatchedBy reporting "zh".

The CLI: three commands

If you installed cmd/us-tariff, the same data is drivable from any shell — handy for pipelines, cron jobs and LLM tooling:

us-tariff meta                  # what's inside / which data version
us-tariff search "steel screws" # EN / 中文 / code prefix, optional limit: us-tariff search 保温杯 20
us-tariff changelog 5           # recent rule changes, newest first

Every command prints indented JSON with an envelope of rulesetVersion, dataAsOf and disclaimer, plus the payload under result — pipe it straight into jq.

Reading the results

Search hits ([]tariff.Hit) pair a curated MFN entry with the surface that matched:

  • hit.Entry.HTS8 / .Description / .DescriptionZh — the 8-digit code and both descriptions.
  • hit.Entry.General — the official USITC Column 1 general rate, as a string like "16.5%".
  • hit.MatchedBy — "code", "en" or "zh"; multi-token queries require every token to match somewhere on the entry (AND semantics).
  • hit.Entry.Sample — true means the rate line is not yet verified line-by-line against the Federal Register text: planning-grade, not certified entry data.

Changelog entries ([]tariff.ChangelogEntry) carry Date, Layer, Status ("published" = in force, "upcoming" = future effective date, "historical" = superseded layer kept for refund lookups), TitleEn, and a Chinese Title/Summary with the Federal Register citation.

Error handling and rate limits — the honest inventory

There is almost nothing to handle, by design:

  • No error values and no panics at call time. The JSON is parsed once at init from embedded data; the query functions are pure. An empty query (or no match) simply returns nil — check for it the way you would any slice.
  • No rate limits, no keys, no timeouts. Nothing calls the network, so the module is safe in CI, air-gapped deployments and serverless cold paths.
  • The one real risk is version drift, not failure. Pin the module in go.mod (a plain go get resolves the latest tag; left unpinned, @latest tooling can move your numbers between builds). Echo tariff.Meta()'s RulesetVersion/DataAsOf with every result, and pass the exported tariff.Disclaimer constant to your end users.
  • tariff.SearchHTS's limit defaults to 10 when <= 0; results keep the snapshot's curation order, not a relevance score.

Keep the data fresh

The snapshot is rebuilt monthly (and ad-hoc when major actions land) from the open rates repo, and this module is re-tagged with each snapshot — bump with go get github.com/invoicetariff/us-tariff-lookup-go@latest. To see what moved between versions, read tariff.Changelog() (or us-tariff changelog). The live feed with old → new values is the Tariff Radar, with an RSS feed if you want to automate reactions.

What's inside the bundled snapshot

Counts below are for the current release (snapshot v0.3.4, as of 2026-10-07) — run tariff.Meta() to see them for your own build:

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 layers the module does not 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. The bundled search covers curated high-frequency codes, not the full 5,689-line HTS — the complete table lives in the hs-codes-database repo and on the HTS search page.

No landed-cost math in v1 — use the npm package or the web calculator

This module intentionally ships only the query surface. Stacked duty layers, specific/compound rates, MPF/HMF entry fees and per-unit landed cost live in the us-tariff-lookup npm package (same snapshot, TypeScript, works in Node) and on this site's tariff calculator — no code at all. A common pattern: look codes up and track rule changes in Go, then price the line through the npm package with the same rulesetVersion so both sides agree digit for digit.

Frequently asked questions

Does the Go module calculate landed cost like the npm package?
Not in v1. us-tariff-lookup-go ships the query surface — HTS search, ruleset meta and the changelog. The stacked calculation (MFN + 301 + 232 + MPF/HMF, per-unit landed cost) lives in the us-tariff-lookup npm package and the web calculator, which run the identical snapshot, so you can combine the two against one rulesetVersion.
Does it call any API, and does it need an API key?
No and no. The ruleset JSON is embedded in the module with go:embed, there are zero dependencies, and nothing touches the network at runtime. That means no keys, no quotas, no timeouts — it works in CI, air-gapped environments and serverless functions.
How current is the data, and how do I update it?
The snapshot is rebuilt monthly from the open us-tariff-rates-2026 repo, and the Go module is re-tagged with each snapshot. Run tariff.Meta() (or us-tariff meta) to see your bundled version and data-as-of date, then go get github.com/invoicetariff/us-tariff-lookup-go@latest to move up. tariff.Changelog() lists what changed.
Can I use it in commercial products? What's the license?
MIT — commercial use, modification and redistribution are fine, including inside paid products. Keep the license notice, and keep the disclaimer visible: the data is planning-grade (many lines carry sample/unverified flags) and final duty is determined by CBP at entry.
Why can't SearchHTS find my product?
The bundled search covers a curated set of high-frequency codes (484 in the current release), not all 5,689 HTS 8-digit lines. Check the full table in the hs-codes-database repo or the HTS search page; for layered rules the module does not parse, RulesetSeedRaw() hands you the complete JSON.
us-tariff-lookup-go on pkg.go.dev

MIT licensed, zero dependencies, Go 1.22+. Source repo, releases and the sibling npm / PHP packages are linked from the open source page.