# Postal Code Lookup Scraper (60+ Countries) (`parseforge/zippopotam-postal-lookup-scraper`) Actor Resolve postal codes to places, states, and coordinates across 60+ countries. Bulk lookup any list of country and postal code pairs. Returns city, state, latitude, longitude, and full place metadata per match. - **URL**: https://apify.com/parseforge/zippopotam-postal-lookup-scraper.md - **Developed by:** [ParseForge](https://apify.com/parseforge) (community) - **Categories:** Developer tools, Automation, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $9.00 / 1,000 result items This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 ![ParseForge Banner](https://github.com/ParseForge/apify-assets/blob/ad35ccc13ddd068b9d6cba33f323962e39aed5b2/banner.jpg?raw=true) ## ๐Ÿ“ฎ Postal Code Lookup Scraper (60+ Countries) > ๐Ÿš€ **Resolve postal codes to places, states, and coordinates worldwide.** Bulk-lookup any list of country + postcode pairs across **60+ countries**, with automatic outward-code normalization for the UK, Canada, the Netherlands, and more. No API key, no registration, no manual JSON wrangling. > ๐Ÿ•’ **Last updated:** 2026-05-22 ยท **๐Ÿ“Š 11 fields** per record ยท **๐ŸŒ 60+ countries** ยท **๐Ÿ“ฎ outward-code auto-normalize** ยท **๐Ÿ—บ๏ธ lat/lon per match** The **Postal Code Lookup Scraper** queries the Zippopotam open postal index and returns **11 structured fields per record**, including the country, country code, postal code, place name, state, state abbreviation, latitude, longitude, and the full list of places matched by the postcode. Multi-place postcodes can be exploded into one row per place or kept packed into a single row. The catalog covers **60+ countries on every populated continent**, from the U.S. and Canada to Japan, South Africa, Brazil, India, and most of Europe. For the UK, Canada, the Netherlands, Brazil, Malta, Crown Dependencies, and Poland, the source only accepts the outward (short) form of the postcode; this Actor strips spaces and inward suffixes automatically so you can pass natural inputs like `SW1A 1AA` or `M5V 3L9`. | ๐ŸŽฏ Target Audience | ๐Ÿ’ก Primary Use Cases | |---|---| | Address-enrichment platforms, logistics teams, sales operations, GIS engineers, customer-data platforms, fraud-prevention teams | Lead enrichment with geocodes, customer-address normalization, shipping-cost estimation, territory assignment, deliverability checks, ZIP-to-city autocomplete | --- ### ๐Ÿ“‹ What the Postal Code Lookup Scraper does Three workflows in a single run: - ๐Ÿ“ฎ **Bulk postcode resolution.** Pass any list of country + postcode pairs and get place, state, and lat/lon back. - ๐Ÿ‡ฌ๐Ÿ‡ง **Outward-code auto-normalize.** UK, Canada, Netherlands, Brazil, Malta, Crown Dependencies, and Poland accept short-form codes; the Actor strips spaces and inward suffixes for you. - ๐Ÿ”€ **Explode multiple places.** Many U.S. ZIPs and Spanish postcodes resolve to multiple towns. Toggle whether each place becomes its own row or all places are packed into one row. Each record includes the ISO-2 country code, full country name, the normalized postal code, the matched place name, state name and abbreviation, latitude, longitude, and the full place array for downstream re-parsing. > ๐Ÿ’ก **Why it matters:** postal code resolution is the foundation of address normalization, shipping cost estimation, fraud scoring, and CRM territory assignment. Building your own pipeline means handling 60+ country formats and the special-case outward-only countries. This Actor handles all of it. --- ### ๐ŸŽฌ Full Demo _๐Ÿšง Coming soon: a 3-minute walkthrough showing how to go from sign-up to a downloaded dataset._ --- ### โš™๏ธ Input
InputTypeDefaultBehavior
lookupsobject[][{"country":"us","postcode":"90210"}, ...]Array of { country, postcode }. Country is ISO-2 lowercase.
explodePlacesbooleantrueWhen ON, each place inside a multi-place postcode becomes its own row.
maxItemsinteger10Records to return. Free plan caps at 10, paid plan at 1,000,000.
**Example: Beverly Hills, Westminster, and Berlin Mitte.** ```json { "lookups": [ { "country": "us", "postcode": "90210" }, { "country": "gb", "postcode": "SW1A" }, { "country": "de", "postcode": "10115" } ], "explodePlaces": true } ```` **Example: bulk Canadian postal-area resolution.** ```json { "lookups": [ { "country": "ca", "postcode": "M5V" }, { "country": "ca", "postcode": "K1A" }, { "country": "ca", "postcode": "V6B" } ], "explodePlaces": false, "maxItems": 100 } ``` > โš ๏ธ **Good to Know:** the supported country list is fixed (60+ ISO-2 codes). Postal codes for countries outside the supported list will return a per-row error. UK/CA/NL/BR/MT/IM/JE/GG/PL only accept the outward (short) form; the inward suffix is stripped automatically. U.S. ZIP+4 inputs use the leading five digits. *** ### ๐Ÿ“Š Output Each lookup record contains **11 fields**. Download the dataset as CSV, Excel, JSON, or XML. #### ๐Ÿงพ Schema | Field | Type | Example | |---|---|---| | ๐Ÿณ๏ธ `countryCode` | string | `"US"` | | ๐ŸŒ `country` | string | `"United States"` | | ๐Ÿ“ฎ `postCode` | string | `"90210"` | | ๐Ÿ™๏ธ `placeName` | string | `"Beverly Hills"` | | ๐Ÿ—บ๏ธ `state` | string | `"California"` | | ๐Ÿท๏ธ `stateAbbreviation` | string | null | `"CA"` | | ๐Ÿ“ `latitude` | number | `34.0901` | | ๐Ÿ“ `longitude` | number | `-118.4065` | | ๐Ÿ“ฆ `places` | array | `[{ "place name": "Beverly Hills", ... }]` | | ๐Ÿ•’ `scrapedAt` | ISO 8601 | `"2026-05-22T00:00:00.000Z"` | | โŒ `error` | string | null | `null` | #### ๐Ÿ“ฆ Sample records
๐Ÿ‡บ๐Ÿ‡ธ Beverly Hills ZIP ```json { "countryCode": "US", "country": "United States", "postCode": "90210", "placeName": "Beverly Hills", "state": "California", "stateAbbreviation": "CA", "latitude": 34.0901, "longitude": -118.4065, "scrapedAt": "2026-05-22T00:00:00.000Z" } ```
๐Ÿ‡ฌ๐Ÿ‡ง UK outward code (Westminster) ```json { "countryCode": "GB", "country": "United Kingdom", "postCode": "SW1A", "placeName": "London, Westminster", "state": "England", "stateAbbreviation": "ENG", "latitude": 51.4969, "longitude": -0.1316, "scrapedAt": "2026-05-22T00:00:00.000Z" } ```
๐Ÿ‡ฉ๐Ÿ‡ช Berlin Mitte ```json { "countryCode": "DE", "country": "Germany", "postCode": "10115", "placeName": "Berlin Mitte", "state": "Berlin", "stateAbbreviation": "BE", "latitude": 52.5323, "longitude": 13.3846, "scrapedAt": "2026-05-22T00:00:00.000Z" } ```
*** ### โœจ Why choose this Actor | | Capability | |---|---| | ๐ŸŒ | **60+ countries.** US, CA, UK, DE, FR, JP, IN, BR, AU, ZA, and many more. | | ๐Ÿ“ฎ | **Outward-code auto-normalize.** Strips spaces and inward suffixes for UK/CA/NL/BR/MT/IM/JE/GG/PL. | | ๐Ÿ—บ๏ธ | **Lat/lon included.** Ready for direct map plotting or distance math. | | ๐Ÿ”€ | **Multi-place explode.** Toggle row-per-place or row-per-postcode output. | | โšก | **Fast.** 10 lookups in under 5 seconds, 1,000 in under a minute. | | ๐Ÿ” | **Always fresh.** Every run queries the live source. | | ๐Ÿšซ | **No authentication.** Public open dataset, no token required. | > ๐Ÿ“Š Accurate postal code resolution is the foundation of address normalization, shipping cost estimation, fraud scoring, and CRM territory assignment. *** ### ๐Ÿ“ˆ How it compares to alternatives | Approach | Cost | Coverage | Refresh | Filters | Setup | |---|---|---|---|---|---| | **โญ Postal Code Lookup Scraper** *(this Actor)* | $5 free credit, then pay-per-use | **60+ countries** | **Live per run** | bulk pairs, explode toggle | โšก 2 min | | Commercial address validation APIs | $0.005-$0.05 per call | Global | Live | Many | โณ Hours | | Local GeoNames data dumps | Free | Worldwide | Manual refresh | None | ๐Ÿข Days | | Manual lookup via national post sites | Free | One country at a time | Live | UI only | ๐Ÿ•’ Hours | Pick this Actor when you want filterable bulk export with lat/lon and no per-call billing. *** ### ๐Ÿš€ How to use 1. ๐Ÿ“ **Sign up.** [Create a free account with $5 credit](https://console.apify.com/sign-up?fpr=vmoqkp) (takes 2 minutes). 2. ๐ŸŒ **Open the Actor.** Go to the Postal Code Lookup Scraper page on the Apify Store. 3. ๐ŸŽฏ **Set input.** Paste your list of country + postcode pairs and choose the explode behavior. 4. ๐Ÿš€ **Run it.** Click **Start** and let the Actor resolve them. 5. ๐Ÿ“ฅ **Download.** Grab your results in the **Dataset** tab as CSV, Excel, JSON, or XML. > โฑ๏ธ Total time from signup to downloaded dataset: **2-4 minutes.** No coding required. *** ### ๐Ÿ’ผ Business use cases
#### ๐Ÿ“ฆ Logistics & Shipping - Zone-based shipping cost estimation - Last-mile route clustering by postcode region - Carrier zone-skip planning - Address-quality screening before label generation #### ๐Ÿ’ผ Sales Operations - Territory assignment by ZIP or postcode - Lead enrichment with city and state - Account-based marketing geo-targeting - Sales-rep coverage heatmaps
#### ๐Ÿ›ก๏ธ Fraud Prevention - Mismatch detection between billing postcode and IP - ZIP-to-city sanity checks on new accounts - Velocity rules by geographic cluster - Sanctioned-region screening inputs #### ๐Ÿ“Š Customer Data Platforms - Address normalization at ingest - Lat/lon enrichment for map dashboards - Cross-region duplicate detection - Audience segmentation by state or region
*** ### ๐Ÿ”Œ Automating Postal Code Lookup Scraper Control the scraper programmatically for scheduled runs and pipeline integrations: - ๐ŸŸข **Node.js.** Install the `apify-client` NPM package. - ๐Ÿ **Python.** Use the `apify-client` PyPI package. - ๐Ÿ“š See the [Apify API documentation](https://docs.apify.com/api/v2) for full details. The [Apify Schedules feature](https://docs.apify.com/platform/schedules) lets you trigger this Actor on any cron interval. Nightly enrichment runs keep new-signup geocodes in sync automatically. *** ### ๐ŸŒŸ Beyond business use cases Data like this powers more than commercial workflows. The same lookup records support research, education, civic projects, and personal initiatives.
#### ๐ŸŽ“ Research and academia - Urban-geography theses with postcode-level overlays - Reproducible address-resolution experiments - Open-data GIS coursework - Cross-country postal-system comparisons #### ๐ŸŽจ Personal and creative - Personal map mashups and visualizations - Travel-planning spreadsheets - Side-project address autocomplete demos - Portfolio data-viz pieces
#### ๐Ÿค Non-profit and civic - Volunteer outreach by postal area - Civic-tech tools for local advocacy - Open contributions to OpenStreetMap address tagging - Mutual-aid network territory mapping #### ๐Ÿงช Experimentation - Train address-parsing ML toy models - Validate geocoding product prototypes - Prototype agent pipelines that enrich CRM leads - Test map-library performance with bulk markers
*** ### ๐Ÿค– Ask an AI assistant about this scraper Open a ready-to-send prompt about this ParseForge actor in the AI of your choice: - ๐Ÿ’ฌ [**ChatGPT**](https://chat.openai.com/?q=How%20do%20I%20use%20the%20Postal%20Code%20Lookup%20Scraper%20by%20ParseForge%20on%20Apify%3F%20Show%20me%20input%20examples%2C%20output%20fields%2C%20common%20use%20cases%2C%20and%20how%20to%20integrate%20it%20into%20a%20workflow.) - ๐Ÿง  [**Claude**](https://claude.ai/new?q=How%20do%20I%20use%20the%20Postal%20Code%20Lookup%20Scraper%20by%20ParseForge%20on%20Apify%3F%20Show%20me%20input%20examples%2C%20output%20fields%2C%20common%20use%20cases%2C%20and%20how%20to%20integrate%20it%20into%20a%20workflow.) - ๐Ÿ” [**Perplexity**](https://perplexity.ai/search?q=How%20do%20I%20use%20the%20Postal%20Code%20Lookup%20Scraper%20by%20ParseForge%20on%20Apify%3F%20Show%20me%20input%20examples%2C%20output%20fields%2C%20common%20use%20cases%2C%20and%20how%20to%20integrate%20it%20into%20a%20workflow.) - ๐Ÿ…’ [**Copilot**](https://copilot.microsoft.com/?q=How%20do%20I%20use%20the%20Postal%20Code%20Lookup%20Scraper%20by%20ParseForge%20on%20Apify%3F%20Show%20me%20input%20examples%2C%20output%20fields%2C%20common%20use%20cases%2C%20and%20how%20to%20integrate%20it%20into%20a%20workflow.) *** ### โ“ Frequently Asked Questions #### ๐Ÿงฉ How does it work? Provide a list of country + postcode pairs, click Start, and the Actor resolves each pair against the Zippopotam open postal index. One row per matched place is written to the dataset. #### ๐Ÿ“ How accurate are the coordinates? The coordinates approximate the centroid of the postcode area and are accurate within a few kilometers, which is plenty for territory assignment and map plotting. Use a full geocoding service when you need rooftop-level accuracy. #### ๐Ÿ‡ฌ๐Ÿ‡ง Why does UK only accept the outward code? The Zippopotam source indexes UK postcodes at the outward (district) level rather than full sector + unit. The Actor strips spaces and the inward suffix automatically so you can pass natural inputs like `SW1A 1AA`. #### ๐Ÿ”€ What does "explode multiple places" do? Some U.S. ZIPs and Spanish postcodes resolve to multiple towns. With explode ON, each place becomes its own row. With explode OFF, all places for that postcode are packed into a single row's `places` array. #### โฐ Can I schedule regular runs? Yes. Use Apify Schedules to run this Actor on any cron interval and keep downstream enrichment caches in sync. #### โš–๏ธ Is this data legal to use? Yes. Zippopotam republishes open postal data and the underlying records are free for redistribution. #### ๐Ÿ’ผ Can I use this data commercially? Yes. The data is open and may be used commercially. You remain responsible for downstream compliance in your own product. #### ๐Ÿ’ณ Do I need a paid Apify plan? No. The free plan is enough for testing and small runs (10 records per run). A paid plan unlocks scheduling, higher concurrency, and larger datasets. #### ๐Ÿ” What happens if a run fails? Apify retries transient errors automatically. Inspect the log in the Runs tab, adjust the input, and re-run. Partial datasets are preserved. #### ๐ŸŒ Which countries are supported? 60+ countries on every populated continent, listed in the input schema. Major ones: US, CA, GB, DE, FR, IT, ES, JP, IN, BR, MX, AU, NZ, ZA, RU, PL, NL, SE, NO, FI, DK. #### ๐Ÿ†˜ What if I need help? Our support team is here to help. Contact us through the Apify platform or the Tally form linked below. *** ### ๐Ÿ”Œ Integrate with any app Postal Code Lookup Scraper connects to any cloud service via [Apify integrations](https://apify.com/integrations): - [**Make**](https://docs.apify.com/platform/integrations/make) - Automate multi-step workflows - [**Zapier**](https://docs.apify.com/platform/integrations/zapier) - Connect with 5,000+ apps - [**Slack**](https://docs.apify.com/platform/integrations/slack) - Get enrichment summaries in your channels - [**Airbyte**](https://docs.apify.com/platform/integrations/airbyte) - Pipe geocode data into your warehouse - [**GitHub**](https://docs.apify.com/platform/integrations/github) - Trigger runs from commits and releases - [**Google Drive**](https://docs.apify.com/platform/integrations/drive) - Export datasets straight to Sheets You can also use webhooks to trigger downstream actions when a run finishes. Push fresh enrichments into your CRM, or alert your team in Slack when an unsupported country code appears. *** ### ๐Ÿ”— Recommended Actors - [**๐Ÿ—บ๏ธ Nominatim OSM Scraper**](https://apify.com/parseforge/nominatim-osm-scraper) - Geocode addresses via OpenStreetMap - [**โœˆ๏ธ OurAirports Scraper**](https://apify.com/parseforge/ourairports-scraper) - Global airport directory - [**๐Ÿด UK Food Hygiene Ratings Scraper**](https://apify.com/parseforge/fsa-uk-food-hygiene-ratings-scraper) - UK food-safety inspections - [**๐ŸŒ… Sunrise & Sunset Times Scraper**](https://apify.com/parseforge/sunrise-sunset-times-scraper) - Solar event times worldwide - [**๐ŸŒฆ๏ธ NOAA Weather Scraper**](https://apify.com/parseforge/noaa-weather-scraper) - U.S. weather forecasts and observations > ๐Ÿ’ก **Pro Tip:** browse the complete [ParseForge collection](https://apify.com/parseforge) for more reference-data scrapers. *** **๐Ÿ†˜ Need Help?** [**Open our contact form**](https://tally.so/r/BzdKgA) to request a new scraper, propose a custom data project, or report an issue. *** > **โš ๏ธ Disclaimer:** this Actor is an independent tool and is not affiliated with, endorsed by, or sponsored by Zippopotam, GeoNames, any national postal service, or any address-validation provider. All trademarks mentioned are the property of their respective owners. Only publicly available open postal data is collected. # Actor input Schema ## `lookups` (type: `array`): Array of country and postal code pairs to resolve. Each item: { "country": "us", "postcode": "90210" }. For UK, Canada, Netherlands, Brazil, Malta, Crown Dependencies and Poland the source only accepts the outward / short form (e.g. UK 'SW1A', Canada 'M5V', Netherlands '1011'); spaces and the inward suffix are stripped automatically. Supported countries (ISO-2, lowercase): 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. ## `explodePlaces` (type: `boolean`): When ON, each place inside a multi-place postal code becomes its own output row. When OFF, all places for a postcode are packed into a single row. ## `maxItems` (type: `integer`): Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000. ## Actor input object example ```json { "lookups": [ { "country": "us", "postcode": "90210" }, { "country": "gb", "postcode": "SW1A" }, { "country": "de", "postcode": "10115" } ], "explodePlaces": true, "maxItems": 10 } ``` # Actor output Schema ## `overview` (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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "lookups": [ { "country": "us", "postcode": "90210" }, { "country": "gb", "postcode": "SW1A" }, { "country": "de", "postcode": "10115" } ], "maxItems": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("parseforge/zippopotam-postal-lookup-scraper").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 = { "lookups": [ { "country": "us", "postcode": "90210", }, { "country": "gb", "postcode": "SW1A", }, { "country": "de", "postcode": "10115", }, ], "maxItems": 10, } # Run the Actor and wait for it to finish run = client.actor("parseforge/zippopotam-postal-lookup-scraper").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 '{ "lookups": [ { "country": "us", "postcode": "90210" }, { "country": "gb", "postcode": "SW1A" }, { "country": "de", "postcode": "10115" } ], "maxItems": 10 }' | apify call parseforge/zippopotam-postal-lookup-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=parseforge/zippopotam-postal-lookup-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Postal Code Lookup Scraper (60+ Countries)", "description": "Resolve postal codes to places, states, and coordinates across 60+ countries. Bulk lookup any list of country and postal code pairs. Returns city, state, latitude, longitude, and full place metadata per match.", "version": "1.0", "x-build-id": "JiCCG6wWgbKsHOmTh" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/parseforge~zippopotam-postal-lookup-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-parseforge-zippopotam-postal-lookup-scraper", "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/parseforge~zippopotam-postal-lookup-scraper/runs": { "post": { "operationId": "runs-sync-parseforge-zippopotam-postal-lookup-scraper", "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/parseforge~zippopotam-postal-lookup-scraper/run-sync": { "post": { "operationId": "run-sync-parseforge-zippopotam-postal-lookup-scraper", "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", "properties": { "lookups": { "title": "Postal Code Lookups", "type": "array", "description": "Array of country and postal code pairs to resolve. Each item: { \"country\": \"us\", \"postcode\": \"90210\" }. For UK, Canada, Netherlands, Brazil, Malta, Crown Dependencies and Poland the source only accepts the outward / short form (e.g. UK 'SW1A', Canada 'M5V', Netherlands '1011'); spaces and the inward suffix are stripped automatically. Supported countries (ISO-2, lowercase): 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." }, "explodePlaces": { "title": "Explode Multiple Places", "type": "boolean", "description": "When ON, each place inside a multi-place postal code becomes its own output row. When OFF, all places for a postcode are packed into a single row.", "default": true }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 1000000, "type": "integer", "description": "Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000." } } }, "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 } } } } } } } } } } ```