API overview

The whole API is authenticated HTTPS. A tax lookup is a single GET. This page shows one call and the response it returns; the sidebar’s API Reference documents every endpoint, parameter, and field.

Base URL

https://api.taxql.com

Authentication

Send your key on the X-API-Key header (or Authorization: Bearer <key>). See Authentication for how to get one.

Your first request

curl -H "X-API-Key: your-key-here" \
  "https://api.taxql.com/v1/tax/tx?address=500%20W%205th%20St,%20Austin,%20TX%2078701"

The response

By default the API returns a single flat rate object plus a diagnostic meta block. Every rate-bearing field is a fixed 5-decimal string (so you never lose precision to a float):

{
  "rate": {
    "state": "TX",
    "zip": "78701",
    "city": "AUSTIN",
    "county": "TRAVIS",
    "country": "US",
    "country_rate": "0.00000",
    "state_rate": "0.06250",
    "county_rate": "0.00000",
    "city_rate": "0.01000",
    "combined_district_rate": "0.01000",
    "combined_rate": "0.08250",
    "freight_taxable": true
  },
  "meta": {
    "resolved_via": "address_locator",
    "confidence": "high",
    "effective_date": null,
    "effective_date_basis": "edition_only",
    "period": "20263",
    "warnings": []
  }
}

meta.period is deprecated

meta.period mixed two different facts under one name — a legal-effect date for some states (e.g. New York’s "2025-03-01") and a publication-quarter edition code for others (e.g. Texas’s "20263") — and is null for most jurisdictions. It is frozen for backward compatibility but no longer documented as a rate signal. Use meta.effective_date (the served rate’s legal-effect date, ISO YYYY-MM-DD) and meta.effective_date_basis instead, and GET /v1/freshness’s source_period for the publication edition.

meta.effective_date is populated only where the source Department of Revenue publishes a genuine per-row effective date; where it does not, the field is null and meta.effective_date_basis says why:

effective_date_basis	effective_date	Meaning
publisher_effective_date	ISO date	The source publishes a per-row legal-effect date (e.g. NY, most SST states, the Canadian provinces, IL, LA, ID, ME).
edition_only	null	The source publishes a periodic edition (a quarter), not a per-row date (e.g. TX, FL, CA, WA, AZ, CO, MO, NM — and the single-rate SST states KY, MI, RI, whose feed carries an edition date, not a legal one). The edition is on /v1/freshness.source_period.
no_published_date	null	The source publishes no per-rate effective date; TaxQL holds only an internal verification/load stamp, exposed on /v1/freshness.

The basis names describe provenance — where the value came from — not a legal characterization. TaxQL never derives an effective date from an edition/quarter.

The field set above is the documented response contract; the sample values are representative of a Texas address lookup.

• rate — the single applicable rate for the resolved jurisdiction, broken out by level (state / county / city / combined_district_rate) with the combined_rate total.
• meta.confidence — how certain the resolution is (exact / high / medium / low / none). See the Confidence envelope.
• meta.warnings — advisories you should surface but that don’t invalidate the rate. See Handling warnings.

The X-TaxQL-Mode response header echoes the shape served (simple by default). Pass mode=full for the verbose per-jurisdiction breakdown (rows, components, resolved place) — see Response shape & modes.

Input modes

Pass exactly one of:

Mode	Parameter(s)	Use when
Address	address=	You have a full street address — most precise.
ZIP	zip=	You only have a 5-digit ZIP (or a Canadian postal code on a province route).
Location	location=	You have a DoR-published place/city name.
Coordinates	lat= + lng=	You already have a point.

Add as_of=YYYY-MM-DD to any of them for a historical rate.

Every endpoint

The API Reference in the sidebar is generated from the live OpenAPI spec and covers the tax lookup, the Portability endpoints (rates, orders, nexus), /v1/freshness, and /healthz. The raw spec is at api.taxql.com/openapi.json.