> This page is for version v6.0 (default).
> For other versions, use one of these documentation indexes:
> - v6.0 (default): https://docs.zip.tax/v-6-0/llms.txt
> - v5.0: https://docs.zip.tax/v-5-0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.zip.tax/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.zip.tax/_mcp/server.

# By Postal Code

Look up every sales tax rate that applies inside a U.S. 5-digit ZIP
code. Unlike [By Address](by-address) and [By Lat / Lng](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.

> **Warning**
>
> 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](by-address) or [By Lat / Lng](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

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

Send the ZIP in the `postalcode` query parameter.

## Quick example

#### cURL

```bash
curl -H "X-API-KEY: YOUR_API_KEY" \
  "https://api.zip-tax.com/request/v60?postalcode=92618"
```

#### Python

```python
import requests

res = requests.get(
    "https://api.zip-tax.com/request/v60",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    params={"postalcode": "92618"},
)
res.raise_for_status()
data = res.json()
```

#### Node.js

```javascript
const res = await fetch(
  "https://api.zip-tax.com/request/v60?" +
  new URLSearchParams({ postalcode: "92618" }),
  { headers: { "X-API-KEY": "YOUR_API_KEY" } }
);
const data = await res.json();
```

#### Go

```go
req, _ := http.NewRequest("GET",
    "https://api.zip-tax.com/request/v60?postalcode=92618", nil)
req.Header.Set("X-API-KEY", "YOUR_API_KEY")

res, err := http.DefaultClient.Do(req)
```

## Parameters

### Required

| Parameter    | Type   | Description                                                                         |
| ------------ | ------ | ----------------------------------------------------------------------------------- |
| `postalcode` | string | U.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

| Parameter | Type   | Default | Description                                                                             |
| --------- | ------ | ------- | --------------------------------------------------------------------------------------- |
| `format`  | string | `json`  | Response format. Set to `xml` for XML; remember to also set `Content-Type` accordingly. |

> **Info**
>
> Postal code lookups don't accept `countryCode`, `taxabilityCode`,
> `sat_item_total`, or `historical`. Those parameters
> apply only to address and lat/lng lookups. For Canadian rates, use
> [By Address](by-address) or [By Lat / Lng](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:

```json
{
  "version": "v60",
  "rCode": 100,
  "results": [
    {
      "geoPostalCode": "92618",
      "geoCity": "IRVINE",
      "geoCounty": "ORANGE",
      "geoState": "CA",
      "taxSales": 0.0775,
      "taxUse": 0.0775,
      "rateState": 0.0725,
      "rateCounty": 0.005,
      "rateCity": 0,
      "rateAdditional": 0
    }
  ],
  "addressDetail": null
}
```

> **Info**
>
> `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

#### Preserve leading zeros

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.

#### Multiple results per ZIP

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.

#### Not for compliance filings

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.

#### ZIP+4 not supported

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.

## Related

#### [By Address](by-address)

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

#### [By Lat / Lng](by-lat-lng)

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

#### [API Reference](/api-reference)

Full parameter and response schema.