# UK Postcode Validator & Enricher (`insulin_junkie/uk-postcode-enricher`) Actor

Validate and enrich UK postcodes with region, district, constituency, lat/long, NHS region, LSOA, MSOA and more. Uses the free postcodes.io API — no API key required.

- **URL**: https://apify.com/insulin\_junkie/uk-postcode-enricher.md
- **Developed by:** [Josh Watterson](https://apify.com/insulin_junkie) (community)
- **Categories:** Lead generation, Developer tools, SEO tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.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 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

## UK Postcode Validator & Enricher

Validate and enrich UK postcodes with full geographic, administrative, political, and health data — using the free [postcodes.io](https://postcodes.io) API. No API key required.

Built for data teams, CRM enrichment, lead generation, and compliance workflows.

***

### What You Get

For each postcode, the actor returns:

| Field | Description |
|---|---|
| `postcode` | Formatted postcode |
| `status` | `VALID` or `INVALID` |
| `latitude` / `longitude` | GPS coordinates |
| `region` | e.g. London, North West, Yorkshire |
| `country` | England, Scotland, Wales, Northern Ireland |
| `district` | Local authority / council district |
| `county` | County (where applicable) |
| `ward` | Electoral ward |
| `constituency` | UK Parliamentary constituency |
| `constituency2024` | Updated 2024 boundary constituency |
| `nhsRegion` | NHS Health Authority region |
| `ccg` | Clinical Commissioning Group |
| `lsoa` | Lower Super Output Area code |
| `msoa` | Middle Super Output Area code |
| `outcode` | Outward code (e.g. SW1A) |
| `incode` | Inward code (e.g. 1AA) |
| `codes` | Raw ONS/GSS codes for all fields |

***

### Input

```json
{
  "postcodes": ["SW1A 1AA", "EC1A 1BB", "M1 1AE"],
  "useBulkApi": true
}
```

| Parameter | Type | Description |
|---|---|---|
| `postcodes` | String\[] | List of UK postcodes to process |
| `useBulkApi` | Boolean | Process in batches of 100 (recommended for large lists, default: `true`) |
| `requestDelayMs` | Integer | Delay between requests in ms (default: `100`) |

Postcodes are case-insensitive and spaces are handled automatically — `sw1a1aa`, `SW1A1AA`, and `SW1A 1AA` all work.

***

### Example Output

```json
{
  "postcode": "SW1A 1AA",
  "status": "VALID",
  "latitude": 51.501009,
  "longitude": -0.141588,
  "region": "London",
  "country": "England",
  "district": "Westminster",
  "county": null,
  "ward": "St James's",
  "constituency": "Cities of London and Westminster",
  "constituency2024": "Cities of London and Westminster",
  "nhsRegion": "London",
  "ccg": "NHS North West London",
  "lsoa": "Westminster 018C",
  "msoa": "Westminster 018",
  "outcode": "SW1A",
  "incode": "1AA",
  "codes": {
    "adminDistrict": "E09000033",
    "adminWard": "E05013806",
    "constituency": "E14000639",
    "lsoa": "E01004736",
    "msoa": "E02000977"
  }
}
```

***

### Use Cases

- **CRM Enrichment** — append region, district, and constituency to customer records
- **Lead Scoring** — segment leads by region, area deprivation (LSOA), or constituency
- **Data Validation** — clean and validate postcode lists before mailing or outreach
- **Geographic Analysis** — map customers by ward, district, or NHS region
- **Compliance** — verify UK addresses for KYC and onboarding workflows
- **Political Targeting** — identify constituency for voter outreach or canvassing

***

### Performance

The actor uses the postcodes.io bulk API to process up to **100 postcodes per request**, making large list enrichment fast and efficient. A list of 10,000 postcodes typically completes in under 2 minutes.

***

### Data Source

All data is sourced from [postcodes.io](https://postcodes.io), which is built on Ordnance Survey, ONS, and Royal Mail open data. The API is free, open, and publicly accessible — no registration required.

***

### Pricing

**$1.00 per 1,000 results + $0.05 per actor start**

***

### Combine With

Pair this actor with the **Companies House Enricher** (`insulin_junkie/companies-house-enricher`) or **FCA Register Scraper** (`insulin_junkie/fca-register-scraper`) to add full geographic context to your UK business data.

# Actor input Schema

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

List of UK postcodes to validate and enrich. Accepts any format — spaces and case are handled automatically.

## `useBulkApi` (type: `boolean`):

Process postcodes in batches of 100 for faster results. Recommended for large lists. Disable for single lookups only.

## `requestDelayMs` (type: `integer`):

Milliseconds to wait between API calls. The postcodes.io API is generous — 100ms is usually fine.

## Actor input object example

```json
{
  "postcodes": [
    "SW1A 1AA",
    "EC1A 1BB",
    "CV11 7AS",
    "M1 1AE",
    "B1 1BB"
  ],
  "useBulkApi": true,
  "requestDelayMs": 100
}
```

# 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",
        "CV11 7AS",
        "M1 1AE",
        "B1 1BB"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("insulin_junkie/uk-postcode-enricher").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",
        "CV11 7AS",
        "M1 1AE",
        "B1 1BB",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("insulin_junkie/uk-postcode-enricher").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 '{
  "postcodes": [
    "SW1A 1AA",
    "EC1A 1BB",
    "CV11 7AS",
    "M1 1AE",
    "B1 1BB"
  ]
}' |
apify call insulin_junkie/uk-postcode-enricher --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=insulin_junkie/uk-postcode-enricher",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/aQJrqRVWPMUog4y3Z/builds/Azcxs8u3VNVrFZfwd/openapi.json