US Sales Tax Rates API

Published sales and use tax rates by jurisdiction, looked up by street address or ZIP code, with the breakdown into state, county, city and special district rates, their effective dates and where each value came from. Served by the Olympus Go gateway.

Not a tax calculation. A rate here is the rate a jurisdiction publishes. It is not the tax due on a transaction and not a taxability determination: whether an item is taxable, which location's rate applies (sourcing), whether the seller must collect at all (nexus) and exemptions all change what is owed. Every response repeats this in meta.notices (not_a_taxability_determination). Transaction tax calculation is not offered.

Coverage. Only the Streamlined Sales Tax (SST) member states listed as published by GET /v1/sales-tax/coverage, for the dates listed there. Every other state (for example California, Texas, New York, Florida) is reported as unsupported, with no rate.

Source. The SST rate and boundary files each member state posts at streamlinedsalestax.org (layout: SST Technology Guide, chapter 5). Rates are as the state publishes them; nothing is estimated. Files are checked twice a month; states post changes quarterly, by the first day of the month before the quarter, so rates for the next quarter are often available ahead of time.

Dates. Rates and boundaries carry effective dates. Pass date (YYYY-MM-DD) to look up another day; the default is today in America/New_York. Each state has its own dates_from..dates_to (coverage); dates outside it are unsupported, so a quarter a state has not posted yet is never answered from its older files.

Results. Lookups always answer 200 with a status:

• matched: exactly one set of jurisdictions applies and every jurisdiction has one published rate. combined_rates is set.
• ambiguous: the address or ZIP maps to more than one set of jurisdictions (common for 5-digit ZIPs). Every candidate is returned with its own rates; combined_rates is null. No single rate is chosen.
• unmatched: nothing in the state's files matches, or a jurisdiction's rate is missing for the date (reason: rate_missing).
• unsupported: the state is not published, or the date is outside the published range.

Matching. match.method says how the result was found and match.confidence how specific it is:

• address_range (confidence high, or medium when a directional or street suffix had to be ignored): the street, house number and parity fall inside one of the state's address ranges.
• zip4 (medium): the ZIP+4 range record. Used when the address is not in the state's address ranges, or for ZIP+4 lookups.
• zip5 (medium when every record of the ZIP agrees; otherwise the result is ambiguous, confidence low).

Lookups fall back from address to ZIP+4 to 5-digit ZIP, as the SST guide prescribes; match.attempted lists the methods tried and a fallback_used notice says when an address was answered from ZIP records.

Address normalisation. Deterministic, no geocoding: the street line is upper-cased and punctuation removed; the first token is the house number (digits, optionally one letter); a unit designator (APT, UNIT, STE, LOT, #, ...) ends the street; a leading / trailing directional (N, NORTH, SW, ...) and a trailing USPS suffix (STREET -> ST, AVENUE -> AVE, ...) are split off and abbreviated; suffix words inside the name are abbreviated too (HIGHWAY 33 -> HWY 33). PO BOX n is supported. The state files are normalised the same way. data.normalized shows how the input was read.

Rates. Four rates per jurisdiction, as SST publishes them: general and food/drug, each intrastate (sale originating in the state) and interstate (originating outside it). Rates are exact decimal fractions (0.0725 = 7.25%). Food/drug rates are null where a state leaves them blank.

Provenance. Every jurisdiction rate and boundary record carries a provenance block: the SST file it came from (source_url, source_version = file name), that file's date, when this version was published and the validation status of the publication. Responses list the active publication in meta.datasets.

Authenticate with an API key in X-API-Key or Authorization: Bearer. The organization's plan must include sales-tax; requests count against its monthly quota. Every response carries X-Request-Id. Errors share the Error body.