> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.zip.tax/v-5-0/guides/rest-api/by-address/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.zip.tax/_mcp/server. # By 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. > **Info** > > 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 ```http 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 ```bash curl -H "X-API-KEY: YOUR_API_KEY" \ "https://api.zip-tax.com/request/v60?address=200+Spectrum+Center+Dr+Irvine+CA+92618" ``` #### Python ```python import requests res = requests.get( "https://api.zip-tax.com/request/v60", headers={"X-API-KEY": "YOUR_API_KEY"}, params={"address": "200 Spectrum Center Dr, Irvine, CA 92618"}, ) res.raise_for_status() data = res.json() ``` #### Node.js ```javascript const res = await fetch( "https://api.zip-tax.com/request/v60?" + new URLSearchParams({ address: "200 Spectrum Center Dr, Irvine, CA 92618", }), { headers: { "X-API-KEY": "YOUR_API_KEY" } } ); const data = await res.json(); ``` #### Go ```go import ( "net/http" "net/url" ) q := url.Values{} q.Set("address", "200 Spectrum Center Dr, Irvine, CA 92618") req, _ := http.NewRequest("GET", "https://api.zip-tax.com/request/v60?"+q.Encode(), nil) req.Header.Set("X-API-KEY", "YOUR_API_KEY") res, err := http.DefaultClient.Do(req) ``` ## Parameters ### Required | Parameter | Type | Description | | --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `address` | string | Full 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 | Parameter | Type | Default | Description | | ---------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `format` | string | `json` | Response format. Set to `xml` if you need XML; remember to also set `Content-Type` accordingly. | | `countryCode` | string | `USA` | ISO 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. | | `taxabilityCode` | string | none | Taxability Information Code (TIC) to get product-specific rules in the response. See the [TIC catalog](https://api.zip-tax.com/data/tic). Requires Pro or Enterprise plan. | | `historical` | string | none | Month 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. | > **Warning** > > 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/response-codes) reference for the full > list. ## Example response ```json { "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](/api-reference). ## Tips & common pitfalls #### URL-encode the address 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. #### Partial addresses are OK 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. #### Canadian addresses 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`. #### US territory addresses 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. #### Rate sourcing (origin vs destination) 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. #### Tennessee Single Article Tax 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. ## Related #### [By Lat / Lng](by-lat-lng) Same endpoint, but supply coordinates instead of a street address. #### [By Postal Code](by-postal-code) ZIP-only lookup. Returns all rates that overlap the postal code. #### [API Reference](/api-reference) Full parameter and response schema. > Door-level sales tax rate for a street address