REST API

By Address

Door-level sales tax rate for a street address

Available onAll plans

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. USA (default), CAN, or a US territory (PRI Puerto Rico, ASM American Samoa, GUM Guam, MNP Northern Mariana Islands, VIR U.S. Virgin Islands). US territories are looked up through the US path and need no extra entitlement. 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.
historicalstringnoneMonth to fetch historical rates for, in YYYYMM format (e.g. 202401 for January 2024). Cannot be the current month or in the future. 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      "definition": "http://api.zip-tax.com/request/v60/schema"
9    }
10  },
11  "baseRates": [
12    {
13      "rate": 0.0725,
14      "jurType": "US_STATE_SALES_TAX",
15      "jurName": "CA",
16      "jurDescription": "US State Sales Tax",
17      "jurTaxCode": "06"
18    },
19    {
20      "rate": 0.0725,
21      "jurType": "US_STATE_USE_TAX",
22      "jurName": "CA",
23      "jurDescription": "US State Use Tax",
24      "jurTaxCode": "06"
25    },
26    {
27      "rate": 0.005,
28      "jurType": "US_COUNTY_SALES_TAX",
29      "jurName": "ORANGE",
30      "jurDescription": "US County Sales Tax",
31      "jurTaxCode": "30"
32    },
33    {
34      "rate": 0.005,
35      "jurType": "US_COUNTY_USE_TAX",
36      "jurName": "ORANGE",
37      "jurDescription": "US County Use Tax",
38      "jurTaxCode": "30"
39    },
40    {
41      "rate": 0,
42      "jurType": "US_CITY_SALES_TAX",
43      "jurName": "IRVINE",
44      "jurDescription": "US City Sales Tax",
45      "jurTaxCode": null
46    },
47    {
48      "rate": 0,
49      "jurType": "US_CITY_USE_TAX",
50      "jurName": "IRVINE",
51      "jurDescription": "US City Use Tax",
52      "jurTaxCode": null
53    }
54  ],
55  "service": {
56    "adjustmentType": "SERVICE_TAXABLE",
57    "taxable": "N",
58    "description": "Services non-taxable"
59  },
60  "shipping": {
61    "adjustmentType": "FREIGHT_TAXABLE",
62    "taxable": "N",
63    "description": "Freight non-taxable"
64  },
65  "sourcingRules": {
66    "adjustmentType": "ORIGIN_DESTINATION",
67    "description": "Destination Based Taxation",
68    "value": "D"
69  },
70  "taxSummaries": [
71    {
72      "rate": 0.0775,
73      "taxType": "SALES_TAX",
74      "summaryName": "Total Base Sales Tax",
75      "displayRates": [
76        { "name": "Total Rate", "rate": 0.0775 }
77      ]
78    },
79    {
80      "rate": 0.0775,
81      "taxType": "USE_TAX",
82      "summaryName": "Total Base Use Tax",
83      "displayRates": [
84        { "name": "Total Rate", "rate": 0.0775 }
85      ]
86    }
87  ],
88  "addressDetail": {
89    "normalizedAddress": "200 Spectrum Center Dr, Irvine, CA 92618-5003, United States",
90    "incorporated": "true",
91    "geoLat": 33.65253,
92    "geoLng": -117.74794
93  }
94}

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.

Set countryCode to a US territory code to look these addresses up through the US path: PRI (Puerto Rico), ASM (American Samoa), GUM (Guam), MNP (Northern Mariana Islands), or VIR (U.S. Virgin Islands). Territories use US ZIP codes and need no extra entitlement.

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.

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.