State-specific notes
The generic GET /v1/tax/{state}
endpoint hides per-state differences in how the lookup is resolved.
Most callers don’t need to think about this, but it matters when you
care about precision (or are debugging an unexpected rate).
Highest precision in address mode. Address-mode lookups proxy the Texas Comptroller’s Mulesoft locator, which performs SPD aggregation server-side using polygons we don’t have offline access to. Use address mode for any TX query where you have a street address — ZIP mode misses Special Purpose Districts in border ZIPs where the city boundary cuts through.
ZIP mode is fine for low-stakes lookups but returns a rate row per
candidate code-pair (city × county allocation); pick the row whose
matched_county_allocation_pct is highest for the most common
answer, or walk all rows to surface the ambiguity to your user.
Florida
Section titled “Florida”Rooftop accuracy via the FL DOR Master Address List. Both address mode (preferred) and lat/lng mode resolve via the same address-xref table loaded from the state’s published Master Address List (~9.8M rows). ZIP mode falls back to ZIP-centroid resolution with appropriate confidence downgrade.
California, Washington, New Mexico
Section titled “California, Washington, New Mexico”Polygon overlay. These three states publish authoritative tax boundary polygons (CDTFA in CA, DOR’s loccode polygons in WA, the RGIS polygon set in NM). Lat/lng mode is the most direct path — PostGIS does an indexed point-in-polygon overlay and returns the applicable jurisdiction.
Address mode also works (geocoder → polygon overlay); use whichever input you have.
SST states
Section titled “SST states”24 states belong to the Streamlined Sales Tax governing board
and publish ZIP+4 boundary files. When you pass a full ZIP+4
(zip="12345-6789"), the lookup is rooftop-accurate. With ZIP-5
only, you get the bulk of the state’s value but the SST boundary
table doesn’t resolve to a single answer for boundary ZIPs.
States in this group include: VT, WV, WY, NV, NE, ND, SD, UT, AR, GA, IA, IN, KS, KY, MI, MN, NC, NJ, OH, OK, RI, TN, WI.
Static-rate states
Section titled “Static-rate states”Several states have a flat state-wide rate with no local jurisdiction component (DE 0%, MT 0%, NH 0%, OR 0%, HI varies but single-jurisdiction). For these, all input modes return the same single-row answer; the lookup is essentially a constant-time state-code lookup.
The static_rates module covers: DE, MT, NH, OR, AK (mostly — has
some local overlays), HI, AL, NM (partial), MO (partial), IL
(partial), CO (partial), LA (partial), AZ (partial).
New York
Section titled “New York”Pub 718 publication-keyed. NY’s DTF publishes Publication 718 quarterly with per-locality rates. Lookups use a Census + DTF join — the Census Geocoder resolves the address to a locality identifier, which joins against the loaded Pub 718 row.
ZIP mode also works but with the standard ZIP-overlap caveat: ZIPs that straddle locality boundaries return multiple rows.
Per-state coverage in the OpenAPI spec
Section titled “Per-state coverage in the OpenAPI spec”The API Reference documents the supported state codes in the 404 response detail. New states are added regularly; check the live spec at api.taxql.com/openapi.json for the current list.