# UK Postcode & Address Lookup — Batch to 100 + Geolocation (`sian.agency/uk-postcode-address-lookup`) Actor

UK postcode lookup API: resolve any postcode to lat/lng, eastings/northings, district, ward, constituency, LSOA, MSOA, NHS CCG and IMD decile. Batch up to 100 per run, autocomplete search, reverse geocoding and outcode districts. No API key needed.

- **URL**: https://apify.com/sian.agency/uk-postcode-address-lookup.md
- **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community)
- **Categories:** Developer tools, Business, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 resolved postcodes

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## UK Postcode & Address Lookup API: Batch, Search & Geolocation 🚀

[![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![Rightmove Property Scraper](https://img.shields.io/badge/Store-Rightmove%20Property%20Scraper-00DEB6)](https://apify.com/sian.agency/rightmove-property-scraper?fpr=sian) [![Zoopla Property Scraper](https://img.shields.io/badge/Store-Zoopla%20Property%20Scraper-8046F1)](https://apify.com/sian.agency/zoopla-property-scraper?fpr=sian) [![OnTheMarket Property Scraper](https://img.shields.io/badge/Store-OnTheMarket%20Scraper-1F4E79)](https://apify.com/sian.agency/onthemarket-property-scraper?fpr=sian)

#### 📮 Every UK postcode with its coordinates, local authority, constituency and deprivation rank

##### Postcode validation, autocomplete, reverse geocoding and batch enrichment for UK-facing teams

### 🔎 What is the UK Postcode & Address Lookup — and when should you use it?

The **UK Postcode & Address Lookup** turns UK postcodes, partial postcodes or latitude/longitude points into clean, structured rows you can filter, export and feed straight into a spreadsheet, database or AI agent. No account, no portal API key, no browser automation to maintain.

**Use it when you need:** a UK postcode checked against the national register, with its latitude and longitude, local authority, ward, 2024 constituency, LSOA, MSOA and deprivation rank. It also covers batches of up to 100 postcodes, postcode-prefix autocomplete, the nearest postcode to a GPS point, and the areas an outcode covers.

**Use something else when:** you need the homes, listings or sold prices at a postcode rather than the postcode's geography. Use [Rightmove Property Scraper](https://apify.com/sian.agency/rightmove-property-scraper?fpr=sian) for UK homes for sale and to rent, with sold prices. Use [Zoopla Property Scraper](https://apify.com/sian.agency/zoopla-property-scraper?fpr=sian) for UK sale and rental listings with valuations. This actor describes places, not properties or people: it returns no house numbers, street addresses or occupants.

### 🤖 Use with AI agents

Already connected to the [Apify MCP server](https://mcp.apify.com)? Just ask for this Actor by name: sian.agency/uk-postcode-address-lookup

**Your agent can pay for its own runs.** This Actor is eligible for [agentic payments](https://docs.apify.com/platform/actors/publishing/monetize), so an agent can discover it, run it and settle the bill over [x402](https://www.x402.org/) (USDC on Base) or [Skyfire](https://www.skyfire.xyz/) — without an Apify account or API token of its own. Billing is the same either way: per successful row, never for errors.

Otherwise copy this prompt into Claude, ChatGPT, Cursor or any MCP-enabled assistant:

```text
I want to resolve UK postcodes to coordinates, local authority, constituency and ONS statistical areas using the Apify Actor `sian.agency/uk-postcode-address-lookup`.

Use it when I need: a UK postcode checked against the national register, with its latitude and longitude, local authority, ward, 2024 constituency, LSOA, MSOA and deprivation rank. It also covers batches of up to 100 postcodes, postcode-prefix autocomplete, the nearest postcode to a GPS point, and the areas an outcode covers.

Don't use it when: you need the homes, listings or sold prices at a postcode rather than the postcode's geography — use rightmove-property-scraper or zoopla-property-scraper instead.

How to call it: pick one `operation`. Use "lookup" with `postcode` for one full postcode, "batch" with `postcodes` for up to 100, "search" with `postcode` for the start of a postcode (autocomplete), "reverse" with `latitude` and `longitude` for the nearest postcode (add `wideSearch: true` for rural points), or "outcode" with `postcode` for the first half of a postcode.

Start with this input:
{
  "operation": "batch",
  "postcodes": [
    "SW1A 1AA",
    "EH1 1YZ",
    "M1 1AE"
  ]
}

Ask me for the postcodes, postcode prefix or coordinates to resolve, and which fields matter most, then run the Actor and summarise the results as a table.
```

**Things you can ask your agent for:**

- *Add the local authority, ward and constituency to these 87 customer postcodes.*
- *Give me the deprivation rank and LSOA for every postcode in this service-user list.*
- *Which postcode is nearest to 56.9, -4.5? It is out in the Highlands, so search wide.*

Machine-readable API, MCP config and OpenAPI definition for this Actor are published at [apify.com/sian.agency/uk-postcode-address-lookup.md](https://apify.com/sian.agency/uk-postcode-address-lookup.md).

### 📋 Overview

UK postcodes come from Ordnance Survey, Royal Mail and ONS files that are a chore to download, join and keep current. This actor has already done that. Send it a postcode, a list of up to 100, the start of a postcode, or a latitude/longitude, and you get one clean row per postcode back.

It suits teams that check addresses at signup, geocode deliveries, or join ONS statistics such as LSOA and the Index of Multiple Deprivation onto their own data.

**Why teams use it:**

- ✅ **Official open data**: the same Ordnance Survey, ONS and Royal Mail sources behind the national postcode register
- ⚡ **Five operations in one actor**: single lookup, batch of 100, postcode search, reverse geocoding and outcode districts
- 🎯 **Around 20 fields per row**: lat/lng, eastings/northings, country, region, local authority, ward, county, 2024 constituency, LSOA, MSOA, NUTS area, NHS area and deprivation rank
- 💰 **Pay per resolved postcode**: $0.004, falling to $0.002 on higher Apify plans. A mistyped or retired postcode gets a row explaining why and costs nothing
- 💎 **No API key**: nothing to sign up for or rotate

### ✨ Features

- 📮 **Postcode Lookup**: one postcode in, its full record out. Spacing and capitals are fixed for you
- 📦 **Batch of 100**: paste a list and get one row per postcode. Duplicates are dropped before anything is charged
- 🔍 **Postcode Search**: every postcode that starts with what you typed (SW1A, SW1A 1), up to 100 matches, for autocomplete
- 📍 **Reverse Geocode**: the nearest postcode to any UK latitude/longitude, with the distance in metres. Looks within 2 km, or 20 km with wide search on
- 🗺️ **Outcode Districts**: the centre point of the first half of a postcode, plus every local authority, ward and constituency it touches
- 📊 **ONS statistical areas**: LSOA, MSOA and NUTS on every row, ready for demographic joins
- 🏥 **Deprivation rank and NHS area**: the Index of Multiple Deprivation rank and NHS area for each postcode
- 🗳️ **2024 constituency boundaries** wherever the record has them
- 🧾 **Itemised charges**: each run's report shows exactly which events you paid for

### 🎬 Quick Start

Open the actor, pick an operation, type a postcode and press Start. The first row comes back in a couple of seconds.

```bash
curl -X POST "https://api.apify.com/v2/acts/sian.agency~uk-postcode-address-lookup/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"operation":"lookup","postcode":"SW1A 1AA"}'
```

### 🚀 Getting Started (3 Simple Steps)

#### Step 1: Pick your operation

Choose Lookup, Batch, Search, Reverse or Outcode in the input form.

#### Step 2: Give it something to look up

One postcode, a list of up to 100, the start of a postcode, or a latitude/longitude pair.

#### Step 3: Run and export

Rows land in the dataset. Export them as JSON, CSV or Excel, or read them over the API.

**What you get back:**

- Each postcode with its latitude and longitude
- Local authority, ward, constituency and country
- LSOA, MSOA, NHS area and deprivation rank

### 📥 Input Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| operation | string | Yes | One of: lookup, batch, search, reverse, outcode |
| postcode | string | For lookup, search and outcode | A full postcode, the start of one, or an outcode |
| postcodes | array | For batch | Up to 100 UK postcodes |
| latitude | number | For reverse | WGS84 latitude |
| longitude | number | For reverse | WGS84 longitude |
| limit | integer | No | Search only: how many matches to return, 1 to 100 (default 10) |
| wideSearch | boolean | No | Reverse only: look up to 20 km away instead of 2 km |

**Single lookup:**

```json
{
  "operation": "lookup",
  "postcode": "SW1A 1AA"
}
```

**Batch (up to 100):**

```json
{
  "operation": "batch",
  "postcodes": ["SW1A 1AA", "EH1 1YZ", "M1 1AE"]
}
```

**Reverse geocode a rural point:**

```json
{
  "operation": "reverse",
  "latitude": 56.9,
  "longitude": -4.5,
  "wideSearch": true
}
```

### 📤 Output

Each row is one postcode. The main fields:

| Field | Type | Description |
|-------|------|-------------|
| postcode | string | Normalised postcode (e.g. SW1A 1AA) |
| latitude / longitude | number | WGS84 coordinates of the postcode centre |
| eastings / northings | number | OS Grid coordinates in metres |
| country / region | string | England, Scotland, Wales or Northern Ireland, and the English region |
| adminDistrict / adminWard | string | Local authority and electoral ward |
| parliamentaryConstituency | string | Constituency, 2024 boundaries |
| lsoa / msoa / nuts | string | ONS statistical areas |
| ccg | string | NHS area |
| imdRank | number | Index of Multiple Deprivation rank within its nation (1 = most deprived) |
| distanceMeters | number | Reverse only: metres from your point to the postcode |
| query | string | The postcode, search term or "lat,lng" this row answers |
| status | string | success or error |
| errorMessage | string | Error rows only: why the input did not resolve |

**Example row** (a real lookup):

```json
{
  "postcode": "SW1A 1AA",
  "outcode": "SW1A",
  "incode": "1AA",
  "latitude": 51.50101,
  "longitude": -0.141563,
  "country": "England",
  "region": "London",
  "adminDistrict": "Westminster",
  "adminWard": "St James's",
  "parliamentaryConstituency": "Cities of London and Westminster",
  "lsoa": "Westminster 018C",
  "msoa": "Westminster 018",
  "ccg": "NHS West and North London",
  "imdRank": 24862,
  "status": "success"
}
```

### 💼 Use Cases & Examples

#### 1. Checkout autocomplete

**Online shops suggest real postcodes while the shopper types.**

**Input:** the start of a postcode ("SW1A 1")
**Output:** up to 100 matching postcodes with their coordinates and local authority
**Use:** feed the matches into your address form's dropdown

#### 2. Address validation and cleaning

**Data teams check messy CRM postcodes against the national register.**

**Input:** a batch of up to 100 postcodes in any spacing or case
**Output:** normalised postcodes with local authority, ward and constituency, plus a row explaining each one that did not resolve
**Use:** scheduled runs over signup or import queues

#### 3. Geocoding for delivery zones

**Operations teams turn postcodes into coordinates for maps and routing.**

**Input:** postcodes, one or a batch
**Output:** lat/lng plus OS Grid eastings/northings
**Use:** plot customers, draw delivery catchments, feed a routing engine

#### 4. Reverse geocoding from app coordinates

**Field-service and delivery apps often have a GPS pin and need the postcode.**

**Input:** a latitude/longitude pair
**Output:** the nearest postcode, the distance in metres and its full record
**Use:** turn GPS pings into postcodes for reporting

#### 5. Deprivation and small-area analysis

**Public-sector and charity analysts join deprivation data to their own postcode lists.**

**Input:** a batch of postcodes from your service records
**Output:** deprivation rank, LSOA, MSOA and ward for each
**Use:** funding bids, service planning and equity audits

#### 6. Territory planning

**Sales teams map districts to local authorities and constituencies.**

**Input:** outcodes such as M1 or SW1A
**Output:** each outcode's centre point and every local authority, ward and constituency it covers
**Use:** allocate territories and plan field visits

### 🔗 Integration Examples

#### JavaScript/Node.js

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_TOKEN' });

const run = await client.actor('sian.agency/uk-postcode-address-lookup').call({
  operation: 'lookup',
  postcode: 'SW1A 1AA'
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0]);
```

#### Python

```python
from apify_client import ApifyClient
client = ApifyClient('YOUR_TOKEN')

run = client.actor('sian.agency/uk-postcode-address-lookup').call(
    run_input={'operation': 'batch', 'postcodes': ['SW1A 1AA', 'M1 1AE']}
)

for item in client.dataset(run['defaultDatasetId']).iterate_items():
    print(item)
```

#### cURL

```bash
curl -X POST 'https://api.apify.com/v2/acts/sian.agency~uk-postcode-address-lookup/runs?token=YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"operation":"search","postcode":"SW1A","limit":5}'
```

#### Automation Workflows (N8N / Zapier / Make)

1. **Trigger**: a schedule or a webhook
2. **HTTP Request**: call the actor API with your batch
3. **Process**: read the JSON rows from the dataset
4. **Action**: update your CRM, validate a signup, or load a warehouse table

### 📊 Performance & Pricing

#### FREE plan

- **25 resolved postcodes** per run, with every field
- No credit card needed
- Enough to test and to handle small lookups

#### Paid plans

- **No row cap**: batches of 100 per run, as many runs as you need
- Charged per resolved row only, never for rows that did not resolve
- The per-row price drops automatically on higher Apify plans

💰 **$0.004 per resolved postcode**, falling to $0.002 on higher Apify plans, plus a small start fee per run

🔗 [View current pricing](https://apify.com/sian.agency/uk-postcode-address-lookup?fpr=sian)

### ❓ Frequently Asked Questions

**Q: How many postcodes can I process?**
A: On the free plan, 25 resolved rows per run. On paid plans, batches of 100 per run and as many runs as you like.

**Q: Which parts of the UK are covered?**
A: England, Scotland, Wales and Northern Ireland.

**Q: Can I search by street or town name?**
A: No. Search matches the start of a postcode, such as SW1A or SW1A 1. To find a postcode from coordinates, use reverse geocoding.

**Q: What does the deprivation rank mean?**
A: It is the Index of Multiple Deprivation rank of the postcode's small area within its own nation, where 1 is the most deprived. Ranks from different nations are not comparable, because each nation publishes its own index.

**Q: What output formats are available?**
A: JSON, CSV and Excel, exported straight from the Apify dataset.

**Q: How current is the data?**
A: It follows the national postcode register releases, including the 2024 constituency boundaries.

**Q: Is my data private?**
A: Postcodes are looked up and returned to your dataset. They are not shared with anyone else.

**Q: How long does a run take?**
A: A few seconds. A single lookup takes about two, and a full batch of 100 is still one request.

**Q: What about retired postcodes?**
A: They get a row saying the postcode did not resolve, and you are not charged for it.

### 🐛 Troubleshooting

**A postcode you know exists comes back "not found"**

- Check for extra characters. Spacing and capitals are fixed for you, but stray letters are not
- The postcode may have been retired. Search its outcode (for example SW1A) to see the live ones nearby

**Search returns nothing**

- Search only matches the start of a postcode. A street or town name will not match
- Try a shorter prefix, such as the outcode alone

**Reverse geocode finds no postcode**

- By default it looks within 2 km. Turn on wide search to look up to 20 km away
- Check the point is in the UK. Points at sea return a row explaining that nothing was found

**Batch stopped at 100**

- One run resolves at most 100 postcodes. Run the next 100 in another batch

### ⚖️ Is it legal to scrape data?

This actor returns UK open data. It reads no personal data: a postcode row describes a place, not a person.

Attribution, as the data licences require: Contains OS data © Crown copyright and database right. Contains Royal Mail data © Royal Mail copyright and database right. Contains National Statistics data © Crown copyright and database right. Contains NRS data © Crown copyright and database right.

Great Britain postcode data is used under the OS OpenData licence. Northern Ireland postcodes (those starting "BT") fall under the ONSPD licence, which requires a licence from NI Land & Property Services for commercial use; if you use BT rows commercially, check that you hold one.

If you combine these rows with your own customer data, that combined data may be personal data under the **GDPR** and similar laws, and you are responsible for handling it lawfully. You can also read Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/).

### 🤝 Support

- Found a bug or want a feature? Open an issue on the actor's [Issues tab](https://apify.com/sian.agency/uk-postcode-address-lookup/issues)
- See the [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian) for more automation tools
- ✉️ <apify@sian-agency.online>

***

**Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)**

# Changelog

This Actor's version history is a separate document: https://apify.com/sian.agency/uk-postcode-address-lookup/changelog.md

# Actor input Schema

## `operation` (type: `string`):

One operation per run:

- **Postcode Lookup**: one full postcode to its complete record (coordinates, local authority, ward, constituency, ONS areas)
- **Batch Lookup**: up to 100 postcodes per run, one row each
- **Postcode Search**: postcodes that start with what you typed (e.g. SW1A or SW1A 1), for autocomplete
- **Reverse Geocode**: the nearest postcode to a UK latitude/longitude
- **Outcode District**: the centre point and areas covered by the first half of a postcode (e.g. SW1A)

## `postcode` (type: `string`):

LOOKUP: a full UK postcode such as SW1A 1AA.

SEARCH: the start of a postcode, such as SW1A or SW1A 1. Search matches postcodes only, not street or town names.

OUTCODE: the first half of a postcode, such as SW1A.

Spacing and capitals are fixed for you, so sw1a1aa works too.

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

📦 **BATCH LOOKUP:** up to 100 UK postcodes, one per line. In the JSON tab, pass them as an array of strings:

```
{"operation": "batch", "postcodes": ["SW1A 1AA", "EC1A 1BB", "M1 1AE"]}
```

Each postcode gets one row. Duplicates are removed before anything is charged. A postcode that is mistyped or no longer in use gets a row saying so, and costs nothing.

🎯 **TIP:** more than 100? Run the batch again with the next 100.

## `latitude` (type: `number`):

📍 **REVERSE GEOCODE:** latitude of the point, in decimal degrees (WGS84).

**Example:** 51.501009 for Buckingham Palace

## `longitude` (type: `number`):

📍 **REVERSE GEOCODE:** longitude of the point, in decimal degrees (WGS84).

**Example:** -0.141588 for Buckingham Palace

## `limit` (type: `integer`):

🔢 **POSTCODE SEARCH:** how many matching postcodes to return, 1 to 100. Default 10. You pay only for postcodes actually returned.

## `wideSearch` (type: `boolean`):

🌐 **REVERSE GEOCODE:** by default the nearest postcode is looked for within 2 km of your point. Turn this on to look up to 20 km away, which helps for points in open country, on the coast or in the Highlands.

Ignored by the other operations.

## Actor input object example

```json
{
  "operation": "lookup",
  "postcode": "SW1A 1AA",
  "limit": 10,
  "wideSearch": false
}
```

# Actor output Schema

## `postcodeResults` (type: `string`):

One row per resolved postcode: the postcode, latitude/longitude, eastings/northings, country, region, local authority, ward, county, parliamentary constituency, LSOA, MSOA, NUTS area, NHS area and deprivation rank. Reverse geocode rows add the distance in metres. Postcodes that did not resolve get a row with the reason.

## `processingReport` (type: `string`):

HTML summary of the run: resolved and unresolved rows, what each fix is, the charges for this run and a ready-made retry input.

# 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 = {
    "postcode": "SW1A 1AA"
};

// Run the Actor and wait for it to finish
const run = await client.actor("sian.agency/uk-postcode-address-lookup").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 = { "postcode": "SW1A 1AA" }

# Run the Actor and wait for it to finish
run = client.actor("sian.agency/uk-postcode-address-lookup").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 '{
  "postcode": "SW1A 1AA"
}' |
apify call sian.agency/uk-postcode-address-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,sian.agency/uk-postcode-address-lookup"
        }
    }
}
```

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/l8C1DSlkXaIvA6P7j/builds/in4dse9bUGNHFoI4P/openapi.json