REST API

By Postal Code

All tax rates that overlap a U.S. ZIP code

Look up every sales tax rate that applies inside a U.S. 5-digit ZIP code. Unlike By Address and By Lat / Lng, which each return a single door-level rate, a postal code request returns every applicable rate for each jurisdiction that overlaps the ZIP, with no geocoding and no door-level disambiguation.

Postal code lookups are not door-level accurate. They don’t adjust for unincorporated areas or special tax jurisdictions, and a single ZIP can span multiple cities, counties, and districts. If you need a single authoritative rate for tax collection or compliance filings, use By Address or By Lat / Lng instead.

When to use a postal code lookup

  • You only have a ZIP and no street address (e.g. a newsletter signup).
  • You’re showing an approximate “rates in your area” summary.
  • You’re working with legacy v50-or-earlier integrations that were built around multi-rate postal code responses.

For transactional use (calculating tax on an order, filing returns), always prefer an address or lat/lng lookup.

Endpoint

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

Send the ZIP in the postalcode query parameter.

Quick example

$curl -H "X-API-Key: YOUR_API_KEY" \
>  "https://api.zip-tax.com/request/v60?postalcode=92618"

Parameters

Required

ParameterTypeDescription
postalcodestringU.S. 5-digit ZIP code. Leading zeros must be preserved: send "02101", not 2101.

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 for XML; remember to also set Content-Type accordingly.

Postal code lookups don’t accept countryCode, taxabilityCode, adjustment, sat_item_total, or historical. Those parameters apply only to address and lat/lng lookups. For Canadian rates, use By Address or By Lat / Lng with countryCode=CAN.

Example response

Because a ZIP can overlap multiple jurisdictions, the response contains a results array with one entry per applicable rate:

1{
2  "version": "v60",
3  "rCode": 100,
4  "results": [
5    {
6      "geoPostalCode": "92618",
7      "geoCity": "IRVINE",
8      "geoCounty": "ORANGE",
9      "geoState": "CA",
10      "taxSales": 0.0775,
11      "taxUse": 0.0775,
12      "rateState": 0.0725,
13      "rateCounty": 0.005,
14      "rateCity": 0,
15      "rateAdditional": 0
16    }
17  ],
18  "addressDetail": null
19}

addressDetail is always null for postal code lookups: there’s no single address to normalize. If you need a normalized address, use an address or lat/lng lookup.

Tips & common pitfalls

Northeastern ZIPs like Boston’s 02101 are strings, not numbers. If your client library serializes the value as an integer, the leading zero is stripped and the lookup will fail or return a different ZIP’s results.

Don’t pick the first result blindly. Some ZIPs span two or more cities or special districts. If you must pick one, match on city or county if you have any additional context; otherwise prompt the user or upgrade to an address lookup.

Postal code rates are not adjusted for unincorporated pockets or special district overlays. Using them for tax collection on a real transaction risks under- or over-collecting, both of which create compliance problems. Use address or lat/lng for anything that will end up on a return.

Only the 5-digit ZIP is accepted. If you have a ZIP+4, drop the +4 suffix or (better) use the associated street address for a door-level lookup.

By Address

Door-level rate for a street address. The recommended method for transactional use.

By Lat / Lng

Door-level rate for a coordinate pair. Skip the geocode step.

API Reference

Full parameter and response schema.