GET
/v1/tax
Look up a sales tax rate
Returns the combined sales tax rate for a US address or 5-digit ZIP code.
Parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
address |
string | required | A free-form US address ("233 S Wacker Dr, Chicago IL") or just a 5-digit ZIP code ("60606"). Full addresses give rooftop-level precision; ZIPs give ZIP-level rates. | 233 S Wacker Dr, Chicago, IL 60606 |
refresh |
boolean | optional | Set to true to skip the cache and recalculate from source data. You rarely need this — rates are refreshed automatically. | false |
Code samples
# Keep the key in the environment, not in your shell history:
# export GEOVERIO_API_KEY="gv_live_…"
curl --fail-with-body "https://tax.geoverio.com/v1/tax?address=233%20S%20Wacker%20Dr%2C%20Chicago%2C%20IL%2060606&refresh=false" \
-H "Authorization: Bearer $GEOVERIO_API_KEY"// Call this from your server, never from the browser:
// front-end JavaScript ships your key to every visitor.
const KEY = process.env.GEOVERIO_API_KEY;
async function main() {
const res = await fetch("https://tax.geoverio.com/v1/tax?address=233%20S%20Wacker%20Dr%2C%20Chicago%2C%20IL%2060606&refresh=false", {
headers: {
Authorization: `Bearer ${KEY}`
}
});
// Never parse the body before checking the status: an expired key answers
// 401 with a perfectly valid JSON envelope.
if (!res.ok) {
throw new Error(`HTTP ${res.status} — ${await res.text()}`);
}
console.log(await res.json());
}
main().catch((err) => {
console.error(err);
process.exitCode = 1;
});# pip install requests
import os, requests
url = "https://tax.geoverio.com/v1/tax?address=233%20S%20Wacker%20Dr%2C%20Chicago%2C%20IL%2060606&refresh=false"
headers = {"Authorization": "Bearer " + os.environ["GEOVERIO_API_KEY"]}
r = requests.get(url, headers=headers)
r.raise_for_status() # turns 4xx / 5xx into an exception instead of silent bad data
print(r.json())<?php
// Read the key from the server environment — never commit it.
$key = getenv('GEOVERIO_API_KEY');
$ch = curl_init("https://tax.geoverio.com/v1/tax?address=233%20S%20Wacker%20Dr%2C%20Chicago%2C%20IL%2060606&refresh=false");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer $key",
"Accept: application/json",
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status < 200 || $status >= 300) {
fwrite(STDERR, "Request failed — HTTP $status: $body\n");
exit(1);
}
print_r(json_decode($body, true));See a sample response
{
"query": "233 S Wacker Dr, Chicago, IL 60606",
"cached": true,
"geo": {
"city": "Chicago",
"state": "IL",
"county": "Cook",
"latitude": 41.878916229496,
"zip_code": "60606",
"longitude": -87.636602795305,
"county_fips": "17031",
"input_query": "233 S Wacker Dr, Chicago, IL 60606",
"matched_address": "233 S WACKER DR, CHICAGO, IL, 60606"
},
"rate": {
"notes": "",
"state": "IL",
"source": "il_official_address_file",
"status": "resolved",
"city_name": "Chicago",
"city_rate": null,
"districts": [],
"confidence": "zip-level",
"local_rate": 0.0425,
"state_name": "Illinois",
"state_rate": 0.0625,
"total_rate": 0.105,
"county_name": "Cook",
"county_rate": null,
"federal_rate": 0,
"jurisdiction": "60606",
"effective_date": "",
"official_source_url": "https:\/\/tax.illinois.gov\/research\/taxrates\/machine-readable-file-address-specific.html",
"special_district_rate": null,
"breakdown": [
{
"label": "Illinois State",
"rate": 0.0625,
"percent": "6.25%"
},
{
"label": "Local",
"rate": 0.0425,
"percent": "4.25%"
}
],
"summary": "Total Sales Tax = 10.5%\n Illinois State: 6.25%\n Local: 4.25%\nJurisdiction: 60606 (confidence: zip-level)",
"total_percent": "10.5%"
},
"fetched_at": "2026-07-15T18:05:55.424828+00:00",
"extra": {
"cache_key": "IL|60606|233swackerdrchicagoil60606",
"next_refresh_due": "2026-10-01T00:00:00+00:00",
"coverage": {
"mechanism": "state_file",
"needs_key": false,
"status": "live"
}
}
}