Published sales tax rates, by jurisdiction.
Look up a street address or ZIP+4 and get the state, county, city and special district rates that apply, each with its effective dates and the state file it came from. Rates come from the rate and boundary files that Streamlined Sales Tax member states publish.
curl -s "https://api.olympus.new-odyssey.com/v1/sales-tax/rates/address?street=100+Main+St&state=$STATE&zip=$ZIP" \
-H "X-API-Key: $OLYMPUS_API_KEY"{
"data": {
"status": "matched",
"reason": null,
"date": "…",
"match": { "method": "address_range", "confidence": "high", "attempted": ["address_range"] },
"combined_rates": { "general_intrastate": …, "general_interstate": …, … },
"candidates": [{
"complete": true,
"jurisdictions": [
{ "level": "state", "code": "…", "rates": { … }, "effective_from": "…", "provenance": { … } },
{ "level": "city", "code": "…", "fips": "…", "rates": { … }, "provenance": { … } }
],
"boundary": { "record_type": "A", "provenance": { … } }
}]
},
"meta": {
"datasets": [ … ],
"notices": [{ "code": "not_a_taxability_determination", "message": "…" }]
}
}A rate is not the tax due.
These are the rates each jurisdiction publishes. They don't tell you whether an item is taxable, which location's rate applies to a sale (sourcing), whether you must collect at all (nexus) or whether an exemption applies. Every response says so in meta.notices. We don't calculate the tax on a transaction.
Coverage is limited to the states that GET /v1/sales-tax/coverage lists as published, for the dates it lists. Every other state answers unsupported. We never return a single rate when the location is uncertain.
Address, ZIP, jurisdictions, coverage.
Lookups fall back from the state's address ranges to its ZIP+4 records and then to the 5-digit ZIP, as the SST guide prescribes. match.method and match.confidence say which one answered.
| Endpoint | What it returns |
|---|---|
| GET/v1/sales-tax/rates/address | Rates for a street address |
| GET/v1/sales-tax/rates/zip/{zip} | Rates for a ZIP+4 or 5-digit ZIP |
| GET/v1/sales-tax/states/{state}/jurisdictions | Every jurisdiction rate of a state on a date |
| GET/v1/sales-tax/coverage | States served, their files and the data vintage |
Four statuses, no guessing.
A 5-digit ZIP often spans several cities or districts. Then you get every candidate, marked ambiguous, and the one the state's ZIP record assigns is flagged sst_default. Send a full address or ZIP+4 to narrow it down.
| status | Meaning |
|---|---|
| matched | Exactly one set of jurisdictions applies and each has one published rate. combined_rates is set. |
| ambiguous | The address or ZIP maps to more than one set of jurisdictions. Every candidate is returned with its own rates; no single rate is chosen. |
| unmatched | Nothing in the state's files matches, or a jurisdiction's rate is missing for the date. |
| unsupported | The state is not published, or the date is outside the published range. No rate is returned. |
Limits
Effective dates
Rates and boundaries carry effective dates, and states post next quarter's changes ahead of time. Pass date to look up another day within the published range.
Deterministic matching
Addresses are normalised with fixed rules (USPS suffix and directional abbreviations, unit designators dropped) and matched against the state's own address ranges. No geocoding.
Not included
Transaction tax calculation, product taxability, exemption certificates, and states outside the Streamlined Sales Tax files.