📮 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 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

{
    "lookupMode": "postal_code",
    "country": "US",
    "postalCodes": "90210,10001-10010,60601,30301",
    "outputFormat": "flat",
    "requestDelay": 100
}

City Reverse Lookup

{
    "lookupMode": "city",
    "country": "US",
    "state": "CA",
    "cities": "Los Angeles,San Francisco,San Diego",
    "outputFormat": "one_per_place"
}

Multi-Country Lookup

{
    "lookupMode": "postal_code",
    "country": "US",
    "postalCodes": "10001,20001,30001",
    "multiCountry": "US,CA,GB",
    "outputFormat": "flat"
}

Pakistani Postal Codes

{
    "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.