# Postcodes.io UK Postcode Scraper (`parseforge/postcodes-io-uk-scraper`) Actor

Scrapes UK postcode data from Postcodes.io. Input a list of postcodes or leave empty for a random sample. Returns one row per postcode with coordinates and administrative areas.

- **URL**: https://apify.com/parseforge/postcodes-io-uk-scraper.md
- **Developed by:** [ParseForge](https://apify.com/parseforge) (community)
- **Categories:** Automation, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.52 / 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.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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](https://raw.githubusercontent.com/ParseForge/apify-assets/main/banner.jpg)](https://apify.com/parseforge?fpr=vmoqkp)

### Postcodes.io UK Postcode Scraper

**Scrape UK postcode data from Postcodes.io, the free open-data API, with no key or login.** Get latitude, longitude, administrative areas, and more for any list of postcodes, or pull a random sample. Export to CSV, JSON, Excel, or XML.

Postcodes.io is the free, open-data UK postcode API, but calling it yourself means handling HTTP requests, rate limits, and pagination. This Actor wraps the API into a simple input: paste a list of postcodes or leave it empty for a random sample, and get back one flat row per postcode with its coordinates, ward, district, and other geographies. No API key, no registration, no code.

| Who uses it | What they scrape Postcodes.io for |
|---|---|
| Market researchers | Mapping customer postcodes to regions for demographic analysis |
| Logistics planners | Geocoding delivery postcodes to optimize routes |
| Data analysts | Enriching CRM records with accurate postcode geography |
| Real estate professionals | Checking postcode boundaries for property listings |
| App developers | Testing postcode validation and lookup features |

### What it does

This Actor collects UK postcode data from Postcodes.io and returns each postcode as a flat row with its coordinates and administrative areas.

- 📍 **Bulk lookup:** paste up to a million postcodes and get one row per postcode.
- 🎲 **Random sample:** leave the input empty and the Actor fetches random postcodes from the API.
- 🗺️ **Geocoding:** each row includes latitude and longitude for mapping.
- 🏛️ **Administrative areas:** returns ward, district, county, and other boundaries.
- 📦 **Flat output:** every postcode becomes one row in CSV, JSON, Excel, or XML.

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

### What you can do with Postcodes.io data

**📍 Geocode a customer list.**

A logistics planner pastes thousands of delivery postcodes and gets coordinates to plot on a map and optimize routes.

**🗺️ Enrich CRM records.**

A data analyst runs a list of customer postcodes to add ward, district, and county fields for regional reporting.

**🎲 Generate test data.**

An app developer leaves the input empty to fetch random postcodes and validate a postcode lookup feature.

**🏛️ Check boundaries.**

A real estate professional verifies which administrative area a property postcode falls into for listings.

### Why choose this scraper

|  | What you get |
|---|---|
| **No API key** | Postcodes.io is open data, so you can start scraping immediately |
| **Bulk and random** | Look up specific postcodes or pull a random sample for testing |
| **Geocoding included** | Latitude and longitude come back with every postcode |
| **Flat schema** | One row per postcode, ready for spreadsheets or databases |

### How it compares

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

| | Postcodes.io UK Postcode Scraper | Build it in-house | By hand |
|---|---|---|---|
| Setup | Run it now, zero config | Days of engineering | None, but hours per pull |
| When Postcodes.io 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 from a list of postcodes or leave it empty for a random sample, and set a maximum number of postcodes to collect per run. The Input tab lists every parameter.

A first run with the defaults:

```json
{
  "postcodes": [
    "SW1A 1AA",
    "EC1A 1BB",
    "M32 0JG"
  ],
  "maxItems": 10
}
```

A larger pull:

```json
{
  "postcodes": [
    "SW1A 1AA",
    "EC1A 1BB",
    "M32 0JG"
  ],
  "maxItems": 200
}
```

### Pricing

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

| Results collected | Approximate cost |
|---|---|
| 100 results | $0.50 |
| 1,000 results | $5.00 |
| 10,000 results | $50.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](https://console.apify.com/sign-up?fpr=vmoqkp) to collect up to 1,000,000 results per run.

### Run it

1. [Create a free Apify account with $5 in credit](https://console.apify.com/sign-up?fpr=vmoqkp).
2. Open the [Postcodes.io UK Postcode Scraper](https://apify.com/parseforge/postcodes-io-uk-scraper?fpr=vmoqkp).
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](https://docs.apify.com/api/v2) (`run-sync-get-dataset-items`) or the [ApifyClient](https://docs.apify.com/api/client/js) for JavaScript and Python.

### Use with AI agents (MCP)

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

```bash
claude mcp add --transport http apify "https://mcp.apify.com/?tools=parseforge/postcodes-io-uk-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 you entered valid UK postcodes in the input. If you left the input empty, the Actor should fetch random postcodes, so also check that the maximum postcodes is set to at least 1.

**Why did the run stop before reaching my maximum?**

Postcodes.io may have rate limits or the random endpoint may return fewer postcodes than requested. Try running again or reduce the maximum.

**Why are some postcodes missing from the output?**

Invalid or terminated postcodes may not return data. Check the input list for typos or outdated postcodes.

**Can I get more fields than what is shown?**

The Actor returns all fields provided by the Postcodes.io API for each postcode. If a field is missing, the API may not have data for that postcode.

### FAQ

| Question | Answer |
|---|---|
| Do I need an API key for Postcodes.io? | No. Postcodes.io is a free, open-data API and does not require registration or an API key. |
| How many postcodes can I scrape in one run? | You can set the maximum postcodes field up to 1,000,000 per run. The Actor will stop once it reaches that number. |
| What if I leave the postcodes input empty? | The Actor will fetch a random sample of postcodes from Postcodes.io, up to the maximum you set. |
| What data comes back for each postcode? | Each row includes the postcode, latitude, longitude, and administrative areas like ward, district, and county, plus other fields returned by the API. |
| Can I export the results to CSV? | Yes. The Actor outputs a flat dataset that you can export to CSV, JSON, Excel, or XML from the Apify platform. |
| Is this the official Postcodes.io API? | Yes, this Actor calls the public Postcodes.io API endpoints and returns the data in a structured format. |
| Does this work for postcodes outside the UK? | No. Postcodes.io only covers UK postcodes. For other countries, you would need a different geocoding service. |
| Can I look up terminated postcodes? | Postcodes.io includes some terminated postcodes, but the Actor returns whatever the API provides for your input. |
| How fast is the scraping? | The Actor makes requests to Postcodes.io as quickly as the API allows, and you can control the total number of postcodes per run. |
| What if a postcode is invalid? | The API returns an error for invalid postcodes, and the Actor will skip them or record the error depending on the response. |

### Related actors

Browse the full [ParseForge collection](https://apify.com/parseforge?fpr=vmoqkp) 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 Postcodes.io. 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.

# Actor input Schema

## `postcodes` (type: `array`):

One or more UK postcodes to look up (for example SW1A 1AA, M32 0JG, OX49 5NU). Leave empty to fetch a random sample of postcodes.

## `maxItems` (type: `integer`):

How many postcodes to collect per run.

## Actor input object example

```json
{
  "postcodes": [
    "SW1A 1AA",
    "EC1A 1BB",
    "M32 0JG"
  ],
  "maxItems": 10
}
```

# Actor output Schema

## `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 = {
    "postcodes": [
        "SW1A 1AA",
        "EC1A 1BB",
        "M32 0JG"
    ],
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("parseforge/postcodes-io-uk-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "postcodes": [
        "SW1A 1AA",
        "EC1A 1BB",
        "M32 0JG",
    ],
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("parseforge/postcodes-io-uk-scraper").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 '{
  "postcodes": [
    "SW1A 1AA",
    "EC1A 1BB",
    "M32 0JG"
  ],
  "maxItems": 10
}' |
apify call parseforge/postcodes-io-uk-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,parseforge/postcodes-io-uk-scraper"
        }
    }
}

```

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/4SGHM4FrSTnlX1Mwo/builds/oHRlkLsv6igsTZePW/openapi.json