# ZIP/Postal Code Lookup (`moving_beacon-owner1/zippopotam----zip-postal-code-lookup`) Actor Bulk ZIP/postal code lookups and city-to-postal reverse lookups across 60+ countries using the Zippopotam.us API. No API key required. - **URL**: https://apify.com/moving\_beacon-owner1/zippopotam----zip-postal-code-lookup.md - **Developed by:** [Jamshaid Arif](https://apify.com/moving_beacon-owner1) (community) - **Categories:** Developer tools, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $10.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 📮 Zippopotam — ZIP/Postal Code Lookup — Apify Actor Bulk **ZIP/postal code lookups** and **city-to-postal reverse lookups** across **60+ countries** using the [Zippopotam.us](https://www.zippopotam.us/) API. No API key required. ### Features - **60+ countries** — US, UK, Germany, France, India, Pakistan, Canada, Japan, and many more. - **Two lookup modes:** - **Postal Code → Places** — find city, state, and coordinates for postal codes. - **City → Postal Codes** — find all postal codes for a given city and state. - **Batch input** — comma-separated codes, numeric range expansion (`90210-90220`), or mixed. - **Multi-country mode** — look up the same postal codes across multiple countries in one run. - **4 output formats** — flat, one-per-place, nested, geocode-only. - **Configurable rate limiting** — adjustable delay between requests. - **Not-found handling** — skip silently or output placeholder records. ### Input Examples #### Bulk Postal Code Lookup ```json { "lookupMode": "postal_code", "country": "US", "postalCodes": "90210,10001-10010,60601,30301", "outputFormat": "flat", "requestDelay": 100 } ```` #### City Reverse Lookup ```json { "lookupMode": "city", "country": "US", "state": "CA", "cities": "Los Angeles,San Francisco,San Diego", "outputFormat": "one_per_place" } ``` #### Multi-Country Lookup ```json { "lookupMode": "postal_code", "country": "US", "postalCodes": "10001,20001,30001", "multiCountry": "US,CA,GB", "outputFormat": "flat" } ``` #### Pakistani Postal Codes ```json { "lookupMode": "postal_code", "country": "PK", "postalCodes": "44000,54000,75500,46000,50700", "outputFormat": "one_per_place" } ``` ### Input Parameters | Parameter | Type | Default | Description | |---|---|---|---| | `lookupMode` | string | `postal_code` | `postal_code` or `city` | | `country` | string | `US` | ISO 2-letter country code | | `postalCodes` | string | — | Codes to look up: `90210,10001-10005,60601` | | `state` | string | — | State/province for city lookup | | `cities` | string | — | Comma-separated cities for reverse lookup | | `multiCountry` | string | — | Comma-separated ISO codes to query multiple countries | | `requestDelay` | integer | `100` | Milliseconds between API requests | | `skipNotFound` | boolean | `true` | Skip codes that return no results | | `outputFormat` | string | `flat` | Output shape (see below) | | `sortBy` | string | `postal_code_asc` | Sort order | | `maxResults` | integer | `0` | Limit output rows (0 = unlimited) | | `addSequentialId` | boolean | `true` | Add sequential ID to each record | ### Output Formats #### Flat (default) One row per postal code. Multiple places within the same code are joined. | Field | Example | |---|---| | `id` | `1` | | `postal_code` | `90210` | | `country` | `United States` | | `country_code` | `US` | | `place_name` | `Beverly Hills` | | `place_count` | `1` | | `state` | `California` | | `state_abbreviation` | `CA` | | `latitude` | `34.0901` | | `longitude` | `-118.4065` | #### One Per Place Most granular — one row for each place within a postal code. A postal code covering 3 neighborhoods produces 3 rows. #### Nested Original API structure with a `places` array inside each record. #### Geocode Only Minimal: `postal_code`, `country_code`, `place_name`, `latitude`, `longitude`. ### Range Expansion Numeric ranges are automatically expanded: | Input | Expands To | |---|---| | `90210-90215` | `90210, 90211, 90212, 90213, 90214, 90215` | | `10001-10005,90210` | `10001, 10002, 10003, 10004, 10005, 90210` | | `01001-01010` | `01001, 01002, … 01010` (leading zeros preserved) | Ranges are capped at 1,000 codes each to prevent runaway requests. ### Supported Countries AD, AR, AS, AT, AU, BD, BE, BG, BR, CA, CH, CL, CO, CZ, DE, DK, DO, ES, FI, FO, FR, GB, GF, GG, GL, GP, GT, GU, HR, HU, IE, IM, IN, IS, IT, JE, JP, LI, LK, LT, LU, MC, MD, MH, MK, MQ, MT, MX, MY, NL, NO, NZ, PH, PK, PL, PM, PR, PT, RE, RO, RU, SE, SI, SK, SM, TH, TR, UA, US, VA, VI, YT, ZA. ### Use Cases - **Address validation** — verify postal codes map to expected cities/states. - **Geocoding** — get latitude/longitude for postal codes without a paid geocoding API. - **Delivery zone mapping** — map postal code ranges to regions for shipping. - **Market research** — identify which postal codes fall within target regions. - **Data enrichment** — add city/state/coordinates to existing postal code data. - **Form auto-fill** — build postal code lookup tables for address forms. # # Actor input Schema ## `lookupMode` (type: `string`): Choose how to search: look up places by postal code, or find postal codes by city. ## `country` (type: `string`): Select the country for lookups. ## `postalCodes` (type: `string`): Comma-separated postal codes to look up (e.g. '90210,10001,60601'). For numeric ranges use dash notation: '90210-90215' expands to 6 codes. Supports mixed: '90210,10001-10005,60601'. Used in 'Postal Code → Places' mode. ## `state` (type: `string`): State or province abbreviation for city lookup (e.g. 'CA', 'NY', 'Punjab'). Required for 'City → Postal Codes' mode. ## `cities` (type: `string`): Comma-separated city names for reverse lookup (e.g. 'Los Angeles,San Francisco'). Used in 'City → Postal Codes' mode. ## `multiCountry` (type: `string`): Look up the same postal codes across multiple countries. Comma-separated ISO codes (e.g. 'US,CA,GB'). If set, overrides the Country dropdown. ## `requestDelay` (type: `integer`): Delay between API requests in milliseconds. Increase if you hit rate limits. ## `skipNotFound` (type: `boolean`): If checked, postal codes that return no results are silently skipped. Otherwise, a record with null fields is created. ## `outputFormat` (type: `string`): How to structure each record. ## `sortBy` (type: `string`): How to sort the output. ## `maxResults` (type: `integer`): Limit number of records saved. 0 = no limit. ## `addSequentialId` (type: `boolean`): Add auto-incrementing ID (1, 2, 3…) to each record. ## Actor input object example ```json { "lookupMode": "postal_code", "country": "US", "requestDelay": 100, "skipNotFound": true, "outputFormat": "flat", "sortBy": "postal_code_asc", "maxResults": 0, "addSequentialId": true } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("moving_beacon-owner1/zippopotam----zip-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("moving_beacon-owner1/zippopotam----zip-postal-code-lookup").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call moving_beacon-owner1/zippopotam----zip-postal-code-lookup --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=moving_beacon-owner1/zippopotam----zip-postal-code-lookup", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "ZIP/Postal Code Lookup", "description": "Bulk ZIP/postal code lookups and city-to-postal reverse lookups across 60+ countries using the Zippopotam.us API. No API key required.", "version": "0.0", "x-build-id": "rIQpKcDH1osuMpbrT" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/moving_beacon-owner1~zippopotam----zip-postal-code-lookup/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-moving_beacon-owner1-zippopotam----zip-postal-code-lookup", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/moving_beacon-owner1~zippopotam----zip-postal-code-lookup/runs": { "post": { "operationId": "runs-sync-moving_beacon-owner1-zippopotam----zip-postal-code-lookup", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/moving_beacon-owner1~zippopotam----zip-postal-code-lookup/run-sync": { "post": { "operationId": "run-sync-moving_beacon-owner1-zippopotam----zip-postal-code-lookup", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "lookupMode", "country" ], "properties": { "lookupMode": { "title": "Lookup Mode", "enum": [ "postal_code", "city" ], "type": "string", "description": "Choose how to search: look up places by postal code, or find postal codes by city.", "default": "postal_code" }, "country": { "title": "Country", "enum": [ "AD", "AR", "AS", "AT", "AU", "BD", "BE", "BG", "BR", "CA", "CH", "CL", "CO", "CZ", "DE", "DK", "DO", "ES", "FI", "FO", "FR", "GB", "GF", "GG", "GL", "GP", "GT", "GU", "HR", "HU", "IE", "IM", "IN", "IS", "IT", "JE", "JP", "LI", "LK", "LT", "LU", "MC", "MD", "MH", "MK", "MQ", "MT", "MX", "MY", "NL", "NO", "NZ", "PH", "PK", "PL", "PM", "PR", "PT", "RE", "RO", "RU", "SE", "SI", "SK", "SM", "TH", "TR", "UA", "US", "VA", "VI", "YT", "ZA" ], "type": "string", "description": "Select the country for lookups.", "default": "US" }, "postalCodes": { "title": "Postal Codes", "type": "string", "description": "Comma-separated postal codes to look up (e.g. '90210,10001,60601'). For numeric ranges use dash notation: '90210-90215' expands to 6 codes. Supports mixed: '90210,10001-10005,60601'. Used in 'Postal Code → Places' mode." }, "state": { "title": "State / Province", "type": "string", "description": "State or province abbreviation for city lookup (e.g. 'CA', 'NY', 'Punjab'). Required for 'City → Postal Codes' mode." }, "cities": { "title": "Cities", "type": "string", "description": "Comma-separated city names for reverse lookup (e.g. 'Los Angeles,San Francisco'). Used in 'City → Postal Codes' mode." }, "multiCountry": { "title": "Multi-Country Mode", "type": "string", "description": "Look up the same postal codes across multiple countries. Comma-separated ISO codes (e.g. 'US,CA,GB'). If set, overrides the Country dropdown." }, "requestDelay": { "title": "Request Delay (ms)", "minimum": 0, "maximum": 5000, "type": "integer", "description": "Delay between API requests in milliseconds. Increase if you hit rate limits.", "default": 100 }, "skipNotFound": { "title": "Skip Not Found", "type": "boolean", "description": "If checked, postal codes that return no results are silently skipped. Otherwise, a record with null fields is created.", "default": true }, "outputFormat": { "title": "Output Format", "enum": [ "flat", "one_per_place", "nested", "geocode_only" ], "type": "string", "description": "How to structure each record.", "default": "flat" }, "sortBy": { "title": "Sort By", "enum": [ "postal_code_asc", "postal_code_desc", "place_name_asc", "state_asc", "latitude_asc", "longitude_asc" ], "type": "string", "description": "How to sort the output.", "default": "postal_code_asc" }, "maxResults": { "title": "Maximum Results", "minimum": 0, "type": "integer", "description": "Limit number of records saved. 0 = no limit.", "default": 0 }, "addSequentialId": { "title": "Add Sequential ID", "type": "boolean", "description": "Add auto-incrementing ID (1, 2, 3…) to each record.", "default": true } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```