# Postcodes.io API

> Postcodes.io returns UK postcode locations and nearby postcode data, available as a workflow and API.

Postcodes.io returns location, administrative, and in-use details for a UK postcode; enter the postcode. List nearby postcodes returns nearby postcode locations and distances; enter a UK postcode or place name, with optional distance and result settings.

- Page: https://fous.com/tools/postcodes-io
- Handle: `@postcodes-io`
- Category: [Maps](https://fous.com/tools/category/maps)
- Source website: https://postcodes.io
- Last verified: Sep 29, 2026

## Methods

### Get postcode

Operation `get_postcode`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get the location and administrative details of a UK postcode, including whether it is still in use. Retired postcodes have limited records: administrative details are unavailable and returned as null.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `postcode` | string | yes | `"e1w1uu"` | UK postcode, with or without a space and in any letter case, for example SW1A 1AA. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "postcode"
  ],
  "properties": {
    "postcode": {
      "type": "string",
      "minLength": 1,
      "description": "UK postcode, with or without a space and in any letter case, for example SW1A 1AA.",
      "examples": [
        "e1w1uu",
        "SW1A 1AA",
        "EH1 1YZ"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "postcode": "e1w1uu"
    },
    {
      "postcode": "SW1A 1AA"
    },
    {
      "postcode": "EH1 1YZ"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `ward` | string or null | `"St James's"` | Administrative ward. |
| `county` | string or null |  | Administrative county, if applicable. |
| `in_use` | boolean | `false` | Whether the postcode is currently active. |
| `parish` | string or null | `"Westminster, unparished area"` | Civil parish or equivalent, if recorded. |
| `region` | string or null | `"London"` | Region, if available. |
| `country` | string or null | `"England"` | UK country. |
| `eastings` | integer or null | `533779` | British National Grid easting when provided. |
| `latitude` | number or null | `51.508009` | Latitude in decimal degrees. |
| `postcode` | string | `"E1W 1UU"` | Postcode with standard spacing and uppercase letters. |
| `longitude` | number or null | `-0.073706` | Longitude in decimal degrees. |
| `northings` | integer or null | `180545` | British National Grid northing when provided. |
| `page_link` | string | `"https://postcodes.io/terminated_postcodes/E1W1UU"` | Link to the postcode record on Postcodes.io. |
| `area_codes` | object |  | Official area identifiers supplied for the postcode; null where unavailable. |
| `area_codes.ward` | string or null | `"E05013806"` |  |
| `area_codes.county` | string or null |  |  |
| `area_codes.parish` | string or null | `"E43000236"` |  |
| `area_codes.local_council` | string or null | `"E09000033"` |  |
| `area_codes.integrated_care_board` | string or null | `"E54000071"` |  |
| `area_codes.parliamentary_constituency` | string or null | `"E14001172"` |  |
| `year_retired` | integer or null | `2015` | Year the postcode was retired, if known. |
| `local_council` | string or null | `"Westminster"` | Local authority or council area. |
| `parliamentary_constituency` | string or null | `"Cities of London and Westminster"` | UK parliamentary constituency. |
| `health_board_or_integrated_care_board` | string or null | `"NHS West and North London Integrated Care Board"` | Integrated care board in England or the available health authority or board elsewhere. |

**Example input**

```json
{
  "postcode": "e1w1uu"
}
```

**Example output**

```json
{
  "ward": null,
  "county": null,
  "in_use": false,
  "parish": null,
  "region": null,
  "country": null,
  "eastings": 533779,
  "latitude": 51.508009,
  "postcode": "E1W 1UU",
  "longitude": -0.073706,
  "northings": 180545,
  "page_link": "https://postcodes.io/terminated_postcodes/E1W1UU",
  "area_codes": {
    "ward": null,
    "county": null,
    "parish": null,
    "local_council": null,
    "integrated_care_board": null,
    "parliamentary_constituency": null
  },
  "year_retired": 2015,
  "local_council": null,
  "parliamentary_constituency": null,
  "health_board_or_integrated_care_board": null
}
```

### List nearby postcodes

Operation `list_nearby_postcodes`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

List UK postcodes nearest to a postcode or named place, with distance, ward, council and coordinates. For places with the same name, a city or town is preferred.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `near` | string | yes | `"SW1A 1AA"` | A UK postcode or place name, for example SW1A 1AA or Oxford. |
| `max_results` | integer | no | `4` | Maximum number of nearest postcodes, for example 10. |
| `radius_metres` | integer | no | `1000` | Maximum distance in metres from the postcode or place, for example 1000. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "near"
  ],
  "properties": {
    "near": {
      "type": "string",
      "minLength": 1,
      "description": "A UK postcode or place name, for example SW1A 1AA or Oxford.",
      "examples": [
        "SW1A 1AA",
        "Oxford",
        "EH1 1YZ"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 10,
      "maximum": 100,
      "minimum": 1,
      "description": "Maximum number of nearest postcodes, for example 10.",
      "x-fous-developer": true,
      "examples": [
        4,
        10,
        100
      ]
    },
    "radius_metres": {
      "type": "integer",
      "default": 1000,
      "maximum": 2000,
      "minimum": 1,
      "description": "Maximum distance in metres from the postcode or place, for example 1000.",
      "x-fous-developer": true,
      "examples": [
        1000,
        1,
        2000
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "near": "SW1A 1AA"
    },
    {
      "near": "Oxford",
      "max_results": 4,
      "radius_metres": 1000
    },
    {
      "near": "Oxford",
      "max_results": 10,
      "radius_metres": 1
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `postcodes` | array |  | Postcodes ordered nearest first. |
| `postcodes[].ward` | string or null | `"St James's"` |  |
| `postcodes[].latitude` | number or null | `51.50101` |  |
| `postcodes[].page_url` | string | `"https://postcodes.io/postcodes/SW1A%201AA"` |  |
| `postcodes[].postcode` | string | `"SW1A 1AA"` |  |
| `postcodes[].longitude` | number or null | `-0.141563` |  |
| `postcodes[].local_council` | string or null | `"Westminster"` |  |
| `postcodes[].distance_metres` | number | `0` |  |

**Example input**

```json
{
  "near": "SW1A 1AA"
}
```

**Example output**

```json
{
  "postcodes": [
    {
      "ward": "St James's",
      "latitude": 51.50101,
      "page_url": "https://postcodes.io/postcodes/SW1A%201AA",
      "postcode": "SW1A 1AA",
      "longitude": -0.141563,
      "local_council": "Westminster",
      "distance_metres": 0
    },
    {
      "ward": "St James's",
      "latitude": 51.499933,
      "page_url": "https://postcodes.io/postcodes/SW1E%206LA",
      "postcode": "SW1E 6LA",
      "longitude": -0.141117,
      "local_council": "Westminster",
      "distance_metres": 123.67233656624896
    },
    {
      "ward": "St James's",
      "latitude": 51.499738,
      "page_url": "https://postcodes.io/postcodes/SW1E%206AY",
      "postcode": "SW1E 6AY",
      "longitude": -0.140736,
      "local_council": "Westminster",
      "distance_metres": 152.5853742672548
    }
  ]
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@postcodes-io",
  "visibility": "public",
  "operation": "get_postcode",
  "version": 1,
  "input": {
    "postcode": "e1w1uu"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@postcodes-io\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_postcode\",\n  \"version\": 1,\n  \"input\": {\n    \"postcode\": \"e1w1uu\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@postcodes-io",
  "visibility": "public",
  "operation": "get_postcode",
  "version": 1,
  "input": {
    "postcode": "e1w1uu"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/postcodes-io`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `get_postcode`: Get postcode. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `list_nearby_postcodes`: List nearby postcodes. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-postcodes-io https://api.fous.com/mcp/tools/postcodes-io --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Find a postcode’s coordinates and administrative areas
- Check whether a postcode is still in use
- Find postcodes near a place or postcode
- Compare distances between nearby postcodes

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this Postcodes.io tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a Postcodes.io account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from postcodes.io when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 29, 2026.

### Where is a UK postcode located?

Get postcode returns latitude, longitude, and other location details for a supplied UK postcode.

### Is a postcode currently in use?

Get postcode returns whether the supplied postcode is currently in use.

### Which postcodes are nearest to a place?

List nearby postcodes returns postcodes ordered nearest first, with distance and location details.

## Related

- [All Maps tools](https://fous.com/tools/category/maps)