Look up sales tax for an address, ZIP, or coordinates

GET

/v1/tax/{state}

• Production

Returns the applicable combined sales tax rate plus a per-jurisdiction breakdown for a U.S. location. Provide exactly one input:

• address= — full street address (most precise).
• location= — a place or city name.
• zip= — 5-digit ZIP; returns the applicable rate with a confidence signal.
• lat=&lng= — coordinates.

Historical rates. Pass as_of=YYYY-MM-DD to get the rate in effect on that date; where historical data isn’t available, the current rate is returned.

Warnings. If a supplied city name doesn’t match the jurisdiction that actually applies at the address, a place_input_mismatch warning is included so you don’t charge the wrong rate.

Response shape. mode=simple (the default) returns a flat single-rate object plus a meta block; mode=full returns the verbose per-jurisdiction body. Any other mode is a 400. Rate-bearing fields are fixed 5-decimal strings; the X-TaxQL-Mode response header echoes the shape served.

Parameters

Path Parameters

state

required

State

string

Query Parameters

location

Any of:

string

string

>= 1 characters <= 64 characters

null

null

A place or city name (e.g. Houston). Some states also accept a numeric location code.

zip

Any of:

string

string

/^(\d{5}|[A-Za-z]\d[A-Za-z][ -]?\d[A-Za-z]\d)$/

null

null

5-digit US ZIP code, or a Canadian postal code (A1A 1A1) on province routes.

address

Any of:

string

string

>= 10 characters <= 200 characters

null

null

Full street address: ’, , ’.

period

Any of:

string

string

/^\d{5}$/

null

null

Effective period code (5-digit YYYYQ). Defaults to the most recent loaded for the chosen state.

lat

Any of:

number

number

>= -90 <= 90

null

null

Latitude in WGS84 degrees. Required together with lng.

lng

Any of:

number

number

>= -180 <= 180

null

null

Longitude in WGS84 degrees. Required together with lat.

as_of

Any of:

string

string

/^\d{4}-\d{2}-\d{2}$/

null

null

Historical effective date (YYYY-MM-DD). Returns the rate in effect on that date; where historical data isn’t available, the current rate is returned.

mode

Mode

Response shape. simple (default) — a flat single-rate object plus a diagnostic meta block. full — the verbose per-jurisdiction body (rows, components, ambiguity envelope). Every rate field renders as a 5-decimal string in both shapes. Any other value is a 400. The response X-TaxQL-Mode header echoes the shape served.

string

default: simple

Response shape. simple (default) — a flat single-rate object plus a diagnostic meta block. full — the verbose per-jurisdiction body (rows, components, ambiguity envelope). Every rate field renders as a 5-decimal string in both shapes. Any other value is a 400. The response X-TaxQL-Mode header echoes the shape served.

strict

Any of:

string

string

null

null

Input-normalization mode. Omitted or off/false/0 (default) — permissive: malformed-but-recoverable input is normalized and the change is disclosed in meta.normalization; the ZIP is authoritative for the state. on/true/1 — strict: input that would be normalized is rejected (400) with a suggested correction. Any other value is a 400. Accepted and ignored for lat/lng mode.

Header Parameters

X-API-Key

Any of:

string

string

null

null

Responses

200

Successful lookup. Default (mode=simple): a flat single-rate object plus a meta block. mode=full: the verbose per-jurisdiction body. Rate fields are 5-decimal strings; the X-TaxQL-Mode header echoes the shape. meta fields: resolved_via, confidence, warnings, and two effective-date fields — effective_date (ISO YYYY-MM-DD, the served rate’s legal-effect date; populated ONLY where the source publishes a genuine per-row effective date, else null) and effective_date_basis (always present: publisher_effective_date | edition_only | no_published_date — describes the provenance of the date, not a legal characterization; for edition_only/no_published_date the currency/edition signal lives on /v1/freshness). meta.period is DEPRECATED: it carried a quarter-edition code for some states and an ISO date for others and is null for most; prefer effective_date + effective_date_basis, or /v1/freshness.source_period for the edition.

Response Get State Tax V1 Tax State Get

object

key

additional properties

any

400

Invalid input — missing required parameter or malformed value.

401

Missing or invalid X-API-Key / Authorization header.

404

State not supported, or address could not be resolved.

422

Validation Error

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

input

Input

ctx

Context

object

429

Monthly lookup quota exceeded for this API key’s tier.

503

Upstream temporarily unavailable; retry shortly.