Get Tax Rates | Ziptax

Every request locates the applicable jurisdiction(s) with one of three parameter sets. Send the parameters from a single set. When parameters from more than one set are present, the most precise set wins: address, then lat/lng, then postalcode.

Option 1 (recommended) — address. Geocodes the street address to a single rooftop-level jurisdiction and applies unincorporated-area and special-district adjustments. This is the preferred method and the one to use for calculating tax.

Option 2 (alternative) — lat and lng. Resolves the single jurisdiction containing a geographic point. Use it when you already have verified coordinates and want to skip geocoding. Both parameters are required; one on its own is not a coordinate lookup.

Option 3 (general use only, not an accurate rate method) — postalcode, plus optional state (or stateCode), county, and city. Returns every rate that overlaps the ZIP, with no door-level accuracy. The optional parameters only narrow that list; they do not resolve a single jurisdiction. Do not use this set to calculate tax on a transaction. A postal-code lookup (no address and no lat/lng) also returns the legacy v5.0-style response body (version, rCode, results) rather than the structured object documented below.

Options 1 and 2 are geocoded lookups and require a current plan with geocoding; without it the request returns response code 107. A request that supplies none of the three sets returns response code 104.

Walkthroughs with full request and response samples: By Address, By Lat / Lng, By Postal Code.

**Every request locates the applicable jurisdiction(s) with one of three parameter sets.** Send the parameters from a single set. When parameters from more than one set are present, the most precise set wins: `address`, then `lat`/`lng`, then `postalcode`. **Option 1 (recommended) — `address`.** Geocodes the street address to a single rooftop-level jurisdiction and applies unincorporated-area and special-district adjustments. This is the preferred method and the one to use for calculating tax. **Option 2 (alternative) — `lat` and `lng`.** Resolves the single jurisdiction containing a geographic point. Use it when you already have verified coordinates and want to skip geocoding. Both parameters are required; one on its own is not a coordinate lookup. **Option 3 (general use only, not an accurate rate method) — `postalcode`, plus optional `state` (or `stateCode`), `county`, and `city`.** Returns every rate that overlaps the ZIP, with no door-level accuracy. The optional parameters only narrow that list; they do not resolve a single jurisdiction. Do not use this set to calculate tax on a transaction. A postal-code lookup (no `address` and no `lat`/`lng`) also returns the legacy v5.0-style response body (`version`, `rCode`, `results`) rather than the structured object documented below. Options 1 and 2 are geocoded lookups and require a current plan with geocoding; without it the request returns response code 107. A request that supplies none of the three sets returns response code 104. Walkthroughs with full request and response samples: [By Address](/guides/rest-api/by-address), [By Lat / Lng](/guides/rest-api/by-lat-lng), [By Postal Code](/guides/rest-api/by-postal-code).

Authentication

X-API-KEYstring

API Key authentication via header

Query parameters

keystringOptional10-100 characters

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.

formatenumOptionalDefaults to json

Serialization format of the response body. ‘json’ (default) returns a JSON object; ‘xml’ returns the same data as an XML document.

Allowed values:

countryCodeenumOptionalDefaults to 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.

postalcodestringOptionalformat: "^[0-9]{5}$"=5 characters

5-digit US ZIP code to look up. When supplied on its own the response may contain rates for multiple overlapping jurisdictions. An invalid format returns response code 104.

addressstringOptional<=100 characters

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.

statestringOptional<=50 characters

State name or two-letter abbreviation. Used with city or postal code to disambiguate the location. An invalid format returns response code 102.

stateCodestringOptionalformat: "^[A-Z]{2}$"=2 characters

Two-letter state code (e.g. CA). Alternative to ‘state’ for supplying the state as a code rather than a name.

citystringOptional<=50 characters

City name used together with state to narrow the lookup when no street address is supplied. An invalid format returns response code 103.

countystringOptional<=50 characters

County name used to refine the lookup when supplied without a street address.

latdoubleOptional-90-90

Latitude of a geographic point. When both lat and lng are supplied the API resolves the single jurisdiction containing that point (coordinate lookup).

lngdoubleOptional-180-180

Longitude of a geographic point. When both lat and lng are supplied the API resolves the single jurisdiction containing that point (coordinate lookup).

adjustmentenumOptionalDefaults to auto

Sourcing/unincorporated-area handling. Defaults to ‘auto’, which applies the appropriate sourcing adjustment on geo (address) lookups in unincorporated areas. The values ‘origin’ and ‘destination’ are accepted but currently do not change the resolved result.

Allowed values:

sat_item_totaldoubleOptional>=0

Single-article item total in dollars, used for Tennessee Single Article Tax (SAT) calculation on TN address lookups. Note: the v6.0 response does not currently return a SAT breakdown object; the SAT detail (satTaxDetail) is available in the v5.0 response.

historicalstringOptionalformat: "^[0-9]{6}$"

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.

taxabilityCodestringOptionalformat: "^[A-Za-z0-9]{1,10}$"

Product Taxability Information Code (TIC). When supplied, the response includes a productDetail object describing the rate rules that apply to that product category in the resolved jurisdiction. Accepts numeric standard TIC codes (e.g., 20010) or alphanumeric override codes (e.g., CIR00001). Requires the product_rates entitlement for standard codes.

addressDetailExtendedbooleanOptionalDefaults to false

When true, returns a full geocoding object in the response broken into address parts (street, city, postal code, etc.). Defaults to false.

shippingExtendedbooleanOptionalDefaults to false

When true, returns a detailed shipping object to help navigate collection complexity. The GENERAL_RULE value will be one of: EXEMPT, EXEMPT_WHEN_SEPARATELY_STATED, ITEM_SPECIFIC, CONDITIONAL, or TAXABLE. For EXEMPT_WHEN_SEPARATELY_STATED, the response includes a boolean flag, and a natural-language description is included for clarity. Defaults to false.

Response

addressDetailobject

Normalized and geocoded address details used for the lookup.

metadataobject

Versioning and response-code metadata for the request.

serviceobject

Whether services/labor are taxable in the resolved jurisdiction.

shippingobject

Whether freight/shipping is taxable in the resolved jurisdiction.

sourcingRulesobject

Sourcing model (origin- vs destination-based) that applies to the resolved location.

baseRateslist of objectsOptional

Component tax rates broken out by jurisdiction level (state/county/city/district) and tax type (sales/use). Sum the relevant components to obtain a combined rate.

productDetailobjectOptional

Product-specific tax rules. Present only when a taxabilityCode is supplied on the request and the account carries the product_rates entitlement.

taxSummarieslist of objectsOptional

Aggregated sales and use tax rates for the location, summarizing the base rate components.

Errors

401

Get Tax Rates V60request Unauthorized Error

403

Get Tax Rates V60request Forbidden Error

405

Get Tax Rates V60request Method Not Allowed Error

422

Get Tax Rates V60request Unprocessable Entity Error

429

Get Tax Rates V60request Too Many Requests Error

500

Get Tax Rates V60request Internal Server Error

Walkthroughs with full request and response samples: By Address, By Lat / Lng, By Postal Code.

$	curl -G https://api.zip-tax.com/request/v60 \
>	-H "X-API-KEY: <apiKey>" \
>	-d key=your-api-key \
>	--data-urlencode "address=200 Spectrum Center Dr Irvine CA"

1	{
2	"addressDetail": {
3	"normalizedAddress": "200 Spectrum Center Dr, Irvine, CA 92618-5003, United States",
4	"incorporated": "true",
5	"geoLat": 33.65253,
6	"geoLng": -117.74794,
7	"address": {
8	"countryCode": "USA",
9	"countryName": "United States",
10	"stateCode": "CA",
11	"state": "California",
12	"county": "Orange",
13	"city": "Irvine",
14	"street": "Spectrum Center Dr",
15	"postalCode": "92618-5003",
16	"houseNumber": "200"
17	}
18	},
19	"metadata": {
20	"response": {
21	"code": 100,
22	"definition": "http://api.zip-tax.com/request/v60/schema",
23	"message": "Successful API Request.",
24	"name": "RESPONSE_CODE_SUCCESS"
25	},
26	"version": "v60"
27	},
28	"service": {
29	"adjustmentType": "SERVICE_TAXABLE",
30	"description": "Services non-taxable",
31	"taxable": "N"
32	},
33	"shipping": {
34	"adjustmentType": "FREIGHT_TAXABLE",
35	"description": "Freight non-taxable",
36	"taxable": "N",
37	"shippingExtended": {
38	"description": "Separately stated common-carrier or USPS shipping is generally exempt if not above actual cost. Handling is taxable, and seller-delivered charges are often taxable.",
39	"exemptWhenSeparatelyStated": "True",
40	"rule": "CONDITIONAL",
41	"stateCode": "CA",
42	"stateName": "California"
43	}
44	},
45	"sourcingRules": {
46	"adjustmentType": "ORIGIN_DESTINATION",
47	"description": "Destination Based Taxation",
48	"value": "D"
49	},
50	"baseRates": [
51	{
52	"jurDescription": "US State Sales Tax",
53	"jurName": "CA",
54	"jurType": "US_STATE_SALES_TAX",
55	"rate": 0.0725,
56	"jurTaxCode": "06"
57	},
58	{
59	"jurDescription": "US State Use Tax",
60	"jurName": "CA",
61	"jurType": "US_STATE_USE_TAX",
62	"rate": 0.0725,
63	"jurTaxCode": "06"
64	},
65	{
66	"jurDescription": "US County Sales Tax",
67	"jurName": "ORANGE",
68	"jurType": "US_COUNTY_SALES_TAX",
69	"rate": 0.005,
70	"jurTaxCode": "30"
71	},
72	{
73	"jurDescription": "US County Use Tax",
74	"jurName": "ORANGE",
75	"jurType": "US_COUNTY_USE_TAX",
76	"rate": 0.005,
77	"jurTaxCode": "30"
78	},
79	{
80	"jurDescription": "US City Sales Tax",
81	"jurName": "IRVINE",
82	"jurType": "US_CITY_SALES_TAX",
83	"rate": 0,
84	"jurTaxCode": null
85	},
86	{
87	"jurDescription": "US City Use Tax",
88	"jurName": "IRVINE",
89	"jurType": "US_CITY_USE_TAX",
90	"rate": 0,
91	"jurTaxCode": null
92	}
93	],
94	"taxSummaries": [
95	{
96	"rate": 0.0775,
97	"summaryName": "Total Base Sales Tax",
98	"taxType": "SALES_TAX",
99	"displayRates": [
100	{
101	"name": "Total Rate",
102	"rate": 0.0775
103	}
104	]
105	},
106	{
107	"rate": 0.0775,
108	"summaryName": "Total Base Use Tax",
109	"taxType": "USE_TAX",
110	"displayRates": [
111	{
112	"name": "Total Rate",
113	"rate": 0.0775
114	}
115	]
116	}
117	]
118	}