Data provenance · Verification pipeline
Sales Tax Data Methodology & Verification
Every rate on this site is published through a four-tier verification pipeline. The pipeline starts with a national ZIP-level database, checks state revenue bulletins, reconciles local boundaries against Streamlined Sales Tax tables, and then applies statutory shields that cannot be overridden by a conflicting scrape. This page documents each tier, the refresh cadence, and the current freshness of the public dataset.
The four-tier verification pipeline
A single source is never enough for a sales tax calculator. State rates change by statute, local rates change at county and city boundaries, and ZIP codes cross municipal lines. The pipeline therefore treats each source as a check on the others and refuses to publish a record that falls outside hard numeric bounds.
| Tier | Source | Cadence | What it verifies |
|---|---|---|---|
| Tier 1 | OpenSalesTax PostgreSQL dumps | Monthly, automated | ZIP-level state, county, city, and special-district rate stacks from the OpenSalesTax national database. The extractor writes compact per-state files only after every ZIP entry parses with the required c/s/co/ci/sp/n keys.public/data/zips/*.json, public/data/zip-index.json |
| Tier 2 | State Department of Revenue bulletins | Monthly review plus statutory changes | Statutory state rates, mandatory local components, grocery and clothing treatment, sales-tax holidays, and effective dates announced by each state's revenue department.src/data/rates.json rule text and statutoryCitation fields |
| Tier 3 | Streamlined Sales Tax boundary tables | Monthly cross-check | Local jurisdiction boundaries and combined rates for the 24 full member states, with special attention to county-line, city-limit, and special-district changes that ZIP-only datasets can blur.Local-rate validation and ZIP jurisdiction stack checks |
| Tier 4 | Statutory shields and hard bounds | Every publish | Non-negotiable statutory facts that override any conflicting scrape: Utah 4.85% + 1.25% = 6.10%, Illinois and Oklahoma 0% state grocery rates, Missouri's 1.225% reduced grocery rate, and the 0% NOMAD states.scripts/extract_opensalestax_to_json.py, scripts/updateTaxes.js |
How each tier works in practice
Tier 1 — OpenSalesTax PostgreSQL dumps
The monthly GitHub Actions workflow provisions a PostgreSQL 16 service container, clones the OpenSalesTax repository, runs the Alembic migrations, restores the national data dump, and executes the extraction script. The extractor groups ZIP records by state and emits compact files that keep the state rate, county rate, city rate, special-district rate, and a short jurisdiction label. It validates that every entry has all five numeric keys before writing, and it computes the average optional local rate from the ZIP distribution rather than guessing from a statewide headline. If the Python extractor fails, the workflow falls back to the Node scraper in scripts/updateTaxes.js.
Tier 2 — State Department of Revenue bulletins
Rates are only half the answer: the calculator also has to know whether groceries, clothing, digital goods, and prepared food are taxable. The editorial layer tracks each state's revenue department bulletins and encodes the result in thegroceryRule,clothingRule, and statutory-citation fields. This is where Illinois and Oklahoma's 0% state grocery rates, Missouri's 1.225% reduced grocery rate, and state-specific holiday windows are documented. The rule text is rendered on every state calculator page so a reader can compare the calculator's behavior with the underlying statute.
Tier 3 — Streamlined Sales Tax boundary tables
ZIP codes are delivery routes, not tax jurisdictions. A single ZIP can span two counties or include a special district that applies only to part of the delivery area. For Streamlined member states, the boundary tables provide a second check on the local stack derived from OpenSalesTax. When the two disagree, the published average local rate is adjusted toward the jurisdiction-weighted figure and the ZIP-level file keeps the more specific county and city components. This tier also catches newly created transit, school, and public-safety districts before they appear in a statewide average.
Tier 4 — Statutory shields and hard bounds
Some facts are statutory and should never be decided by a scrape. Utah's pure state rate is 4.85% and its statewide mandatory county component is 1.25%, producing a 6.10% functional minimum base; if a source returns 4.7%, the shield forces 4.85% and rejects the source value. Illinois and Oklahoma are pinned to a 0% state grocery rate, and Missouri is pinned to a 1.225% reduced grocery rate with a false full exemption flag. California's 7.25% headline is normalized to the 6.00% state rate plus its mandatory local component. Any record outside 0–15%, or any statutory rate that moves more than five percentage points in one refresh, aborts the entire publish rather than writing a suspicious value.
Live data freshness
The table below is generated at build time fromsrc/data/rates.jsonand public/data/changelog.json. A build with stale metadata is visible here, which makes freshness auditable rather than a claim.
| Dataset | Value | Source file |
|---|---|---|
| Jurisdictions published | 51 | src/data/rates.meta.json |
| Rates last updated | 2026-11-08T14:59:29.042Z | src/data/rates.json |
| Latest changelog event | opensalestax | public/data/changelog.json |
| Latest changelog time | 2026-11-08T13:40:05.966Z | public/data/changelog.json |
| ZIP entries seeded | — | public/data/changelog.json |
| 3-digit ZIP prefixes indexed | — | public/data/changelog.json |
Most recent changelog summary: Updated 96 rate field(s) and 39389 ZIP entries across 52 state file(s).
Known limits and how to verify your exact rate
No national dataset can replace the rate table published by the jurisdiction that actually collects the tax. ZIP-level estimates are strongest for state and county rates and weaker for city and special-district layers, especially in states with home-rule local taxes such as Alabama, Colorado, Louisiana, and Missouri. When a purchase is large, when you are filing a return, or when an exemption certificate is involved, confirm the rate with the destination state's revenue department or the local tax authority. The calculator exposes separate statutory, mandatory county, and optional local fields so you can override any layer without reloading the page.
The public data is available at /rates.jsonand is refreshed by the monthly workflow. For interpretation help, start with thesales tax guides, review theabout page, orcontact the team to report a correction. Popular state calculators includeCalifornia,Texas,New York, andFlorida.