Postal Code Lookup Scraper

Postal Code Lookup Scraper

Resolve any postal code to its place, region, and coordinates in one batch. Feed country and postcode pairs, get back every matching place with its latitude, longitude, and administrative hierarchy. No API key, no rate limits, export to CSV, JSON, Excel, or XML.

Zippopotam is a free postal code lookup service covering over 60 countries, but its API only resolves one postcode at a time and returns nested JSON that is painful to flatten. This Actor resolves thousands of postal codes in a single run, strips the nesting, and returns one flat row per place. It handles multi-place postcodes, short-form codes for the UK, Canada, Netherlands, Brazil, Malta, Crown Dependencies, and Poland, and works without any API key or registration.

Who uses it	What they scrape Zippopotam for
Logistics planners	Batch-validate delivery postcodes and get coordinates for route planning.
CRM data cleaners	Enrich customer records with standardized place names and regions from postal codes.
Market analysts	Map postal code lists to geographic areas for regional reporting.
E-commerce developers	Pre-warm address autocomplete caches with valid postcode-to-place mappings.
GIS specialists	Convert postal code datasets into point layers with latitude and longitude.

What it does

This Actor resolves postal codes to places using the public Zippopotam service and returns each matched place as a flat row with country, postcode, place name, state, and coordinates.

• 🌍 60+ countries supported: ISO-2 codes from ad to za, including US, UK, Canada, Germany, France, Japan, Brazil, and more.
• 📦 Batch lookups: Resolve up to 1,000,000 postal codes per run for paid users, 10 for free preview.
• 🧩 Multi-place explosion: Toggle to split postcodes that match multiple places into separate rows, or keep them packed in one row.
• ✂️ Short-form handling: Automatically strips inward suffixes and spaces for UK, Canada, Netherlands, Brazil, Malta, Crown Dependencies, and Poland.
• 📤 Flat output: Every place comes back as a clean row with country, postcode, place name, state, latitude, and longitude.

Results export to CSV, JSON, Excel, or XML, or straight from the API.

What you can do with Zippopotam data

🚚 Validate delivery postcodes.

A logistics company runs a nightly batch of 50,000 customer postcodes through the Actor to confirm each one resolves to a real place and to append coordinates for route optimization.

🧹 Clean CRM address data.

A data steward feeds a list of postal codes from a CRM export and uses the returned place names and regions to standardize inconsistent address fields.

🗺️ Build regional sales maps.

A market analyst resolves a list of postcodes from sales transactions and maps the resulting latitude and longitude pairs to visualize revenue by territory.

🔎 Pre-warm address autocomplete.

An e-commerce developer populates a search cache with valid postcode-to-place mappings so the storefront autocomplete responds instantly without hitting an external API per keystroke.

📍 Create GIS point layers.

A GIS specialist converts a spreadsheet of postal codes into a point feature class by running the Actor and importing the flat CSV with coordinates into ArcGIS or QGIS.

Why choose this scraper

	What you get
No API key	Uses the public Zippopotam endpoint, no registration or token needed.
Batch scale	Resolve up to a million postcodes in one run instead of one-by-one API calls.
Flat schema	Nested JSON is flattened into a predictable table for CSV, JSON, Excel, or XML export.
Multi-place aware	Postcodes that match several places can be split into individual rows or kept together.
Short-form ready	UK outward codes, Canadian FSAs, and similar short forms are accepted and normalized.

How it compares

No other Store actor targets Zippopotam the same way, so the honest comparison is with the alternatives teams actually weigh.

	Postal Code Lookup Scraper	Build it in-house	By hand
Setup	Run it now, zero config	Days of engineering	None, but hours per pull
When Zippopotam changes	Maintained for you	You fix it	You re-learn the page
Proxies, retries, anti-bot	Built in	Your problem	Browser only
Output	Fixed JSON schema, CSV/Excel export	Whatever you build	Copy-paste
Cost	Pay per result	Engineering time	Analyst hours

Configure the run

Drive the Actor with an array of country and postcode pairs, and control whether multi-place postcodes are exploded into separate rows or packed into one. The Input tab lists every parameter.

A first run with the defaults:

{
 "lookups": [
 {
 "country": "us",
 "postcode": "90210"
 },
 {
 "country": "gb",
 "postcode": "SW1A"
 },
 {
 "country": "de",
 "postcode": "10115"
 }
 ],
 "maxItems": 10
}

A larger pull:

{
 "lookups": [
 {
 "country": "us",
 "postcode": "90210"
 },
 {
 "country": "gb",
 "postcode": "SW1A"
 },
 {
 "country": "de",
 "postcode": "10115"
 }
 ],
 "maxItems": 200
}

Pricing

Pay-per-result: $0.012 per result collected. You pay only for the results written to your dataset.

Results collected	Approximate cost
100 results	$1.20
1,000 results	$12.00
10,000 results	$120.00

New Apify accounts start with $5 in free credit.

Free users

Free-plan runs return up to 10 results as a preview. Upgrade your Apify plan to collect up to 1,000,000 results per run.

Run it

1. Create a free Apify account with $5 in credit.
2. Open the Postal Code Lookup Scraper.
3. Set your inputs and any filters, then click Start.
4. Export the results as CSV, Excel, JSON, or XML from the Dataset tab.

Run it programmatically through the Apify API (run-sync-get-dataset-items) or the ApifyClient for JavaScript and Python.

Use with AI agents (MCP)

Give an AI agent live access to Zippopotam through the Model Context Protocol. Add the Actor to Claude, Cursor, or any MCP client:

$claude mcp add --transport http apify "https://mcp.apify.com?tools=parseforge/zippopotam-postal-lookup-scraper"

Then prompt it in plain language to run the scraper and read back the results.

Troubleshooting

Why am I getting no results?

Check that your country codes are lowercase ISO-2 and your postcodes are valid for that country. For UK, Canada, Netherlands, Brazil, Malta, Crown Dependencies, and Poland, use the short form without spaces or inward suffix.

Why does my run stop after 10 items?

Free users are limited to 10 postal codes for preview. Upgrade to a paid Apify plan to increase maxItems up to 1,000,000.

Why do I get multiple rows for one postcode?

Some postcodes match multiple places. By default, explodePlaces is ON, so each place becomes its own row. Set explodePlaces to false to pack all places into one row.

Why is my UK postcode with a space rejected?

The Actor automatically strips spaces and inward suffixes for UK postcodes. Use the outward form like SW1A instead of SW1A 1AA.

Why does the run take a long time for many postcodes?

The Actor processes lookups sequentially to respect the public service. For very large batches, consider splitting into multiple runs or increasing the timeout.

Why are some fields empty in the output?

Zippopotam may not return all fields for every place. Empty fields are normal when the source data lacks that information.

FAQ

Question	Answer
Which countries does Zippopotam support?	The Actor supports over 60 countries using ISO-2 lowercase codes, including ad, ar, as, at, au, az, be, bd, bg, br, ca, ch, cz, de, dk, do, es, fi, fo, fr, gb, gf, gg, gl, gp, gt, gu, hr, hu, im, in, is, it, je, jp, li, lk, lt, lu, mc, md, mh, mk, mp, mq, mt, mx, my, nc, nl, no, nz, ph, pk, pl, pm, pr, pt, re, ro, ru, se, si, sj, sk, sm, th, tr, ua, us, va, vi, wf, yt, za.
Do I need an API key for Zippopotam?	No. The Actor uses the public Zippopotam endpoint, which does not require registration or an API key.
How many postal codes can I resolve in one run?	Free users can preview up to 10 postal codes. Paid users can set maxItems up to 1,000,000.
What is the input format?	Provide an array of objects, each with a country (ISO-2 lowercase) and a postcode string. For example: [{ "country": "us", "postcode": "90210" }, { "country": "gb", "postcode": "SW1A" }].
What happens if a postcode matches multiple places?	By default, explodePlaces is ON, so each place becomes its own output row. If you turn it OFF, all places for that postcode are packed into a single row.
Does it handle UK outward codes like SW1A?	Yes. For UK, Canada, Netherlands, Brazil, Malta, Crown Dependencies, and Poland, the Actor accepts the short or outward form and automatically strips spaces and inward suffixes.
What fields are returned for each place?	Each row includes the country, postcode, place name, state or region, latitude, and longitude. The exact field list is shown in the sample output.
Can I export the results?	Yes. The Actor outputs a flat dataset that can be exported to CSV, JSON, Excel, or XML from the Apify platform.
Is there a rate limit?	The Actor respects Zippopotam's public service availability. For large batches, the Actor processes requests sequentially to avoid overwhelming the endpoint.
What if a postcode is invalid or not found?	The Actor will return an empty result for that lookup or skip it, depending on the service response. You can check the run log for details.
Can I use this for commercial projects?	Yes, the Actor itself is available on Apify for commercial use. Zippopotam's public API is free to use, but you should review its terms for your specific use case.
How do I run this on a schedule?	You can set up a scheduled task in Apify to run the Actor at regular intervals, for example nightly, to keep your postal code data fresh.

Related actors

Browse the full ParseForge collection for more scrapers.

🆘 Need help? Email parseforge@protonmail.com with your run ID, your input, and what you expected.

⚠️ Disclaimer. This Actor is unofficial and is not affiliated with, endorsed by, or sponsored by Zippopotam. It collects only publicly available data. You are responsible for using the collected data in compliance with the source's terms of service and applicable data-protection laws, including GDPR, CCPA, and PIPL. Do not use it to collect personal data unlawfully.