Name: ZIP Code API: Postal Code Lookup, Distance, Validation
Brand: tidydata
SKU: api-tidydata-postal-codes
Availability: InStock
Author: API Market

TidyData

# ZIP Code API

## Overview

ZIP Code API answers postal code questions for 121 countries and about 1.8 million codes from GeoNames data (CC BY 4.0). It has four endpoints. GET /v1/postal/{country}/{code} returns every place that shares a postal code, with region, province, community, latitude, longitude and an accuracy level. GET /v1/postal/distance takes two codes written as COUNTRY:CODE and returns the straight line (great-circle) distance between their centroids in kilometres and miles. GET /v1/postal/validate tells you whether a code exists and how many places use it, and GET /v1/postal/countries lists the supported countries with the number of codes in each.

It is designed for checkout and address forms that fill in the city from a ZIP code, shipping cost and delivery zone estimates, store locators, CRM data cleaning and reporting by region. Codes are accepted with or without spaces and dashes. In our test, US 90210 resolved to Beverly Hills, Los Angeles, California in 784 ms, and Salamanca 37007 to Madrid 28013 measured 176.5 km. Coverage depth varies by country, so check the countries endpoint for the code count of the markets you serve. The API runs on a global edge network (Cloudflare Workers) and needs only the x-api-market-key header.

## Features

*   **Four endpoints**: Lookup, distance between two codes, validation and the list of supported countries.
*   **121 countries**: About 1.8 million postal codes, with the code count per country available from the countries endpoint.
*   **Place details and coordinates**: Place name, region, province, community, latitude, longitude and an accuracy level for each match.
*   **Distance in km and miles**: Great-circle distance between the centroids of two postal codes.
*   **Flexible input**: Codes are accepted with or without spaces and dashes.
*   **Rate limit**: Every plan allows up to 10 requests per second.

## Use Cases

*   **Checkout and address forms**: Fill in city and state as soon as the customer types a ZIP or postal code.
*   **Shipping estimates**: Use the distance between warehouse and customer codes to set delivery zones or prices.
*   **Store locators**: Turn a visitor's postal code into coordinates and find the nearest locations.
*   **CRM data cleaning**: Validate stored postal codes and add missing city and region fields.
*   **Regional analytics**: Group customers or orders by region and province from their postal codes.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/tidydata/postal-codes
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Look up a postal code

Returns all places for a postal code in the given country with region, province, community, coordinates and accuracy. Use it to autofill addresses or geocode a code.

**Method:** `GET`

**Endpoint:** `/v1/postal/{country}/{code}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `country` | path | ISO country code | string | Yes | - | - |
| `code` | path | Postal/ZIP code | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/postal-codes/v1/postal/US/90210" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "countryCode": "US",
  "postalCode": "90210",
  "found": true,
  "partialMatch": false,
  "count": 1,
  "places": [
    {
      "countryCode": "US",
      "postalCode": "90210",
      "place": "Beverly Hills",
      "region": "California",
      "province": "Los Angeles",
      "community": null,
      "latitude": 34.0901,
      "longitude": -118.4065,
      "accuracy": "place"
    }
  ],
  "attribution": "Postal code data © GeoNames (https://www.geonames.org), CC BY 4.0."
}
```

#### 2. Distance between postal codes

Takes from and to as COUNTRY:CODE and returns both places plus the straight line distance between their centroids in kilometres and miles.

**Method:** `GET`

**Endpoint:** `/v1/postal/distance`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `from` | query | COUNTRY:CODE | string | Yes | - | - |
| `to` | query | COUNTRY:CODE | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/postal-codes/v1/postal/distance?from=ES%3A37007&to=ES%3A28013" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "from": {
    "countryCode": "ES",
    "postalCode": "37007",
    "place": "Salamanca",
    "region": "Castilla - Leon",
    "province": "Salamanca",
    "community": "Salamanca",
    "latitude": 40.9688,
    "longitude": -5.6716,
    "accuracy": "place"
  },
  "to": {
    "countryCode": "ES",
    "postalCode": "28013",
    "place": "Madrid",
    "region": "Madrid",
    "province": "Madrid",
    "community": "Madrid",
    "latitude": 40.4187,
    "longitude": -3.7076,
    "accuracy": "place"
  },
  "distanceKm": 176.5,
  "distanceMiles": 109.7,
  "note": "Straight-line (great-circle) distance between postal code centroids.",
  "attribution": "Postal code data © GeoNames (https://www.geonames.org), CC BY 4.0."
}
```

#### 3. Validate a postal code

Returns whether the code exists in the given country and how many places share it. Use it for quick form validation.

**Method:** `GET`

**Endpoint:** `/v1/postal/validate`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `country` | query | ISO country code | string | Yes | - | - |
| `code` | query | Postal code | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/postal-codes/v1/postal/validate?country=DE&code=10115" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "countryCode": "DE",
  "postalCode": "10115",
  "valid": true,
  "places": 1
}
```

#### 4. List supported countries

Returns the 121 supported country codes with the number of postal codes available for each.

**Method:** `GET`

**Endpoint:** `/v1/postal/countries`

**Parameters:** none.

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/postal-codes/v1/postal/countries" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "count": 121,
  "countries": [
    {
      "countryCode": "AD",
      "postalCodes": 7
    },
    {
      "countryCode": "AE",
      "postalCodes": 178171
    },
    {
      "countryCode": "AI",
      "postalCodes": 1
    }
  ],
  "attribution": "Postal code data © GeoNames (https://www.geonames.org), CC BY 4.0."
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the result is in the response body. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. The body explains the problem. |
| 401 | Unauthorized | The `x-api-market-key` header is missing, invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The requested item or path does not exist. |
| 429 | Too Many Requests | You went over 10 requests per second or used up your plan quota. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

Every plan allows 10 requests per second. The Pro plan includes 25,000 calls a month and the Ultra plan 150,000; when a monthly quota is used up, further calls return `429 Too Many Requests` until the next billing period. The pay-as-you-go plan has no quota and bills US$0.0005 per successful call. If you receive a `429`, back off before retrying and honour any `Retry-After` header.

## FAQ

**How do I write the codes for the distance endpoint?**

Use COUNTRY:CODE for both from and to, for example from=ES:37007 and to=ES:28013.

**Is the distance a driving distance?**

No. It is the straight line (great-circle) distance between the centroids of the two postal codes, given in km and miles.

**Why can one postal code return several places?**

Some codes cover more than one town or district. The lookup returns them all in the places array, and count tells you how many there are.

**Is coverage the same in every country?**

No. The countries endpoint shows how many codes each country has, for example 41,490 for the US and 27,450 for Great Britain but 1,657 for Canada. Check the count before relying on a market.

**Do I need to credit the data source?**

The data comes from GeoNames under CC BY 4.0, which requires attribution. Responses include a ready attribution string you can show.

**How much does the ZIP Code API cost?**

There is no free plan. Pay as you go costs US$0.0005 per call with no monthly fee. Pro is US$4.99 per month for 25,000 calls and Ultra is US$14.99 per month for 150,000 calls. All plans allow 10 requests per second.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Postal code API for 121 countries and 1.8 million codes: place, region, province and coordinates, distance between two codes in km and miles, and validation.