> This page is for version v5.0. > For other versions, use one of these documentation indexes: > - v6.0 (default): https://docs.zip.tax/v-6-0/llms.txt > - v5.0: https://docs.zip.tax/v-5-0/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.zip.tax/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.zip.tax/_mcp/server. # Get Tax Rates (v5.0) GET https://api.zip-tax.com/request/v50 Returns comprehensive tax rates with geocoding support, multi-district breakdown, and Tennessee Single Article Tax calculations. Supports both USA and Canada. Reference: https://docs.zip.tax/v-5-0/api-reference/tax-rates/get-tax-rates-v-50 ## Authentication - `X-API-KEY` header (required) — API Key authentication via header ## Request ### Query parameters - `key` (string, optional) — API key that authenticates the request and resolves the account's plan, entitlements, and rate limits. Supply it either as this query parameter or the X-API-KEY request header. A missing, malformed, or unknown key returns response code 101. - `format` (enum, optional, default: json) — Serialization format of the response body. 'json' (default) returns a JSON object; 'xml' returns the same data as an XML document. - Allowed values: `json`, `xml` - `countryCode` (enum, optional, default: USA) — Country of the lookup: 'USA' (default), 'CAN', or a US territory (ASM, GUM, MNP, PRI, VIR). 'CAN' requires the Canadian rates (rate_loc_can) entitlement; otherwise the request returns response code 112. US territories are looked up via the USA path and require no additional entitlement. - Allowed values: `USA`, `CAN`, `PRI`, `ASM`, `GUM`, `MNP`, `VIR` - `postalcode` (string, optional) — 5-digit US ZIP code to look up. When supplied on its own the response may contain multiple results, one per overlapping jurisdiction. An invalid format returns response code 104. - `address` (string, optional) — Street address to geocode to a single rooftop-level jurisdiction. Geocoding requires the geo_enabled entitlement; an incomplete or ungeocodable address returns response code 109. - `state` (string, optional) — State name or two-letter abbreviation. Used with city or postal code to disambiguate the location. An invalid format returns response code 102. - `stateCode` (string, optional) — Two-letter state code (e.g. CA). Alternative to 'state' for supplying the state as a code rather than a name. - `city` (string, optional) — City name used together with state to narrow the lookup when no street address is supplied. An invalid format returns response code 103. - `county` (string, optional) — County name used to refine the lookup when supplied without a street address. - `lat` (double, optional) — Latitude of a geographic point. When both lat and lng are supplied the API resolves the single jurisdiction containing that point (coordinate lookup). - `lng` (double, optional) — Longitude of a geographic point. When both lat and lng are supplied the API resolves the single jurisdiction containing that point (coordinate lookup). - `adjustment` (string, optional) — Unincorporated-area handling. Only the value 'auto' has an effect: on geo (address) lookups in unincorporated areas it applies the appropriate sourcing adjustment. No default is applied when omitted, and no other value (including 'origin'/'destination') changes the result. - `sat_item_total` (double, optional) — Single-article item total in dollars used to compute Tennessee Single Article Tax (SAT). When greater than 0 and the location is in Tennessee, the response includes the satTaxDetail object describing the local tax limit and additional state tax on the single article. - `historical` (string, optional) — Historical period to price the lookup against, formatted YYYYMM (6 digits, e.g. 202401). Returns the rates that were in effect for that month. Requires historical data to be enabled; an invalid format returns response code 111. ## Response ### 200 OK - `addressDetail` (V50AddressDetail, required) — Normalized and geocoded address details used for the lookup. - `rCode` (long, required) — Numeric status of the request. 100 = success; 101 = invalid/unknown API key; 102 = invalid state; 103 = invalid city; 104 = invalid postal code; 105 = invalid query string; 106 = unknown API error; 107 = feature/version not enabled for the plan; 108 = request rate limit exceeded; 109 = missing/incomplete/invalid address; 110 = valid request but no result found; 111 = invalid historical parameter; 112 = Canadian (international) rates not enabled; 113 = product rate rules not enabled. - `version` (string, required) — Schema version of the response payload (e.g. 'v50'). - `results` (list of V50TaxResult, optional) — Tax rate results for the request, each with a full state/county/city/district breakdown and sourcing model. Empty when no rate is found (response code 110). - `satTaxDetail` (V50SingleArticleTax, optional) — Tennessee Single Article Tax breakdown. Present only when sat_item_total is supplied and the resolved location is in Tennessee. ## Errors ### 422 Get Tax Rates V50request Unprocessable Entity Error Unprocessable Entity - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 429 Get Tax Rates V50request Too Many Requests Error Too Many Requests - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 500 Get Tax Rates V50request Internal Server Error Internal Server Error - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ## Types ### V50AddressDetail - `geoLat` (double, required) — Latitude of the geocoded location, or 0 when the location was not geocoded. - `geoLng` (double, required) — Longitude of the geocoded location, or 0 when the location was not geocoded. - `incorporated` (string, required) — Whether the geocoded point falls within incorporated city limits, as the string 'true' or 'false'. - `normalizedAddress` (string, required) — Standardized address returned by the geocoder, or empty when the location was not geocoded (e.g. postal-code-only lookups). ### V50TaxResult - `citySalesTax` (float, required) — City-level portion of the sales tax rate, as a decimal fraction. 0 when the location has no city-level tax. - `cityTaxCode` (string, required) — Tax code (jurisdiction identifier) for the city; for Texas addresses this is the TAID of the city that contains the address. Empty when the location has no city-level tax. - `cityUseTax` (float, required) — City-level portion of the use tax rate, as a decimal fraction. 0 when the location has no city-level tax. - `countySalesTax` (float, required) — County-level portion of the sales tax rate, as a decimal fraction. - `countyTaxCode` (string, required) — Tax code (jurisdiction identifier) for the county; empty when the location has no county-level tax. - `countyUseTax` (float, required) — County-level portion of the use tax rate, as a decimal fraction. - `district1Code` (string, required) — Tax code (jurisdiction identifier) of the first special tax district applied to this location; empty when no first district applies. - `district1SalesTax` (float, required) — Sales tax rate of the first special district, as a decimal fraction. - `district1UseTax` (float, required) — Use tax rate of the first special district, as a decimal fraction. - `district2Code` (string, required) — Tax code (jurisdiction identifier) of the second special tax district; empty when no second district applies. - `district2SalesTax` (double, required) — Sales tax rate of the second special district, as a decimal fraction. - `district2UseTax` (double, required) — Use tax rate of the second special district, as a decimal fraction. - `district3Code` (string, required) — Tax code (jurisdiction identifier) of the third special tax district; empty when no third district applies. - `district3SalesTax` (double, required) — Sales tax rate of the third special district, as a decimal fraction. - `district3UseTax` (double, required) — Use tax rate of the third special district, as a decimal fraction. - `district4Code` (string, required) — Tax code (jurisdiction identifier) of the fourth special tax district; empty when no fourth district applies. - `district4SalesTax` (double, required) — Sales tax rate of the fourth special district, as a decimal fraction. - `district4UseTax` (double, required) — Use tax rate of the fourth special district, as a decimal fraction. - `district5Code` (string, required) — Tax code (jurisdiction identifier) of the fifth special tax district; empty when no fifth district applies. - `district5SalesTax` (double, required) — Sales tax rate of the fifth special district, as a decimal fraction. - `district5UseTax` (double, required) — Use tax rate of the fifth special district, as a decimal fraction. - `districtSalesTax` (float, required) — Combined special-district sales tax rate (sum of the district1–district5 sales rates), as a decimal fraction. Special districts include transit authorities and other sub-county taxing areas. - `districtUseTax` (float, required) — Combined special-district use tax rate (sum of the district1–district5 use rates), as a decimal fraction. - `geoCity` (string, required) — Uppercase city name of the matched location, as resolved by geocoding. - `geoCounty` (string, required) — Uppercase county name of the matched location. - `geoPostalCode` (string, required) — 5-digit postal code of the matched jurisdiction, as resolved by geocoding. - `geoState` (string, required) — Two-letter uppercase USPS state code of the matched location. - `originDestination` (enum, required) — Sourcing model used for this location: 'D' = destination-based (rate of the ship-to address), 'O' = origin-based (rate of the ship-from address). - Allowed values: `D`, `O` - `stateSalesTax` (float, required) — State-level portion of the sales tax rate, as a decimal fraction. - `stateUseTax` (float, required) — State-level portion of the use tax rate, as a decimal fraction. - `taxSales` (float, required) — Combined sales tax rate for the location as a decimal fraction (e.g. 0.095 = 9.5%). Sum of the applicable state, county, city, and district sales tax rates. - `taxUse` (float, required) — Combined use tax rate for the location as a decimal fraction (e.g. 0.095 = 9.5%). Sum of the applicable state, county, city, and district use tax rates. - `txbFreight` (enum, required) — Whether freight/shipping is taxable in this jurisdiction. 'Y' = taxable, 'N' = not taxable. - Allowed values: `Y`, `N` - `txbService` (enum, required) — Whether services/labor are taxable in this jurisdiction. 'Y' = taxable, 'N' = not taxable. - Allowed values: `Y`, `N` ### V50SingleArticleTax - `appliedTotal` (string, required) — Item total (dollars, formatted as a string) used as the basis for the Tennessee Single Article Tax calculation; echoes the sat_item_total request parameter. - `countyTaxRate` (string, required) — County tax rate (formatted as a string) applied in the single-article tax calculation. - `localTaxLimit` (string, required) — Maximum dollar amount of a single article that is subject to local tax under Tennessee SAT rules (formatted as a string). - `localTaxTotal` (string, required) — Total local tax (dollars, formatted as a string) computed for the single article up to the local tax limit. - `stateAdditionalTaxTotal` (string, required) — Additional state single-article tax (dollars, formatted as a string) applied to the portion of the item above the local tax limit. ### ErrorDetail - `location` (string, optional) — Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' - `message` (string, optional) — Error message text - `value` (any, optional) — The value at the given location ## Examples **Response** ```json { "addressDetail": { "geoLat": 33.65253, "geoLng": -117.74794, "incorporated": "Yes", "normalizedAddress": "200 Spectrum Center Dr, Irvine, CA 92618" }, "rCode": 100, "version": "5.0.0", "results": [ { "citySalesTax": 1, "cityTaxCode": "IRV01", "cityUseTax": 1, "countySalesTax": 0.25, "countyTaxCode": "ORA01", "countyUseTax": 0.25, "district1Code": "D1OC", "district1SalesTax": 0.5, "district1UseTax": 0.5, "district2Code": "", "district2SalesTax": 0, "district2UseTax": 0, "district3Code": "", "district3SalesTax": 0, "district3UseTax": 0, "district4Code": "", "district4SalesTax": 0, "district4UseTax": 0, "district5Code": "", "district5SalesTax": 0, "district5UseTax": 0, "districtSalesTax": 0.5, "districtUseTax": 0.5, "geoCity": "Irvine", "geoCounty": "Orange County", "geoPostalCode": "92618", "geoState": "CA", "originDestination": "destination", "stateSalesTax": 6, "stateUseTax": 6, "taxSales": 7.75, "taxUse": 7.75, "txbFreight": "taxable", "txbService": "nontaxable" } ] } ``` **SDK Code** ```python import requests url = "https://api.zip-tax.com/request/v50" querystring = {"address":"200 Spectrum Center Dr Irvine CA","key":"your-api-key"} response = requests.get(url, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.zip-tax.com/request/v50?address=200+Spectrum+Center+Dr+Irvine+CA&key=your-api-key'; const options = {method: 'GET'}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.zip-tax.com/request/v50?address=200+Spectrum+Center+Dr+Irvine+CA&key=your-api-key" req, _ := http.NewRequest("GET", url, nil) res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.zip-tax.com/request/v50?address=200+Spectrum+Center+Dr+Irvine+CA&key=your-api-key") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.zip-tax.com/request/v50?address=200+Spectrum+Center+Dr+Irvine+CA&key=your-api-key") .asString(); ``` ```php request('GET', 'https://api.zip-tax.com/request/v50?address=200+Spectrum+Center+Dr+Irvine+CA&key=your-api-key'); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.zip-tax.com/request/v50?address=200+Spectrum+Center+Dr+Irvine+CA&key=your-api-key"); var request = new RestRequest(Method.GET); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let request = NSMutableURLRequest(url: NSURL(string: "https://api.zip-tax.com/request/v50?address=200+Spectrum+Center+Dr+Irvine+CA&key=your-api-key")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```