# ZIP & Postal Code Lookup: Distance, Radius, 120+ Countries (`blueberry_rainstorm/postal-code-lookup`) Actor

Look up ZIP and postal codes in 124 countries: city, state, county and coordinates. Distance between two codes, all codes within a radius, codes for a city, and the nearest code to a latitude/longitude. Bulk or instant API. Not-found rows are free.

- **URL**: https://apify.com/blueberry_rainstorm/postal-code-lookup.md
- **Developed by:** [Pandapi](https://apify.com/blueberry_rainstorm) (community)
- **Categories:** Developer tools, Integrations, Lead generation
- **Features:** Limited permissions, Single-tenant, Server interface
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.30 / 1,000 result founds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## ZIP & Postal Code Lookup: Distance, Radius & 120+ Countries

Look up **ZIP codes and postal codes in 124 countries** and get the city, state, county and coordinates. Also get the **distance between two ZIP codes**, **every ZIP code within a radius**, **all postal codes of a city**, and the **nearest postal code to a latitude/longitude**. Run it in bulk on thousands of rows, or call it as an instant HTTP API.

- 📮 **Postal code lookup**: `US 90210` gives Beverly Hills, California, Los Angeles County, 34.0901, -118.4065
- 📏 **Distance between ZIP codes**: `US 10001; US 94105` gives 4,126 km / 2,564 miles, across countries too
- ⭕ **ZIP codes in a radius**: every code within 10 km (or miles) of a center, nearest first
- 🏙️ **City to postal codes**: `Springfield, IL, US` gives all 35 Springfield ZIP codes in Illinois
- 📍 **Reverse lookup**: `40.7484, -73.9857` gives the nearest code (10118, New York) in any country
- 🌍 **124 countries**: US, Canada, UK, Germany, France, Spain, Italy, Japan, India, Mexico, Brazil, Australia and more
- ⚡ **Fast and cheap**: no scraping, nothing to block. 5,000 lookups take about 5 seconds
- 💸 **You only pay for codes that are found.** Not-found rows are free. No start fee.

### Use cases

- **Clean and enrich address lists**: add city, state, county and coordinates to a CRM or spreadsheet export
- **Store locators and delivery zones**: which ZIP codes are within 25 miles of each store
- **Shipping and logistics**: distance between origin and destination postal codes for quotes
- **Sales territories and lead routing**: assign leads by ZIP code radius or state
- **Form validation and autocomplete**: check a postal code exists and fill in the city
- **Geocoding GPS points**: turn coordinates into the nearest postal code and region

### How to use it

1. Fill one or more sections: **Postal codes to look up**, **Distance between two codes**, **Find codes within a radius of**, **Codes for a city or place**, **Nearest code to coordinates**. You can mix them in one run.
2. Write the 2-letter country first (`US 90210`, `GB SW1A 1AA`, `DE 10115`) or set **Default country**.
3. Run it. Each line gives one row in the dataset, in the order you gave them. Export to Excel, CSV or JSON.

#### Example input

```json
{
  "postalCodes": ["US 90210", "GB SW1A 1AA", "DE 10115", "CA M5V 3L9", "JP 100-0001"],
  "distancePairs": ["US 10001; US 94105", "GB SW1A 1AA; FR 75001"],
  "radiusCenters": ["US 60601"],
  "radius": 10,
  "radiusUnit": "mi",
  "placeNames": ["Springfield, IL, US", "Lyon, FR"],
  "coordinates": ["40.7484, -73.9857"]
}
```

### Output

A lookup row:

```json
{
  "type": "lookup",
  "input": "US 90210",
  "found": true,
  "matchedOn": "exact",
  "country": "US",
  "countryName": "United States",
  "postalCode": "90210",
  "placeName": "Beverly Hills",
  "state": "California",
  "stateCode": "CA",
  "county": "Los Angeles",
  "countyCode": "037",
  "latitude": 34.0901,
  "longitude": -118.4065,
  "places": ["Beverly Hills"],
  "accuracy": 4,
  "error": null
}
```

- **Distance** rows have `distanceKm`, `distanceMiles` and the `from` and `to` places.
- **Radius** rows have `count`, `postalCodes` (nearest first) and `results` with each code's place, state, coordinates and distance.
- **Place** rows have `count`, `postalCodes` and `results`.
- **Reverse** rows have the nearest `postalCode`, its place and `distanceKm` from your point.
- Rows that are not found have `found: false` and an `error` such as `Postal code "99999" was not found in United States.` They are free.

### Instant API (Standby)

Call it like a normal REST API, with answers in milliseconds once it's warm. Send your Apify token as a Bearer header:

```bash
curl -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  "https://blueberry-rainstorm--postal-code-lookup.apify.actor/lookup?code=90210&country=US"
```

| Endpoint | Example |
|---|---|
| `/lookup` | `?code=SW1A 1AA&country=GB` |
| `/distance` | `?from=US 10001&to=US 94105` |
| `/radius` | `?code=60601&country=US&radius=10&unit=mi&limit=500` |
| `/places` | `?name=Springfield&state=IL&country=US` |
| `/reverse` | `?lat=40.7484&lon=-73.9857` (add `&country=US` to stay in one country) |
| `/countries` | every country and how many codes it has |

A found answer is charged like one row. A not-found answer returns HTTP 404 and is free.

### Countries and limits

124 countries from the GeoNames postal code database. Some postal services publish only part of their codes, so for these countries the actor matches the published part and says so in `matchedOn`:

- **United Kingdom, Guernsey, Jersey, Isle of Man**: outward code (`SW1A 1AA` matches `SW1A`)
- **Canada**: first 3 characters, the FSA (`M5V 3L9` matches `M5V`)
- **Netherlands**: first 4 digits. **Ireland**: routing key (`D02`). **Malta**: first 3 letters. **Argentina**: first 5 characters
- **Brazil**: only major codes (ending in `-000`). **Chile, China**: partial codes

Coordinates are estimates for the area of the code (`accuracy` 1 = estimated to 6 = centroid). They are right for distances, radius searches and maps, not for street-level routing. Distances are straight-line (great-circle), not driving distances. Radius searches stay inside the center's country.

Speed: each country's data loads on first use (under a second for most countries). Lookups in a few countries run thousands of rows in seconds. Coordinates spread over many countries are slower, about a minute per 1,000 points; give the run more memory to speed it up.

### Pricing

**$0.30 per 1,000 results found** ($0.0003 each). A radius or place search counts as one result, however many codes it returns. Not found is free. No start fee.

| You run | You pay |
|---|---|
| 1,000 ZIP code lookups | $0.30 |
| 10,000 distances | $3.00 |
| 100 radius searches of 25 miles | $0.03 |

### Use it from the API, n8n, Make or Zapier

Run it with the [Apify API](https://docs.apify.com/api/v2) or the Apify app in n8n, Make or Zapier, then read the dataset:

```bash
curl -X POST "https://api.apify.com/v2/acts/blueberry_rainstorm~postal-code-lookup/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"postalCodes": ["US 90210", "DE 10115"]}'
```

### FAQ

**Where does the data come from?** From [GeoNames](https://www.geonames.org/) postal codes, under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Each row says so in `dataSource`, with the data date in `dataDate`. The data is refreshed when the actor is rebuilt.

**Can I get full UK or Canadian postcodes with street addresses?** No. Those files belong to Royal Mail and Canada Post. This actor uses only openly published codes.

**Is "UK" accepted?** Yes, `UK` works as well as `GB`.

**Why is my code not found?** It may be new, a PO box or company-only code, or a country with partial data (see above). Not-found rows are free.

**Does it include time zones or area codes?** Not yet. Open an issue if you need them.

### More from Pandapi 🐼

Pandapi makes friendly, no-nonsense data tools: simple input, clean output, and fair pay-per-result prices. Found a bug or need a feature? Open an issue on the Issues tab and we answer fast.

- [Pandapi MCP Server](https://apify.com/blueberry_rainstorm/pandapi-mcp-server): all these tools in Claude, Cursor or any AI agent through one MCP connection
- [Web Page to Markdown](https://apify.com/blueberry_rainstorm/web-page-to-markdown): clean, chunked Markdown from any URL or sitemap, ready for AI and RAG
- [PDF to Text, Markdown & Excel](https://apify.com/blueberry_rainstorm/pdf-to-text-markdown): text, Markdown and real Excel tables from any PDF, with OCR
- [Website Contact Details Scraper](https://apify.com/blueberry_rainstorm/website-contact-finder): business emails, phones and social links, one row per website
- [Website Screenshot](https://apify.com/blueberry_rainstorm/website-screenshot): full-page and mobile screenshots or PDFs of many URLs at once
- [Broken Link Checker](https://apify.com/blueberry_rainstorm/broken-link-checker): every 404, dead link and redirect on a site, with the page it is on
- [Public Tenders Feed](https://apify.com/blueberry_rainstorm/public-tenders-feed): government tenders and contract awards from six official portals
- [App Store Reviews Scraper](https://apify.com/blueberry_rainstorm/app-store-reviews-scraper): iOS reviews, ratings and app details from about 180 countries
- [Google Play Reviews Scraper](https://apify.com/blueberry_rainstorm/google-play-reviews-scraper): Android reviews with developer replies, ratings and app data, many languages
- [Company Jobs Tracker](https://apify.com/blueberry_rainstorm/company-jobs-tracker): every open job from the companies you name (Greenhouse, Lever, Ashby and 8 more), with new and closed jobs tracked
- [Profanity Filter API](https://apify.com/blueberry_rainstorm/profanity-filter): find and mask bad words in 26 languages, leetspeak included, without the Scunthorpe problem
- [HTML to PDF](https://apify.com/blueberry_rainstorm/html-to-pdf): web pages, HTML or a template plus JSON rows (invoices, certificates) to PDF
- [Hacker News Scraper](https://apify.com/blueberry_rainstorm/hacker-news-scraper): stories, comments, Show HN and job posts, filtered your way

# Actor input Schema

## `postalCodes` (type: `array`):

One code per line. Put the 2-letter country first ("US 90210", "GB SW1A 1AA", "DE 10115") or set Default country below. Each row returns place name, state, county and coordinates.

## `distancePairs` (type: `array`):

Two codes per line separated by ";", e.g. "US 10001; US 94105" or "GB SW1A 1AA; FR 75001". Returns the straight-line distance in km and miles.

## `radiusCenters` (type: `array`):

Center codes, one per line, e.g. "US 60601". Each returns every code of the same country within the radius below, nearest first.

## `radius` (type: `number`):

Search radius for the centers above.

## `radiusUnit` (type: `string`):

Kilometers or miles.

## `placeNames` (type: `array`):

"City, state, country" or "City, country", e.g. "Springfield, IL, US" or "Lyon, FR". Returns all postal codes of that place.

## `coordinates` (type: `array`):

"latitude, longitude" per line, e.g. "40.7484, -73.9857". Returns the nearest postal code (any country) and its distance.

## `defaultCountry` (type: `string`):

2-letter ISO code (US, GB, DE, FR, CA, ...) used when a line has no country.

## `maxResultsPerSearch` (type: `integer`):

Caps the list of codes in one radius or place row. The row still reports the full count.

## `maxRequests` (type: `integer`):

Stop after this many lines in total (all sections together).

## Actor input object example

```json
{
  "postalCodes": [
    "US 90210",
    "GB SW1A 1AA",
    "DE 10115",
    "CA M5V 3L9",
    "JP 100-0001"
  ],
  "distancePairs": [
    "US 10001; US 94105"
  ],
  "radiusCenters": [
    "US 60601"
  ],
  "radius": 10,
  "radiusUnit": "km",
  "placeNames": [
    "Springfield, IL, US"
  ],
  "coordinates": [
    "40.7484, -73.9857"
  ],
  "defaultCountry": "US",
  "maxResultsPerSearch": 500,
  "maxRequests": 100000
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "postalCodes": [
        "US 90210",
        "GB SW1A 1AA",
        "DE 10115",
        "CA M5V 3L9",
        "JP 100-0001"
    ],
    "distancePairs": [
        "US 10001; US 94105"
    ],
    "radiusCenters": [
        "US 60601"
    ],
    "placeNames": [
        "Springfield, IL, US"
    ],
    "coordinates": [
        "40.7484, -73.9857"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("blueberry_rainstorm/postal-code-lookup").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "postalCodes": [
        "US 90210",
        "GB SW1A 1AA",
        "DE 10115",
        "CA M5V 3L9",
        "JP 100-0001",
    ],
    "distancePairs": ["US 10001; US 94105"],
    "radiusCenters": ["US 60601"],
    "placeNames": ["Springfield, IL, US"],
    "coordinates": ["40.7484, -73.9857"],
}

# Run the Actor and wait for it to finish
run = client.actor("blueberry_rainstorm/postal-code-lookup").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "postalCodes": [
    "US 90210",
    "GB SW1A 1AA",
    "DE 10115",
    "CA M5V 3L9",
    "JP 100-0001"
  ],
  "distancePairs": [
    "US 10001; US 94105"
  ],
  "radiusCenters": [
    "US 60601"
  ],
  "placeNames": [
    "Springfield, IL, US"
  ],
  "coordinates": [
    "40.7484, -73.9857"
  ]
}' |
apify call blueberry_rainstorm/postal-code-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,blueberry_rainstorm/postal-code-lookup"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/wgVR5YOwqipKgSXy5/builds/FDepSUOwsq1VtU39i/openapi.json
