Skip to content
TaxQL Docs

Quickstart

Terminal window
pip install taxql
from taxql import TaxQL


client = TaxQL(api_key="your-key-here")


response = client.lookup(
    state="tx",
    address="500 W 5th St, Austin, TX 78701",
)


print(f"Rate:       {response.combined_rate * 100:.2f}%")  # Rate:       8.25%
print(f"County:     {response.rate.county}")               # County:     TRAVIS
print(f"Confidence: {response.confidence}")                # Confidence: high

What you get back

Section titled “What you get back”

client.lookup() returns a TaxResponse. By default the API resolves to the single applicable rate for the address, so the ergonomics are simple:

  • response.combined_rate — the total rate as a float (0.0825).
  • response.confidence — exact / high / medium / low / none.
  • response.rate — the per-level breakdown (state, county, city, combined_district_rate) plus the resolved state / zip / city / county.
  • response.warnings — advisories you should surface (see below).

See the API overview for the raw request/response, and Response shape & modes if you need every candidate row for a straddling ZIP (mode=full).

Warnings catch bad input

Section titled “Warnings catch bad input”

If the customer-supplied city doesn’t match the jurisdiction that actually applies at the address, the response includes a place_input_mismatch warning — so you don’t silently charge the wrong rate:

for w in response.warnings:
    if isinstance(w, dict) and w.get("code") == "place_input_mismatch":
        print(f"'{w['customer_input_place']}' → '{w['resolved_place_name']}'")

See Handling warnings for the full list.

Other input modes

Section titled “Other input modes”
from datetime import date


# Location name (DoR-published place name — fast, no geocoding)
client.lookup(state="wa", location="Seattle")


# ZIP only (single best rate; lower confidence on straddling ZIPs)
client.lookup(state="ca", zip="94110")


# Lat/lng (as precise as the point you supply)
client.lookup(state="nm", lat=35.6870, lng=-105.9378)


# Historical query (rate in effect on a past date)
client.lookup(state="wa", zip="98039", as_of=date(2026, 4, 15))

Raw HTTP equivalent

Section titled “Raw HTTP equivalent”
Terminal window
curl -H "X-API-Key: your-key-here" \
     "https://api.taxql.com/v1/tax/tx?address=500%20W%205th%20St,%20Austin,%20TX%2078701"

Next steps

Section titled “Next steps”