REST API

By Address

Door-level sales tax rate for a street address

Look up the single sales tax rate that applies at a specific street address. Ziptax geocodes the address down to the rooftop and returns the rate adjusted for unincorporated areas and special tax jurisdictions, which is the right answer for an actual delivery or point-of-sale location.

Use this method when you have a customer shipping address, a billing address, or a physical storefront. It’s the most accurate lookup option and what we recommend for most integrations.

Endpoint

1GET https://api.zip-tax.com/request/v60

Send the address in the address query parameter. The full URL-encoded address is the only required input besides your API key.

Quick example

$curl -H "X-API-Key: YOUR_API_KEY" \
>  "https://api.zip-tax.com/request/v60?address=200+Spectrum+Center+Dr+Irvine+CA+92618"

Parameters

Required

ParameterTypeDescription
addressstringFull or partial U.S. street address. URL-encode the value. Ziptax normalizes to the USPS-standard full address; you can read it back in addressDetail.normalizedAddress.

You must also authenticate with your API key via the X-API-Key header (recommended) or the key query parameter.

Optional

ParameterTypeDefaultDescription
formatstringjsonResponse format. Set to xml if you need XML; remember to also set Content-Type accordingly.
countryCodestringUSAISO 3166-1 alpha-3 country code. Currently USA or CAN. Canadian rates require a Pro or Enterprise plan.
taxabilityCodestringnoneTaxability Information Code (TIC) to get product-specific rules in the response. See the TIC catalog. Requires Pro or Enterprise plan.
adjustmentstringnoneOverride the origin/destination sourcing decision. Accepted values: origin, destination, auto.
sat_item_totalnumbernoneItem total for Tennessee Single Article Tax calculation. Only affects TN addresses.
historicalstringnoneISO-8601 date (e.g. 2024-01-15) to fetch historical rates as of that date. Requires Pro or Enterprise plan.

Plan-gated parameters return a specific response code if your account doesn’t have the entitlement: countryCode=CAN returns code 112 (rate_loc_can entitlement), taxabilityCode returns code 113 (product_rates entitlement). See the Response Codes reference for the full list.

Example response

1{
2  "metadata": {
3    "version": "v60",
4    "response": {
5      "code": 100,
6      "name": "RESPONSE_CODE_SUCCESS",
7      "message": "Successful API Request."
8    }
9  },
10  "baseRates": [
11    {
12      "rate": 0.0725,
13      "jurType": "US_STATE_SALES_TAX",
14      "jurName": "CA",
15      "jurDescription": "US State Sales Tax",
16      "jurTaxCode": "06"
17    },
18    {
19      "rate": 0.005,
20      "jurType": "US_COUNTY_SALES_TAX",
21      "jurName": "ORANGE",
22      "jurDescription": "US County Sales Tax",
23      "jurTaxCode": "30"
24    },
25    {
26      "rate": 0,
27      "jurType": "US_CITY_SALES_TAX",
28      "jurName": "IRVINE",
29      "jurDescription": "US City Sales Tax",
30      "jurTaxCode": null
31    }
32  ],
33  "taxSummaries": [
34    {
35      "rate": 0.0775,
36      "taxType": "SALES_TAX",
37      "summaryName": "Total Base Sales Tax",
38      "displayRates": [
39        { "name": "Total Rate", "rate": 0.0775 }
40      ]
41    }
42  ],
43  "sourcingRules": {
44    "adjustmentType": "ORIGIN_DESTINATION",
45    "description": "Destination Based Taxation",
46    "value": "D"
47  },
48  "addressDetail": {
49    "normalizedAddress": "200 Spectrum Center Dr, Irvine, CA 92618-5003, United States",
50    "incorporated": "true",
51    "geoLat": 33.65253,
52    "geoLng": -117.74794
53  }
54}

The full response schema (every field on baseRates, taxSummaries, shipping, service, productDetail, etc.) is documented in the API Reference.

Tips & common pitfalls

Addresses contain spaces, commas, and sometimes # or &, all of which must be percent-encoded. Most HTTP clients do this for you if you pass the address via a params object; if you’re building URLs by hand, use your language’s URL encoder.

You can send just street + ZIP (200 Spectrum Center Dr 92618) or street + city + state. Ziptax normalizes to the full USPS address regardless. Check addressDetail.normalizedAddress in the response if you want to confirm what Ziptax actually geocoded.

Set countryCode=CAN to look up Canadian rates. Canadian lookups require a Pro or Enterprise plan. Accounts without the rate_loc_can entitlement will get response code 112.

Most states use destination-based sourcing, but a handful (e.g. California’s “modified origin” rule) are more nuanced. Ziptax makes the correct decision automatically; sourcingRules in the response tells you which rule was applied. Override with the adjustment parameter only if your nexus rules require something different.

TN applies a reduced state rate to the portion of a single-item sale above a threshold. Pass the item total in sat_item_total to have Ziptax compute the blended rate for you.

By Lat / Lng

Same endpoint, but supply coordinates instead of a street address.

By Postal Code

ZIP-only lookup. Returns all rates that overlap the postal code.

API Reference

Full parameter and response schema.