Skip to navigation
REST API

By Address

Door-level sales tax rate for a street address

View as Markdown
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

GET 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

{
  "metadata": {
    "version": "v60",
    "response": {
      "code": 100,
      "name": "RESPONSE_CODE_SUCCESS",
      "message": "Successful API Request.",
      "definition": "http://api.zip-tax.com/request/v60/schema"
    }
  },
  "baseRates": [
    {
      "rate": 0.0725,
      "jurType": "US_STATE_SALES_TAX",
      "jurName": "CA",
      "jurDescription": "US State Sales Tax",
      "jurTaxCode": "06"
    },
    {
      "rate": 0.0725,
      "jurType": "US_STATE_USE_TAX",
      "jurName": "CA",
      "jurDescription": "US State Use Tax",
      "jurTaxCode": "06"
    },
    {
      "rate": 0.005,
      "jurType": "US_COUNTY_SALES_TAX",
      "jurName": "ORANGE",
      "jurDescription": "US County Sales Tax",
      "jurTaxCode": "30"
    },
    {
      "rate": 0.005,
      "jurType": "US_COUNTY_USE_TAX",
      "jurName": "ORANGE",
      "jurDescription": "US County Use Tax",
      "jurTaxCode": "30"
    },
    {
      "rate": 0,
      "jurType": "US_CITY_SALES_TAX",
      "jurName": "IRVINE",
      "jurDescription": "US City Sales Tax",
      "jurTaxCode": null
    },
    {
      "rate": 0,
      "jurType": "US_CITY_USE_TAX",
      "jurName": "IRVINE",
      "jurDescription": "US City Use Tax",
      "jurTaxCode": null
    }
  ],
  "service": {
    "adjustmentType": "SERVICE_TAXABLE",
    "taxable": "N",
    "description": "Services non-taxable"
  },
  "shipping": {
    "adjustmentType": "FREIGHT_TAXABLE",
    "taxable": "N",
    "description": "Freight non-taxable"
  },
  "sourcingRules": {
    "adjustmentType": "ORIGIN_DESTINATION",
    "description": "Destination Based Taxation",
    "value": "D"
  },
  "taxSummaries": [
    {
      "rate": 0.0775,
      "taxType": "SALES_TAX",
      "summaryName": "Total Base Sales Tax",
      "displayRates": [
        { "name": "Total Rate", "rate": 0.0775 }
      ]
    },
    {
      "rate": 0.0775,
      "taxType": "USE_TAX",
      "summaryName": "Total Base Use Tax",
      "displayRates": [
        { "name": "Total Rate", "rate": 0.0775 }
      ]
    }
  ],
  "addressDetail": {
    "normalizedAddress": "200 Spectrum Center Dr, Irvine, CA 92618-5003, United States",
    "incorporated": "true",
    "geoLat": 33.65253,
    "geoLng": -117.74794
  }
}

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.

Some states tax a single item differently once its price passes a threshold. Pass the price of one item in sat_item_total and the response adds a satTaxDetail object with the tax on that item. baseRates and taxSummaries don’t change. Requires a geo-enabled key.

StateRuleLookups
TNSingle article tax: local tax on the first $1,600 of the item ($300 in Hamblen County outside Morristown, $375 in Hancock County), plus 2.75% state tax on the part from $1,600 to $3,200Address only
AZCity single-item rate: some cities charge a lower city rate once the item passes a threshold, per the Arizona Department of RevenueAddress or lat/lng
FLCounty discretionary sales surtax applies only to the first $5,000 of the itemAddress or lat/lng

For Arizona and Florida, satTaxDetail.singleItemRules lists each rule that changed the item’s tax, with its threshold, standardRate, reducedRate, affectedAmount, and taxChange. When no rule changes the tax (the price is under the threshold, or the city has no single-item rate), there is no satTaxDetail. The breakdown uses the location’s standard rates and doesn’t reflect the rate rules of a taxabilityCode sent with the request. See the API reference for every field.

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.