Docs
Open Lodol
DocumentationIntegrationsAPI

Postcodes.io

App · Travel & Places · 18 actions

Look up UK postcodes and geocode from a workflow, with no account and no API key. Get everything the Office for National Statistics holds for a postcode - coordinates, country, region, local authority district, ward, parish, parliamentary constituency, NHS and statistical areas, and the GSS code for each. Validate a postcode against the real directory rather than a regular expression, and find out when a retired one was withdrawn. Turn coordinates into postcodes and postcodes into coordinates, search or autocomplete a partial postcode, and list what is nearby. Look up hundreds of postcodes or coordinate pairs in one step. Measure the distance between two postcodes. Read an outward code as a whole postal area, search Ordnance Survey's gazetteer of British places, and get the Scottish-only geographies - council area, Data Zone, SIMD - that the UK-wide directory does not carry. Every action reads: nothing here changes anything.

Actions

ActionWhat it does
Autocomplete a postcodeComplete a partial postcode into a list of real ones.
Find nearest outward codesList the outward codes around another one, nearest first, each with how far away it is.
Find nearest postcodesList the postcodes around another postcode, nearest first, each with how far away it is in metres, kilometres and miles.
Get a random placeGet a random British place from Ordnance Survey's Open Names, with its full record and its code.
Get a random postcodeGet a random live UK postcode with its full record, optionally from one outward code.
Look up a placeLook up one British place by its Ordnance Survey code, the 'code' field of a search result such as 'osgb4000000074502842'.
Look up a postcodeLook up everything Postcodes.io holds for one UK postcode: its coordinates, its country, region, local authority district, ward, parish and parliamentary constituency, its NHS and statistical areas, and the GSS code for each.
Look up a Scottish postcodeLook up the Scottish-only geographies for a postcode in Scotland, from the Scottish Postcode Directory: council area, Scottish Parliamentary constituency and region, health board, Data Zone and Intermediate Zone, locality and settlement, the Scottish Index of Multiple Deprivation rank, the urban-rural classification, and census household and population counts.
Look up a terminated postcodeLook up a UK postcode that no longer exists and find out when it was withdrawn, together with its last known coordinates.
Look up an outward codeLook up one outward code, the part of a postcode before the space, such as 'SW1A' in 'SW1A 2AA'.
Look up postcodes in bulkLook up many UK postcodes in one step, which is what to use instead of a loop: a column from a spreadsheet, a list of customer addresses, a delivery run.
Measure the distance between two postcodesMeasure how far apart two UK postcodes are, in metres, kilometres and miles, and say whether they fall in the same local authority district, constituency and country.
Reverse geocode coordinatesTurn a longitude and latitude into the UK postcodes around it, nearest first, each with its distance and its full record.
Reverse geocode coordinates in bulkTurn many coordinate pairs into UK postcodes in one step: a day of GPS readings, a set of pins, a list of site locations.
Reverse geocode to outward codesTurn a longitude and latitude into the outward codes around it, nearest first.
Search placesFind British places by name, from Ordnance Survey's Open Names: towns, villages, suburbs, hamlets and other gazetteer entries, each with its county, region, country, outward code and coordinates.
Search postcodesFind live UK postcodes that start with a string, each with its full record.
Validate a postcodeCheck whether a string is a live UK postcode.

Autocomplete a postcode

Complete a partial postcode into a list of real ones. The same search as Search postcodes, but it returns the postcode strings alone rather than a full record for each, which is what an address form or a chat reply wants and a fraction of the data. Terminated postcodes are never suggested. No API key required.

Inputs

Partial postcodepostcodetextRequired
As much of the postcode as is known. Spacing and capitalisation do not matter.
How many resultslimitnumber
How many postcodes to return, from 1 to 100. Leave empty for 10.From 1 to 100. Default: 10.

Outputs

countnumber
foundtrue/false
limitnumber
postcodeslist
querytext
Example output
{
  "count": 5,
  "found": true,
  "limit": 10,
  "postcodes": [
    "SW1A 2AA",
    "SW1A 2AB",
    "SW1A 2AE",
    "SW1A 2AF",
    "SW1A 2AG"
  ],
  "query": "SW1A 2"
}

Find nearest outward codes

List the outward codes around another one, nearest first, each with how far away it is. Use it to widen a delivery or service area a postal district at a time, or to name the neighbouring areas of a site. The default radius is 5km and it reaches 25km, which is wider than the postcode search because outward codes are much further apart. No API key required.

Inputs

Outward codeoutcodetextRequired
The part of a postcode before the space, such as 'SW1A' in 'SW1A 2AA'. Two to four characters.
How many resultslimitnumber
How many outward codes to return, from 1 to 100, nearest first. Leave empty for 10.From 1 to 100. Default: 10.
Search radius (metres)radiusnumber
How far out to look, in metres, from 1 to 25,000. Leave empty for 5,000m. Outward codes are much further apart than postcodes, which is why this reaches further than the postcode search does.From 1 to 25000. Default: 5000.

Outputs

countnumber
foundtrue/false
limitnumber
nearestobject
outcodetext
outcodeslist
radius_metresnumber
resultslist
Example output
{
  "count": 2,
  "found": true,
  "limit": 10,
  "nearest": {
    "admin_county": [
      "(pseudo) England (UA/MD/LB)"
    ],
    "admin_district": [
      "Camden",
      "Westminster"
    ],
    "admin_ward": [
      "Regent's Park",
      "Camden Town"
    ],
    "constituency_count": 1,
    "country": [
      "England"
    ],
    "distance": 0.0,
    "distance_km": 0.0,
    "distance_metres": 0.0,
    "distance_miles": 0.0,
    "district_count": 2,
    "eastings": 528628,
    "has_coordinates": true,
    "latitude": 51.535003,
    "longitude": -0.148315,
    "map_url": "https://www.openstreetmap.org/?mlat=51.535003&mlon=-0.148315#map=16/51.535003/-0.148315",
    "northings": 183440,
    "not_applicable": [
      "admin_county"
    ],
    "outcode": "NW1",
    "parish": [
      "Camden, unparished area"
    ],
    "parliamentary_constituency": [
      "Holborn and St Pancras"
    ],
    "summary": "NW1 - Camden, Westminster",
    "ward_count": 2
  },
  "outcode": "NW1",
  "outcodes": [
    "NW1",
    "W1T"
  ],
  "radius_metres": 5000,
  "results": [
    {
      "admin_county": [
        "(pseudo) England (UA/MD/LB)"
      ],
      "admin_district": [
        "Camden",
        "Westminster"
      ],
      "admin_ward": [
        "Regent's Park",
        "Camden Town"
      ],
      "constituency_count": 1,
      "country": [
        "England"
      ],
      "distance": 0.0,
      "distance_km": 0.0,
      "distance_metres": 0.0,
      "distance_miles": 0.0,
      "district_count": 2,
      "eastings": 528628,
      "has_coordinates": true,
      "latitude": 51.535003,
      "longitude": -0.148315,
      "map_url": "https://www.openstreetmap.org/?mlat=51.535003&mlon=-0.148315#map=16/51.535003/-0.148315",
      "northings": 183440,
      "not_applicable": [
        "admin_county"
      ],
      "outcode": "NW1",
      "parish": [
        "Camden, unparished area"
      ],
      "parliamentary_constituency": [
        "Holborn and St Pancras"
      ],
      "summary": "NW1 - Camden, Westminster",
      "ward_count": 2
    },
    {
      "admin_county": [
        "(pseudo) England (UA/MD/LB)"
      ],
      "admin_district": [
        "Camden",
        "Westminster"
      ],
      "admin_ward": [
        "Bloomsbury",
        "West End"
      ],
      "constituency_count": 1,
      "country": [
        "England"
      ],
      "distance": 1723.4,
      "distance_km": 1.723,
      "distance_metres": 1723.4,
      "distance_miles": 1.071,
      "district_count": 2,
      "eastings": 529415,
      "has_coordinates": true,
      "latitude": 51.520865,
      "longitude": -0.137056,
      "map_url": "https://www.openstreetmap.org/?mlat=51.520865&mlon=-0.137056#map=16/51.520865/-0.137056",
      "northings": 181872,
      "not_applicable": [
        "admin_county"
      ],
      "outcode": "W1T",
      "parish": [
        "Westminster, unparished area"
      ],
      "parliamentary_constituency": [
        "Holborn and St Pancras"
      ],
      "summary": "W1T - Camden, Westminster",
      "ward_count": 2
    }
  ]
}

Find nearest postcodes

List the postcodes around another postcode, nearest first, each with how far away it is in metres, kilometres and miles. The postcode itself comes back first at zero. Use it to find neighbouring delivery areas, to widen a catchment, or to check what else is on a street. The default radius is 100 metres, which is a street rather than a neighbourhood, so raise it for a rural address. No API key required.

Inputs

PostcodepostcodetextRequired
A UK postcode. Spacing and capitalisation do not matter: 'sw1a2aa' and 'SW1A 2AA' reach the same record.
How many resultslimitnumber
How many postcodes to return, from 1 to 100, nearest first. Leave empty for 10.From 1 to 100. Default: 10.
Search radius (metres)radiusnumber
How far out to look, in metres, from 1 to 2,000. Leave empty for 100m, which is a street rather than a neighbourhood: raise it for a rural address, where the nearest postcode can be a kilometre away.From 1 to 2000. Default: 100.

Outputs

countnumber
foundtrue/false
limitnumber
nearestobject
postcodetext
postcodeslist
radius_metresnumber
resultslist
widesearchtrue/false
Example output
{
  "count": 1,
  "found": true,
  "limit": 10,
  "nearest": {
    "admin_county": "(pseudo) England (UA/MD/LB)",
    "admin_district": "Westminster",
    "admin_ward": "St James's",
    "bua": "City of Westminster",
    "cancer_alliance": "West London",
    "ccg": "NHS North West London",
    "ced": null,
    "codes": {
      "admin_county": "E99999999",
      "admin_district": "E09000033",
      "admin_ward": "E05013806",
      "bua": "E63012036",
      "cancer_alliance": "E56000021",
      "ccg": "E38000256",
      "ced": "E99999999",
      "icb": "E54000027",
      "lau2": "E09000033",
      "lep1": "E37000051",
      "lep2": null,
      "lsoa": "E01004736",
      "lsoa11": "E01004736",
      "lsoa21": "E01004736",
      "msoa": "E02000977",
      "msoa11": "E02000977",
      "msoa21": "E02000977",
      "national_park": "E65000001",
      "nhs_region": "E40000003",
      "nuts": "TLI35",
      "oa21": "E00023938",
      "parish": "E43000236",
      "parliamentary_constituency": "E14001172",
      "parliamentary_constituency_2024": "E14001172",
      "pfa": "E23000001",
      "ruc11": "A1",
      "ruc21": "UN1",
      "ttwa": "E30000234"
    },
    "country": "England",
    "date_of_introduction": "198001",
    "date_of_termination": null,
    "eastings": 530047,
    "european_electoral_region": "London",
    "has_coordinates": true,
    "icb": "NHS North West London Integrated Care Board",
    "incode": "2AA",
    "index_of_multiple_deprivation": 24862,
    "introduced_on": "1980-01",
    "latitude": 51.50354,
    "lep1": "London",
    "lep2": null,
    "longitude": -0.127695,
    "lsoa": "Westminster 018C",
    "lsoa11": "Westminster 018C",
    "lsoa21": "Westminster 018C",
    "map_url": "https://www.openstreetmap.org/?mlat=51.50354&mlon=-0.127695#map=16/51.50354/-0.127695",
    "msoa": "Westminster 018",
    "msoa11": "Westminster 018",
    "msoa21": "Westminster 018",
    "national_park": "England (non-National Park)",
    "nhs_ha": "London",
    "nhs_region": "London",
    "northings": 179951,
    "not_applicable": [
      "admin_county",
      "ced"
    ],
    "nuts": "Westminster",
    "oa21": "E00023938",
    "outcode": "SW1A",
    "parish": "Westminster, unparished area",
    "parliamentary_constituency": "Cities of London and Westminster",
    "parliamentary_constituency_2024": "Cities of London and Westminster",
    "pfa": "Metropolitan Police",
    "postcode": "SW1A 2AA",
    "primary_care_trust": "Westminster",
    "quality": 1,
    "quality_description": "Within the building of the matched address closest to the postcode mean",
    "region": "London",
    "ruc11": "(England/Wales) Urban major conurbation",
    "ruc21": "Urban: Nearer to a major town or city",
    "senedd_constituency": null,
    "senedd_constituency_no": null,
    "summary": "SW1A 2AA - St James's, Westminster, London",
    "ttwa": "London"
  },
  "postcode": "SW1A 2AA",
  "postcodes": [
    "SW1A 2AA"
  ],
  "radius_metres": 100,
  "results": [
    {
      "admin_county": "(pseudo) England (UA/MD/LB)",
      "admin_district": "Westminster",
      "admin_ward": "St James's",
      "bua": "City of Westminster",
      "cancer_alliance": "West London",
      "ccg": "NHS North West London",
      "ced": null,
      "codes": {
        "admin_county": "E99999999",
        "admin_district": "E09000033",
        "admin_ward": "E05013806",
        "bua": "E63012036",
        "cancer_alliance": "E56000021",
        "ccg": "E38000256",
        "ced": "E99999999",
        "icb": "E54000027",
        "lau2": "E09000033",
        "lep1": "E37000051",
        "lep2": null,
        "lsoa": "E01004736",
        "lsoa11": "E01004736",
        "lsoa21": "E01004736",
        "msoa": "E02000977",
        "msoa11": "E02000977",
        "msoa21": "E02000977",
        "national_park": "E65000001",
        "nhs_region": "E40000003",
        "nuts": "TLI35",
        "oa21": "E00023938",
        "parish": "E43000236",
        "parliamentary_constituency": "E14001172",
        "parliamentary_constituency_2024": "E14001172",
        "pfa": "E23000001",
        "ruc11": "A1",
        "ruc21": "UN1",
        "ttwa": "E30000234"
      },
      "country": "England",
      "date_of_introduction": "198001",
      "date_of_termination": null,
      "eastings": 530047,
      "european_electoral_region": "London",
      "has_coordinates": true,
      "icb": "NHS North West London Integrated Care Board",
      "incode": "2AA",
      "index_of_multiple_deprivation": 24862,
      "introduced_on": "1980-01",
      "latitude": 51.50354,
      "lep1": "London",
      "lep2": null,
      "longitude": -0.127695,
      "lsoa": "Westminster 018C",
      "lsoa11": "Westminster 018C",
      "lsoa21": "Westminster 018C",
      "map_url": "https://www.openstreetmap.org/?mlat=51.50354&mlon=-0.127695#map=16/51.50354/-0.127695",
      "msoa": "Westminster 018",
      "msoa11": "Westminster 018",
      "msoa21": "Westminster 018",
      "national_park": "England (non-National Park)",
      "nhs_ha": "London",
      "nhs_region": "London",
      "northings": 179951,
      "not_applicable": [
        "admin_county",
        "ced"
      ],
      "nuts": "Westminster",
      "oa21": "E00023938",
      "outcode": "SW1A",
      "parish": "Westminster, unparished area",
      "parliamentary_constituency": "Cities of London and Westminster",
      "parliamentary_constituency_2024": "Cities of London and Westminster",
      "pfa": "Metropolitan Police",
      "postcode": "SW1A 2AA",
      "primary_care_trust": "Westminster",
      "quality": 1,
      "quality_description": "Within the building of the matched address closest to the postcode mean",
      "region": "London",
      "ruc11": "(England/Wales) Urban major conurbation",
      "ruc21": "Urban: Nearer to a major town or city",
      "senedd_constituency": null,
      "senedd_constituency_no": null,
      "summary": "SW1A 2AA - St James's, Westminster, London",
      "ttwa": "London"
    }
  ],
  "widesearch": false
}

Get a random place

Get a random British place from Ordnance Survey's Open Names, with its full record and its code. Useful for seeding test data with a location that really exists, for sampling, or for a 'somewhere in Britain' post. No API key required.

Inputs

None.

Outputs

codetext
foundtrue/false
messagetext
nametext
resultobject
Example output
{
  "code": "osgb4000000074552637",
  "found": true,
  "message": "Llanfairpwllgwyngyll - Isle of Anglesey, Wales (Village)",
  "name": "Llanfairpwllgwyngyll",
  "result": {
    "alternate_name": null,
    "alternate_name_language": null,
    "code": "osgb4000000074552637",
    "country": "Wales",
    "county_unitary": "Isle of Anglesey",
    "county_unitary_type": "UnitaryAuthority",
    "district_borough": null,
    "district_borough_type": null,
    "eastings": 253187,
    "has_coordinates": true,
    "latitude": 53.22224,
    "local_type": "Village",
    "longitude": -4.20355,
    "map_url": "https://www.openstreetmap.org/?mlat=53.22224&mlon=-4.20355#map=16/53.22224/-4.20355",
    "max_eastings": 254967,
    "max_northings": 372813,
    "min_eastings": 251534,
    "min_northings": 370422,
    "name": "Llanfairpwllgwyngyll",
    "name_1": "Llanfairpwllgwyngyll",
    "name_1_lang": "cym",
    "name_2": null,
    "name_2_lang": null,
    "northings": 371604,
    "outcode": "LL61",
    "region": "Wales",
    "summary": "Llanfairpwllgwyngyll - Isle of Anglesey, Wales (Village)"
  }
}

Get a random postcode

Get a random live UK postcode with its full record, optionally from one outward code. Useful for seeding test data with an address that really exists, for sampling, or for a daily 'somewhere in the UK' post. An outward code the service does not hold is reported as such rather than coming back as an empty result. No API key required.

Inputs

Outward codeoutcodetext
Restrict the pick to one outward code, such as 'SW1A'. Leave empty to draw from the whole of the UK.

Outputs

foundtrue/false
messagetext
outcodetext
postcodetext
resultobject
Example output
{
  "found": true,
  "message": "SW1A 2AA - St James's, Westminster, London",
  "outcode": "SW1A",
  "postcode": "SW1A 2AA",
  "result": {
    "admin_county": "(pseudo) England (UA/MD/LB)",
    "admin_district": "Westminster",
    "admin_ward": "St James's",
    "bua": "City of Westminster",
    "cancer_alliance": "West London",
    "ccg": "NHS North West London",
    "ced": null,
    "codes": {
      "admin_county": "E99999999",
      "admin_district": "E09000033",
      "admin_ward": "E05013806",
      "bua": "E63012036",
      "cancer_alliance": "E56000021",
      "ccg": "E38000256",
      "ced": "E99999999",
      "icb": "E54000027",
      "lau2": "E09000033",
      "lep1": "E37000051",
      "lep2": null,
      "lsoa": "E01004736",
      "lsoa11": "E01004736",
      "lsoa21": "E01004736",
      "msoa": "E02000977",
      "msoa11": "E02000977",
      "msoa21": "E02000977",
      "national_park": "E65000001",
      "nhs_region": "E40000003",
      "nuts": "TLI35",
      "oa21": "E00023938",
      "parish": "E43000236",
      "parliamentary_constituency": "E14001172",
      "parliamentary_constituency_2024": "E14001172",
      "pfa": "E23000001",
      "ruc11": "A1",
      "ruc21": "UN1",
      "ttwa": "E30000234"
    },
    "country": "England",
    "date_of_introduction": "198001",
    "date_of_termination": null,
    "eastings": 530047,
    "european_electoral_region": "London",
    "has_coordinates": true,
    "icb": "NHS North West London Integrated Care Board",
    "incode": "2AA",
    "index_of_multiple_deprivation": 24862,
    "introduced_on": "1980-01",
    "latitude": 51.50354,
    "lep1": "London",
    "lep2": null,
    "longitude": -0.127695,
    "lsoa": "Westminster 018C",
    "lsoa11": "Westminster 018C",
    "lsoa21": "Westminster 018C",
    "map_url": "https://www.openstreetmap.org/?mlat=51.50354&mlon=-0.127695#map=16/51.50354/-0.127695",
    "msoa": "Westminster 018",
    "msoa11": "Westminster 018",
    "msoa21": "Westminster 018",
    "national_park": "England (non-National Park)",
    "nhs_ha": "London",
    "nhs_region": "London",
    "northings": 179951,
    "not_applicable": [
      "admin_county",
      "ced"
    ],
    "nuts": "Westminster",
    "oa21": "E00023938",
    "outcode": "SW1A",
    "parish": "Westminster, unparished area",
    "parliamentary_constituency": "Cities of London and Westminster",
    "parliamentary_constituency_2024": "Cities of London and Westminster",
    "pfa": "Metropolitan Police",
    "postcode": "SW1A 2AA",
    "primary_care_trust": "Westminster",
    "quality": 1,
    "quality_description": "Within the building of the matched address closest to the postcode mean",
    "region": "London",
    "ruc11": "(England/Wales) Urban major conurbation",
    "ruc21": "Urban: Nearer to a major town or city",
    "senedd_constituency": null,
    "senedd_constituency_no": null,
    "summary": "SW1A 2AA - St James's, Westminster, London",
    "ttwa": "London"
  }
}

Look up a place

Look up one British place by its Ordnance Survey code, the 'code' field of a search result such as 'osgb4000000074502842'. Returns the same full record as a search, including the Welsh or Gaelic name where there is one and the bounding box of the place. Run Search places or Get a random place first to get a code. No API key required.

Inputs

Place codecodetextRequired
The Ordnance Survey code of the place, such as 'osgb4000000074502842'. Codes are per place and do not follow a pattern you can guess, so take one from a Search places step in the same workflow. Case does not matter.

Outputs

codetext
foundtrue/false
messagetext
nametext
resultobject
Example output
{
  "code": "osgb4000000074502842",
  "found": true,
  "message": "Edinburgh - City of Edinburgh, Scotland (City)",
  "name": "Edinburgh",
  "result": {
    "alternate_name": "Dun Eideann",
    "alternate_name_language": "gla",
    "code": "osgb4000000074502842",
    "country": "Scotland",
    "county_unitary": "City of Edinburgh",
    "county_unitary_type": "UnitaryAuthority",
    "district_borough": null,
    "district_borough_type": null,
    "eastings": 326036,
    "has_coordinates": true,
    "latitude": 55.953251,
    "local_type": "City",
    "longitude": -3.188267,
    "map_url": "https://www.openstreetmap.org/?mlat=55.953251&mlon=-3.188267#map=16/55.953251/-3.188267",
    "max_eastings": 335533,
    "max_northings": 680564,
    "min_eastings": 316471,
    "min_northings": 665453,
    "name": "Edinburgh",
    "name_1": "Edinburgh",
    "name_1_lang": null,
    "name_2": "Dun Eideann",
    "name_2_lang": "gla",
    "northings": 673985,
    "outcode": "EH1",
    "region": "Scotland",
    "summary": "Edinburgh - City of Edinburgh, Scotland (City)"
  }
}

Look up a postcode

Look up everything Postcodes.io holds for one UK postcode: its coordinates, its country, region, local authority district, ward, parish and parliamentary constituency, its NHS and statistical areas, and the GSS code for each. Spacing and capitalisation do not matter. A postcode that no longer exists is not a failure: the step reports when it was terminated, so a workflow can tell a retired postcode from a typo. Comes with a plain-English reading of how accurate the coordinates are and a map link. No API key required.

Inputs

PostcodepostcodetextRequired
A UK postcode. Spacing and capitalisation do not matter: 'sw1a2aa' and 'SW1A 2AA' reach the same record.

Outputs

foundtrue/false
messagetext
postcodetext
resultobject
terminatedtrue/false
terminated_recordobject
Example output
{
  "found": true,
  "message": "SW1A 2AA - St James's, Westminster, London",
  "postcode": "SW1A 2AA",
  "result": {
    "admin_county": "(pseudo) England (UA/MD/LB)",
    "admin_district": "Westminster",
    "admin_ward": "St James's",
    "bua": "City of Westminster",
    "cancer_alliance": "West London",
    "ccg": "NHS North West London",
    "ced": null,
    "codes": {
      "admin_county": "E99999999",
      "admin_district": "E09000033",
      "admin_ward": "E05013806",
      "bua": "E63012036",
      "cancer_alliance": "E56000021",
      "ccg": "E38000256",
      "ced": "E99999999",
      "icb": "E54000027",
      "lau2": "E09000033",
      "lep1": "E37000051",
      "lep2": null,
      "lsoa": "E01004736",
      "lsoa11": "E01004736",
      "lsoa21": "E01004736",
      "msoa": "E02000977",
      "msoa11": "E02000977",
      "msoa21": "E02000977",
      "national_park": "E65000001",
      "nhs_region": "E40000003",
      "nuts": "TLI35",
      "oa21": "E00023938",
      "parish": "E43000236",
      "parliamentary_constituency": "E14001172",
      "parliamentary_constituency_2024": "E14001172",
      "pfa": "E23000001",
      "ruc11": "A1",
      "ruc21": "UN1",
      "ttwa": "E30000234"
    },
    "country": "England",
    "date_of_introduction": "198001",
    "date_of_termination": null,
    "eastings": 530047,
    "european_electoral_region": "London",
    "has_coordinates": true,
    "icb": "NHS North West London Integrated Care Board",
    "incode": "2AA",
    "index_of_multiple_deprivation": 24862,
    "introduced_on": "1980-01",
    "latitude": 51.50354,
    "lep1": "London",
    "lep2": null,
    "longitude": -0.127695,
    "lsoa": "Westminster 018C",
    "lsoa11": "Westminster 018C",
    "lsoa21": "Westminster 018C",
    "map_url": "https://www.openstreetmap.org/?mlat=51.50354&mlon=-0.127695#map=16/51.50354/-0.127695",
    "msoa": "Westminster 018",
    "msoa11": "Westminster 018",
    "msoa21": "Westminster 018",
    "national_park": "England (non-National Park)",
    "nhs_ha": "London",
    "nhs_region": "London",
    "northings": 179951,
    "not_applicable": [
      "admin_county",
      "ced"
    ],
    "nuts": "Westminster",
    "oa21": "E00023938",
    "outcode": "SW1A",
    "parish": "Westminster, unparished area",
    "parliamentary_constituency": "Cities of London and Westminster",
    "parliamentary_constituency_2024": "Cities of London and Westminster",
    "pfa": "Metropolitan Police",
    "postcode": "SW1A 2AA",
    "primary_care_trust": "Westminster",
    "quality": 1,
    "quality_description": "Within the building of the matched address closest to the postcode mean",
    "region": "London",
    "ruc11": "(England/Wales) Urban major conurbation",
    "ruc21": "Urban: Nearer to a major town or city",
    "senedd_constituency": null,
    "senedd_constituency_no": null,
    "summary": "SW1A 2AA - St James's, Westminster, London",
    "ttwa": "London"
  },
  "terminated": false,
  "terminated_record": null
}

Look up a Scottish postcode

Look up the Scottish-only geographies for a postcode in Scotland, from the Scottish Postcode Directory: council area, Scottish Parliamentary constituency and region, health board, Data Zone and Intermediate Zone, locality and settlement, the Scottish Index of Multiple Deprivation rank, the urban-rural classification, and census household and population counts. None of that is in the UK-wide directory. A postcode outside Scotland is reported as such rather than as an error, so it can be told apart from a typo. No API key required.

Inputs

Scottish postcodepostcodetextRequired
A postcode in Scotland. Spacing and capitalisation do not matter.

Outputs

foundtrue/false
in_scotlandtrue/false
messagetext
postcodetext
resultobject
Example output
{
  "found": true,
  "in_scotland": true,
  "message": "EH1 1YJ - City Centre, City of Edinburgh",
  "postcode": "EH1 1YJ",
  "result": {
    "census_household_count": 74,
    "census_population_count": 106,
    "council_area": "City of Edinburgh",
    "data_zone": "Old Town, Princes Street and Leith Street - 04",
    "date_of_deletion": null,
    "date_of_introduction": "199406",
    "deleted_on": null,
    "eastings": 325947,
    "electoral_ward": "City Centre",
    "has_coordinates": true,
    "health_board_area": "Lothian",
    "incode": "1YJ",
    "intermediate_zone": "Old Town, Princes Street and Leith Street",
    "introduced_on": "1994-06",
    "is_live": true,
    "latitude": 55.951206,
    "locality": "Edinburgh",
    "longitude": -3.189515,
    "map_url": "https://www.openstreetmap.org/?mlat=55.951206&mlon=-3.189515#map=16/55.951206/-3.189515",
    "northings": 673757,
    "not_applicable": [],
    "outcode": "EH1",
    "pc_compact": "EH11YJ",
    "postcode": "EH1 1YJ",
    "postcode_district": "EH1",
    "postcode_sector": "EH1 1",
    "scottish_index_of_multiple_deprivation": 3201,
    "scottish_parliamentary_constituency_2021": "Edinburgh Central",
    "scottish_parliamentary_region_2021": "Lothian",
    "settlement": "Edinburgh",
    "summary": "EH1 1YJ - City Centre, City of Edinburgh",
    "urban_rural_8_fold": "1",
    "user_type": "0"
  }
}

Look up a terminated postcode

Look up a UK postcode that no longer exists and find out when it was withdrawn, together with its last known coordinates. Postcodes are retired all the time as streets are redeveloped, so an old customer record can hold an address that a normal lookup simply cannot find. Only terminated postcodes are here: a postcode still in use is reported as still in use rather than as a failure. No API key required.

Inputs

Terminated postcodepostcodetextRequired
A UK postcode that no longer exists. Spacing and capitalisation do not matter. Only withdrawn postcodes are in this table: a postcode still in use is reported as still in use, so use Look up a postcode for one of those. If you do not have a retired postcode to hand, the example below is one.

Outputs

foundtrue/false
messagetext
postcodetext
resultobject
terminated_ontext
Example output
{
  "found": true,
  "message": "BN1 1AU was terminated in August 2011.",
  "postcode": "BN1 1AU",
  "result": {
    "eastings": 531265,
    "has_coordinates": true,
    "latitude": 50.823931,
    "longitude": -0.13772,
    "map_url": "https://www.openstreetmap.org/?mlat=50.823931&mlon=-0.13772#map=16/50.823931/-0.13772",
    "month_terminated": 8,
    "northings": 104362,
    "postcode": "BN1 1AU",
    "terminated_on": "2011-08",
    "terminated_phrase": "August 2011",
    "year_terminated": 2011
  },
  "terminated_on": "2011-08"
}

Look up an outward code

Look up one outward code, the part of a postcode before the space, such as 'SW1A' in 'SW1A 2AA'. An outward code covers hundreds of postcodes, so this returns every local authority district, ward, county, parish and parliamentary constituency it touches, plus its centre point. Use it to describe a postal area from a partial address, or to see how many boundaries an area straddles. No API key required.

Inputs

Outward codeoutcodetextRequired
The part of a postcode before the space, such as 'SW1A' in 'SW1A 2AA'. Two to four characters.

Outputs

foundtrue/false
messagetext
outcodetext
resultobject
Example output
{
  "found": true,
  "message": "SW1A - Westminster",
  "outcode": "SW1A",
  "result": {
    "admin_county": [
      "(pseudo) England (UA/MD/LB)"
    ],
    "admin_district": [
      "Westminster"
    ],
    "admin_ward": [
      "St James's"
    ],
    "constituency_count": 1,
    "country": [
      "England"
    ],
    "district_count": 1,
    "eastings": 529740,
    "has_coordinates": true,
    "latitude": 51.50464,
    "longitude": -0.132066,
    "map_url": "https://www.openstreetmap.org/?mlat=51.50464&mlon=-0.132066#map=16/51.50464/-0.132066",
    "northings": 180066,
    "not_applicable": [
      "admin_county"
    ],
    "outcode": "SW1A",
    "parish": [
      "Westminster, unparished area"
    ],
    "parliamentary_constituency": [
      "Cities of London and Westminster"
    ],
    "summary": "SW1A - Westminster",
    "ward_count": 1
  }
}

Look up postcodes in bulk

Look up many UK postcodes in one step, which is what to use instead of a loop: a column from a spreadsheet, a list of customer addresses, a delivery run. The answers come back in the order they were sent, so they line up with the column they came from, and the ones that could not be matched are listed separately rather than left as gaps to sift out. Postcodes.io takes 100 per request and refuses a longer list outright, so this step splits a longer one into batches automatically, up to 1,000. Trim the fields to keep a large answer small. No API key required.

Inputs

PostcodespostcodeslistRequired
The postcodes to look up. Give a list, or one string with the postcodes separated by commas or new lines. Up to 1,000; duplicates and order are kept so the answers line up with the list that was sent.
Fields to returnfieldslist
Trim every result down to just these fields, which keeps a hundred-postcode answer small. Leave empty to get everything. Postcodes.io only filters on the fields listed here and silently ignores any other name, so anything else is refused rather than quietly returning the lot. Note that a trimmed result skips the extra fields this integration adds, such as the map link and the plain-English position quality, because those are worked out from fields the filter may have removed.One or more of: postcode, longitude, latitude, eastings (Eastings (British National Grid)), northings (Northings (British National Grid)), quality (Positional quality (1 to 9)), country, region, admin_district (Local authority district), admin_county (County), and 14 more.

Outputs

fieldslist
foundtrue/false
matchedlist
matched_countnumber
postcodeslist
request_countnumber
requested_countnumber
resultslist
unmatchedlist
unmatched_countnumber
Example output
{
  "fields": [],
  "found": true,
  "matched": [
    {
      "admin_county": "(pseudo) England (UA/MD/LB)",
      "admin_district": "Westminster",
      "admin_ward": "St James's",
      "bua": "City of Westminster",
      "cancer_alliance": "West London",
      "ccg": "NHS North West London",
      "ced": null,
      "codes": {
        "admin_county": "E99999999",
        "admin_district": "E09000033",
        "admin_ward": "E05013806",
        "bua": "E63012036",
        "cancer_alliance": "E56000021",
        "ccg": "E38000256",
        "ced": "E99999999",
        "icb": "E54000027",
        "lau2": "E09000033",
        "lep1": "E37000051",
        "lep2": null,
        "lsoa": "E01004736",
        "lsoa11": "E01004736",
        "lsoa21": "E01004736",
        "msoa": "E02000977",
        "msoa11": "E02000977",
        "msoa21": "E02000977",
        "national_park": "E65000001",
        "nhs_region": "E40000003",
        "nuts": "TLI35",
        "oa21": "E00023938",
        "parish": "E43000236",
        "parliamentary_constituency": "E14001172",
        "parliamentary_constituency_2024": "E14001172",
        "pfa": "E23000001",
        "ruc11": "A1",
        "ruc21": "UN1",
        "ttwa": "E30000234"
      },
      "country": "England",
      "date_of_introduction": "198001",
      "date_of_termination": null,
      "eastings": 530047,
      "european_electoral_region": "London",
      "has_coordinates": true,
      "icb": "NHS North West London Integrated Care Board",
      "incode": "2AA",
      "index_of_multiple_deprivation": 24862,
      "introduced_on": "1980-01",
      "latitude": 51.50354,
      "lep1": "London",
      "lep2": null,
      "longitude": -0.127695,
      "lsoa": "Westminster 018C",
      "lsoa11": "Westminster 018C",
      "lsoa21": "Westminster 018C",
      "map_url": "https://www.openstreetmap.org/?mlat=51.50354&mlon=-0.127695#map=16/51.50354/-0.127695",
      "msoa": "Westminster 018",
      "msoa11": "Westminster 018",
      "msoa21": "Westminster 018",
      "national_park": "England (non-National Park)",
      "nhs_ha": "London",
      "nhs_region": "London",
      "northings": 179951,
      "not_applicable": [
        "admin_county",
        "ced"
      ],
      "nuts": "Westminster",
      "oa21": "E00023938",
      "outcode": "SW1A",
      "parish": "Westminster, unparished area",
      "parliamentary_constituency": "Cities of London and Westminster",
      "parliamentary_constituency_2024": "Cities of London and Westminster",
      "pfa": "Metropolitan Police",
      "postcode": "SW1A 2AA",
      "primary_care_trust": "Westminster",
      "quality": 1,
      "quality_description": "Within the building of the matched address closest to the postcode mean",
      "region": "London",
      "ruc11": "(England/Wales) Urban major conurbation",
      "ruc21": "Urban: Nearer to a major town or city",
      "senedd_constituency": null,
      "senedd_constituency_no": null,
      "summary": "SW1A 2AA - St James's, Westminster, London",
      "ttwa": "London"
    }
  ],
  "matched_count": 1,
  "postcodes": [
    "SW1A 2AA"
  ],
  "request_count": 1,
  "requested_count": 2,
  "results": [
    {
      "found": true,
      "query": "SW1A 2AA",
      "result": {
        "admin_county": "(pseudo) England (UA/MD/LB)",
        "admin_district": "Westminster",
        "admin_ward": "St James's",
        "bua": "City of Westminster",
        "cancer_alliance": "West London",
        "ccg": "NHS North West London",
        "ced": null,
        "codes": {
          "admin_county": "E99999999",
          "admin_district": "E09000033",
          "admin_ward": "E05013806",
          "bua": "E63012036",
          "cancer_alliance": "E56000021",
          "ccg": "E38000256",
          "ced": "E99999999",
          "icb": "E54000027",
          "lau2": "E09000033",
          "lep1": "E37000051",
          "lep2": null,
          "lsoa": "E01004736",
          "lsoa11": "E01004736",
          "lsoa21": "E01004736",
          "msoa": "E02000977",
          "msoa11": "E02000977",
          "msoa21": "E02000977",
          "national_park": "E65000001",
          "nhs_region": "E40000003",
          "nuts": "TLI35",
          "oa21": "E00023938",
          "parish": "E43000236",
          "parliamentary_constituency": "E14001172",
          "parliamentary_constituency_2024": "E14001172",
          "pfa": "E23000001",
          "ruc11": "A1",
          "ruc21": "UN1",
          "ttwa": "E30000234"
        },
        "country": "England",
        "date_of_introduction": "198001",
        "date_of_termination": null,
        "eastings": 530047,
        "european_electoral_region": "London",
        "has_coordinates": true,
        "icb": "NHS North West London Integrated Care Board",
        "incode": "2AA",
        "index_of_multiple_deprivation": 24862,
        "introduced_on": "1980-01",
        "latitude": 51.50354,
        "lep1": "London",
        "lep2": null,
        "longitude": -0.127695,
        "lsoa": "Westminster 018C",
        "lsoa11": "Westminster 018C",
        "lsoa21": "Westminster 018C",
        "map_url": "https://www.openstreetmap.org/?mlat=51.50354&mlon=-0.127695#map=16/51.50354/-0.127695",
        "msoa": "Westminster 018",
        "msoa11": "Westminster 018",
        "msoa21": "Westminster 018",
        "national_park": "England (non-National Park)",
        "nhs_ha": "London",
        "nhs_region": "London",
        "northings": 179951,
        "not_applicable": [
          "admin_county",
          "ced"
        ],
        "nuts": "Westminster",
        "oa21": "E00023938",
        "outcode": "SW1A",
        "parish": "Westminster, unparished area",
        "parliamentary_constituency": "Cities of London and Westminster",
        "parliamentary_constituency_2024": "Cities of London and Westminster",
        "pfa": "Metropolitan Police",
        "postcode": "SW1A 2AA",
        "primary_care_trust": "Westminster",
        "quality": 1,
        "quality_description": "Within the building of the matched address closest to the postcode mean",
        "region": "London",
        "ruc11": "(England/Wales) Urban major conurbation",
        "ruc21": "Urban: Nearer to a major town or city",
        "senedd_constituency": null,
        "senedd_constituency_no": null,
        "summary": "SW1A 2AA - St James's, Westminster, London",
        "ttwa": "London"
      }
    },
    {
      "found": false,
      "query": "ZZ99 9ZZ",
      "result": null
    }
  ],
  "unmatched": [
    "ZZ99 9ZZ"
  ],
  "unmatched_count": 1
}

Measure the distance between two postcodes

Measure how far apart two UK postcodes are, in metres, kilometres and miles, and say whether they fall in the same local authority district, constituency and country. This is the step for 'is this customer within 20 miles of the depot?' or 'which of our sites is closest?'. Both postcodes are read in a single request. The distance is as the crow flies between the two postcode centroids, not a driving distance and not door to door. No API key required.

Inputs

From postcodeorigintextRequired
The postcode to measure from.
To postcodedestinationtextRequired
The postcode to measure to.

Outputs

destinationtext
destination_resultobject
distance_kmnumber
distance_metresnumber
distance_milesnumber
foundtrue/false
origintext
origin_resultobject
same_constituencytrue/false
same_countrytrue/false
same_districttrue/false
Example output
{
  "destination": "EH1 1YJ",
  "destination_result": {
    "admin_county": null,
    "admin_district": "City of Edinburgh",
    "admin_ward": "City Centre",
    "bua": "Edinburgh",
    "cancer_alliance": null,
    "ccg": "Lothian",
    "ced": null,
    "codes": {
      "admin_county": "S99999999",
      "admin_district": "S12000036",
      "admin_ward": "S13002929",
      "bua": "S45000185",
      "cancer_alliance": "S99999999",
      "ccg": "S08000024",
      "ced": "S99999999",
      "icb": "S99999999",
      "lau2": "S30000026",
      "lep1": "S99999999",
      "lep2": null,
      "lsoa": "S01008682",
      "lsoa11": "S01008682",
      "lsoa21": "S01008682",
      "msoa": "S02001576",
      "msoa11": "S02001576",
      "msoa21": "S02001576",
      "national_park": "S99999999",
      "nhs_region": "S99999999",
      "nuts": "TLM75",
      "oa21": "S00128558",
      "parish": "S99999999",
      "parliamentary_constituency": "S14000091",
      "parliamentary_constituency_2024": "S14000091",
      "pfa": "S23000009",
      "ruc11": "2",
      "ruc21": "2",
      "ttwa": "S22000059"
    },
    "country": "Scotland",
    "date_of_introduction": "199406",
    "date_of_termination": null,
    "eastings": 325947,
    "european_electoral_region": "Scotland",
    "has_coordinates": true,
    "icb": null,
    "incode": "1YJ",
    "index_of_multiple_deprivation": 4691,
    "introduced_on": "1994-06",
    "latitude": 55.951206,
    "lep1": null,
    "lep2": null,
    "longitude": -3.189515,
    "lsoa": "Old Town, Princes Street and Leith Street - 03",
    "lsoa11": "Old Town, Princes Street and Leith Street - 03",
    "lsoa21": "Old Town, Princes Street and Leith Street - 03",
    "map_url": "https://www.openstreetmap.org/?mlat=55.951206&mlon=-3.189515#map=16/55.951206/-3.189515",
    "msoa": "Old Town, Princes Street and Leith Street",
    "msoa11": "Old Town, Princes Street and Leith Street",
    "msoa21": "Old Town, Princes Street and Leith Street",
    "national_park": null,
    "nhs_ha": "Lothian",
    "nhs_region": null,
    "northings": 673757,
    "not_applicable": [
      "admin_county",
      "cancer_alliance",
      "ced",
      "icb",
      "lep1",
      "national_park",
      "nhs_region",
      "parish"
    ],
    "nuts": "City of Edinburgh",
    "oa21": "S00128558",
    "outcode": "EH1",
    "parish": null,
    "parliamentary_constituency": "Edinburgh East and Musselburgh",
    "parliamentary_constituency_2024": "Edinburgh East and Musselburgh",
    "pfa": "Scotland",
    "postcode": "EH1 1YJ",
    "primary_care_trust": "Lothian",
    "quality": 1,
    "quality_description": "Within the building of the matched address closest to the postcode mean",
    "region": null,
    "ruc11": "Large Urban Area",
    "ruc21": "Large Urban Area",
    "senedd_constituency": null,
    "senedd_constituency_no": null,
    "summary": "EH1 1YJ - City Centre, City of Edinburgh, Scotland",
    "ttwa": "Edinburgh"
  },
  "distance_km": 533.873,
  "distance_metres": 533872.8,
  "distance_miles": 331.733,
  "found": true,
  "origin": "SW1A 2AA",
  "origin_result": {
    "admin_county": "(pseudo) England (UA/MD/LB)",
    "admin_district": "Westminster",
    "admin_ward": "St James's",
    "bua": "City of Westminster",
    "cancer_alliance": "West London",
    "ccg": "NHS North West London",
    "ced": null,
    "codes": {
      "admin_county": "E99999999",
      "admin_district": "E09000033",
      "admin_ward": "E05013806",
      "bua": "E63012036",
      "cancer_alliance": "E56000021",
      "ccg": "E38000256",
      "ced": "E99999999",
      "icb": "E54000027",
      "lau2": "E09000033",
      "lep1": "E37000051",
      "lep2": null,
      "lsoa": "E01004736",
      "lsoa11": "E01004736",
      "lsoa21": "E01004736",
      "msoa": "E02000977",
      "msoa11": "E02000977",
      "msoa21": "E02000977",
      "national_park": "E65000001",
      "nhs_region": "E40000003",
      "nuts": "TLI35",
      "oa21": "E00023938",
      "parish": "E43000236",
      "parliamentary_constituency": "E14001172",
      "parliamentary_constituency_2024": "E14001172",
      "pfa": "E23000001",
      "ruc11": "A1",
      "ruc21": "UN1",
      "ttwa": "E30000234"
    },
    "country": "England",
    "date_of_introduction": "198001",
    "date_of_termination": null,
    "eastings": 530047,
    "european_electoral_region": "London",
    "has_coordinates": true,
    "icb": "NHS North West London Integrated Care Board",
    "incode": "2AA",
    "index_of_multiple_deprivation": 24862,
    "introduced_on": "1980-01",
    "latitude": 51.50354,
    "lep1": "London",
    "lep2": null,
    "longitude": -0.127695,
    "lsoa": "Westminster 018C",
    "lsoa11": "Westminster 018C",
    "lsoa21": "Westminster 018C",
    "map_url": "https://www.openstreetmap.org/?mlat=51.50354&mlon=-0.127695#map=16/51.50354/-0.127695",
    "msoa": "Westminster 018",
    "msoa11": "Westminster 018",
    "msoa21": "Westminster 018",
    "national_park": "England (non-National Park)",
    "nhs_ha": "London",
    "nhs_region": "London",
    "northings": 179951,
    "not_applicable": [
      "admin_county",
      "ced"
    ],
    "nuts": "Westminster",
    "oa21": "E00023938",
    "outcode": "SW1A",
    "parish": "Westminster, unparished area",
    "parliamentary_constituency": "Cities of London and Westminster",
    "parliamentary_constituency_2024": "Cities of London and Westminster",
    "pfa": "Metropolitan Police",
    "postcode": "SW1A 2AA",
    "primary_care_trust": "Westminster",
    "quality": 1,
    "quality_description": "Within the building of the matched address closest to the postcode mean",
    "region": "London",
    "ruc11": "(England/Wales) Urban major conurbation",
    "ruc21": "Urban: Nearer to a major town or city",
    "senedd_constituency": null,
    "senedd_constituency_no": null,
    "summary": "SW1A 2AA - St James's, Westminster, London",
    "ttwa": "London"
  },
  "same_constituency": false,
  "same_country": false,
  "same_district": false
}

Reverse geocode coordinates

Turn a longitude and latitude into the UK postcodes around it, nearest first, each with its distance and its full record. This is the step for a GPS reading, a map click or a photo's location. The default radius is 100 metres, which finds nothing in open country: turn on wide search for a rural point and it looks out to 20km instead, though it then ignores the radius and returns at most 10 results. No API key required.

Inputs

LongitudelongitudenumberRequired
The east-west coordinate, in WGS84 decimal degrees. Negative is west of Greenwich, which is most of the UK.From -180.0 to 180.0.
LatitudelatitudenumberRequired
The north-south coordinate, in WGS84 decimal degrees.From -90.0 to 90.0.
How many resultslimitnumber
How many postcodes to return, from 1 to 100, nearest first. Leave empty for 10.From 1 to 100. Default: 10.
Search radius (metres)radiusnumber
How far out to look, in metres, from 1 to 2,000. Leave empty for 100m, which is a street rather than a neighbourhood: raise it for a rural address, where the nearest postcode can be a kilometre away.From 1 to 2000. Default: 100.
Wide searchwidesearchtrue/false
Look out to 20km instead of using the radius above. Turn this on for a point in open country, where the default 100m finds nothing. It is not simply a wider version of the same search: it ignores the radius entirely and returns at most 10 results however many were asked for.Default: false.

Outputs

countnumber
foundtrue/false
latitudenumber
limitnumber
longitudenumber
nearestobject
postcodeslist
radius_metresnumber
resultslist
widesearchtrue/false
Example output
{
  "count": 1,
  "found": true,
  "latitude": 51.50354,
  "limit": 10,
  "longitude": -0.127695,
  "nearest": {
    "admin_county": "(pseudo) England (UA/MD/LB)",
    "admin_district": "Westminster",
    "admin_ward": "St James's",
    "bua": "City of Westminster",
    "cancer_alliance": "West London",
    "ccg": "NHS North West London",
    "ced": null,
    "codes": {
      "admin_county": "E99999999",
      "admin_district": "E09000033",
      "admin_ward": "E05013806",
      "bua": "E63012036",
      "cancer_alliance": "E56000021",
      "ccg": "E38000256",
      "ced": "E99999999",
      "icb": "E54000027",
      "lau2": "E09000033",
      "lep1": "E37000051",
      "lep2": null,
      "lsoa": "E01004736",
      "lsoa11": "E01004736",
      "lsoa21": "E01004736",
      "msoa": "E02000977",
      "msoa11": "E02000977",
      "msoa21": "E02000977",
      "national_park": "E65000001",
      "nhs_region": "E40000003",
      "nuts": "TLI35",
      "oa21": "E00023938",
      "parish": "E43000236",
      "parliamentary_constituency": "E14001172",
      "parliamentary_constituency_2024": "E14001172",
      "pfa": "E23000001",
      "ruc11": "A1",
      "ruc21": "UN1",
      "ttwa": "E30000234"
    },
    "country": "England",
    "date_of_introduction": "198001",
    "date_of_termination": null,
    "eastings": 530047,
    "european_electoral_region": "London",
    "has_coordinates": true,
    "icb": "NHS North West London Integrated Care Board",
    "incode": "2AA",
    "index_of_multiple_deprivation": 24862,
    "introduced_on": "1980-01",
    "latitude": 51.50354,
    "lep1": "London",
    "lep2": null,
    "longitude": -0.127695,
    "lsoa": "Westminster 018C",
    "lsoa11": "Westminster 018C",
    "lsoa21": "Westminster 018C",
    "map_url": "https://www.openstreetmap.org/?mlat=51.50354&mlon=-0.127695#map=16/51.50354/-0.127695",
    "msoa": "Westminster 018",
    "msoa11": "Westminster 018",
    "msoa21": "Westminster 018",
    "national_park": "England (non-National Park)",
    "nhs_ha": "London",
    "nhs_region": "London",
    "northings": 179951,
    "not_applicable": [
      "admin_county",
      "ced"
    ],
    "nuts": "Westminster",
    "oa21": "E00023938",
    "outcode": "SW1A",
    "parish": "Westminster, unparished area",
    "parliamentary_constituency": "Cities of London and Westminster",
    "parliamentary_constituency_2024": "Cities of London and Westminster",
    "pfa": "Metropolitan Police",
    "postcode": "SW1A 2AA",
    "primary_care_trust": "Westminster",
    "quality": 1,
    "quality_description": "Within the building of the matched address closest to the postcode mean",
    "region": "London",
    "ruc11": "(England/Wales) Urban major conurbation",
    "ruc21": "Urban: Nearer to a major town or city",
    "senedd_constituency": null,
    "senedd_constituency_no": null,
    "summary": "SW1A 2AA - St James's, Westminster, London",
    "ttwa": "London"
  },
  "postcodes": [
    "SW1A 2AA"
  ],
  "radius_metres": 100,
  "results": [
    {
      "admin_county": "(pseudo) England (UA/MD/LB)",
      "admin_district": "Westminster",
      "admin_ward": "St James's",
      "bua": "City of Westminster",
      "cancer_alliance": "West London",
      "ccg": "NHS North West London",
      "ced": null,
      "codes": {
        "admin_county": "E99999999",
        "admin_district": "E09000033",
        "admin_ward": "E05013806",
        "bua": "E63012036",
        "cancer_alliance": "E56000021",
        "ccg": "E38000256",
        "ced": "E99999999",
        "icb": "E54000027",
        "lau2": "E09000033",
        "lep1": "E37000051",
        "lep2": null,
        "lsoa": "E01004736",
        "lsoa11": "E01004736",
        "lsoa21": "E01004736",
        "msoa": "E02000977",
        "msoa11": "E02000977",
        "msoa21": "E02000977",
        "national_park": "E65000001",
        "nhs_region": "E40000003",
        "nuts": "TLI35",
        "oa21": "E00023938",
        "parish": "E43000236",
        "parliamentary_constituency": "E14001172",
        "parliamentary_constituency_2024": "E14001172",
        "pfa": "E23000001",
        "ruc11": "A1",
        "ruc21": "UN1",
        "ttwa": "E30000234"
      },
      "country": "England",
      "date_of_introduction": "198001",
      "date_of_termination": null,
      "eastings": 530047,
      "european_electoral_region": "London",
      "has_coordinates": true,
      "icb": "NHS North West London Integrated Care Board",
      "incode": "2AA",
      "index_of_multiple_deprivation": 24862,
      "introduced_on": "1980-01",
      "latitude": 51.50354,
      "lep1": "London",
      "lep2": null,
      "longitude": -0.127695,
      "lsoa": "Westminster 018C",
      "lsoa11": "Westminster 018C",
      "lsoa21": "Westminster 018C",
      "map_url": "https://www.openstreetmap.org/?mlat=51.50354&mlon=-0.127695#map=16/51.50354/-0.127695",
      "msoa": "Westminster 018",
      "msoa11": "Westminster 018",
      "msoa21": "Westminster 018",
      "national_park": "England (non-National Park)",
      "nhs_ha": "London",
      "nhs_region": "London",
      "northings": 179951,
      "not_applicable": [
        "admin_county",
        "ced"
      ],
      "nuts": "Westminster",
      "oa21": "E00023938",
      "outcode": "SW1A",
      "parish": "Westminster, unparished area",
      "parliamentary_constituency": "Cities of London and Westminster",
      "parliamentary_constituency_2024": "Cities of London and Westminster",
      "pfa": "Metropolitan Police",
      "postcode": "SW1A 2AA",
      "primary_care_trust": "Westminster",
      "quality": 1,
      "quality_description": "Within the building of the matched address closest to the postcode mean",
      "region": "London",
      "ruc11": "(England/Wales) Urban major conurbation",
      "ruc21": "Urban: Nearer to a major town or city",
      "senedd_constituency": null,
      "senedd_constituency_no": null,
      "summary": "SW1A 2AA - St James's, Westminster, London",
      "ttwa": "London"
    }
  ],
  "widesearch": false
}

Reverse geocode coordinates in bulk

Turn many coordinate pairs into UK postcodes in one step: a day of GPS readings, a set of pins, a list of site locations. Every point gets its own row with the nearest postcode and everything else in range, and the points that matched nothing are counted rather than left as gaps. Postcodes.io takes 100 points per request and refuses more, so a longer list is batched automatically, up to 1,000. No API key required.

Inputs

CoordinatescoordinateslistRequired
The points to look up, latitude first, as a person reads them off a map. Give one 'latitude, longitude' pair per line, or a list of objects with 'longitude' and 'latitude'. Up to 1,000 points.
How many resultslimitnumber
How many postcodes to return, from 1 to 100, nearest first. Leave empty for 10.From 1 to 100. Default: 10.
Search radius (metres)radiusnumber
How far out to look, in metres, from 1 to 2,000. Leave empty for 100m, which is a street rather than a neighbourhood: raise it for a rural address, where the nearest postcode can be a kilometre away.From 1 to 2000. Default: 100.
Wide searchwidesearchtrue/false
Look out to 20km instead of using the radius above. Turn this on for a point in open country, where the default 100m finds nothing. It is not simply a wider version of the same search: it ignores the radius entirely and returns at most 10 results however many were asked for.Default: false.
Fields to returnfieldslist
Trim every result down to just these fields, which keeps a hundred-postcode answer small. Leave empty to get everything. Postcodes.io only filters on the fields listed here and silently ignores any other name, so anything else is refused rather than quietly returning the lot. Note that a trimmed result skips the extra fields this integration adds, such as the map link and the plain-English position quality, because those are worked out from fields the filter may have removed.One or more of: postcode, longitude, latitude, eastings (Eastings (British National Grid)), northings (Northings (British National Grid)), quality (Positional quality (1 to 9)), country, region, admin_district (Local authority district), admin_county (County), and 14 more.

Outputs

fieldslist
foundtrue/false
limitnumber
matched_countnumber
radius_metresnumber
request_countnumber
requested_countnumber
resultslist
unmatched_countnumber
widesearchtrue/false
Example output
{
  "fields": [],
  "found": true,
  "limit": 10,
  "matched_count": 1,
  "radius_metres": 100,
  "request_count": 1,
  "requested_count": 1,
  "results": [
    {
      "count": 1,
      "found": true,
      "latitude": 51.50354,
      "longitude": -0.127695,
      "nearest": {
        "admin_county": "(pseudo) England (UA/MD/LB)",
        "admin_district": "Westminster",
        "admin_ward": "St James's",
        "bua": "City of Westminster",
        "cancer_alliance": "West London",
        "ccg": "NHS North West London",
        "ced": null,
        "codes": {
          "admin_county": "E99999999",
          "admin_district": "E09000033",
          "admin_ward": "E05013806",
          "bua": "E63012036",
          "cancer_alliance": "E56000021",
          "ccg": "E38000256",
          "ced": "E99999999",
          "icb": "E54000027",
          "lau2": "E09000033",
          "lep1": "E37000051",
          "lep2": null,
          "lsoa": "E01004736",
          "lsoa11": "E01004736",
          "lsoa21": "E01004736",
          "msoa": "E02000977",
          "msoa11": "E02000977",
          "msoa21": "E02000977",
          "national_park": "E65000001",
          "nhs_region": "E40000003",
          "nuts": "TLI35",
          "oa21": "E00023938",
          "parish": "E43000236",
          "parliamentary_constituency": "E14001172",
          "parliamentary_constituency_2024": "E14001172",
          "pfa": "E23000001",
          "ruc11": "A1",
          "ruc21": "UN1",
          "ttwa": "E30000234"
        },
        "country": "England",
        "date_of_introduction": "198001",
        "date_of_termination": null,
        "eastings": 530047,
        "european_electoral_region": "London",
        "has_coordinates": true,
        "icb": "NHS North West London Integrated Care Board",
        "incode": "2AA",
        "index_of_multiple_deprivation": 24862,
        "introduced_on": "1980-01",
        "latitude": 51.50354,
        "lep1": "London",
        "lep2": null,
        "longitude": -0.127695,
        "lsoa": "Westminster 018C",
        "lsoa11": "Westminster 018C",
        "lsoa21": "Westminster 018C",
        "map_url": "https://www.openstreetmap.org/?mlat=51.50354&mlon=-0.127695#map=16/51.50354/-0.127695",
        "msoa": "Westminster 018",
        "msoa11": "Westminster 018",
        "msoa21": "Westminster 018",
        "national_park": "England (non-National Park)",
        "nhs_ha": "London",
        "nhs_region": "London",
        "northings": 179951,
        "not_applicable": [
          "admin_county",
          "ced"
        ],
        "nuts": "Westminster",
        "oa21": "E00023938",
        "outcode": "SW1A",
        "parish": "Westminster, unparished area",
        "parliamentary_constituency": "Cities of London and Westminster",
        "parliamentary_constituency_2024": "Cities of London and Westminster",
        "pfa": "Metropolitan Police",
        "postcode": "SW1A 2AA",
        "primary_care_trust": "Westminster",
        "quality": 1,
        "quality_description": "Within the building of the matched address closest to the postcode mean",
        "region": "London",
        "ruc11": "(England/Wales) Urban major conurbation",
        "ruc21": "Urban: Nearer to a major town or city",
        "senedd_constituency": null,
        "senedd_constituency_no": null,
        "summary": "SW1A 2AA - St James's, Westminster, London",
        "ttwa": "London"
      },
      "postcodes": [
        "SW1A 2AA"
      ],
      "results": [
        {
          "admin_county": "(pseudo) England (UA/MD/LB)",
          "admin_district": "Westminster",
          "admin_ward": "St James's",
          "bua": "City of Westminster",
          "cancer_alliance": "West London",
          "ccg": "NHS North West London",
          "ced": null,
          "codes": {
            "admin_county": "E99999999",
            "admin_district": "E09000033",
            "admin_ward": "E05013806",
            "bua": "E63012036",
            "cancer_alliance": "E56000021",
            "ccg": "E38000256",
            "ced": "E99999999",
            "icb": "E54000027",
            "lau2": "E09000033",
            "lep1": "E37000051",
            "lep2": null,
            "lsoa": "E01004736",
            "lsoa11": "E01004736",
            "lsoa21": "E01004736",
            "msoa": "E02000977",
            "msoa11": "E02000977",
            "msoa21": "E02000977",
            "national_park": "E65000001",
            "nhs_region": "E40000003",
            "nuts": "TLI35",
            "oa21": "E00023938",
            "parish": "E43000236",
            "parliamentary_constituency": "E14001172",
            "parliamentary_constituency_2024": "E14001172",
            "pfa": "E23000001",
            "ruc11": "A1",
            "ruc21": "UN1",
            "ttwa": "E30000234"
          },
          "country": "England",
          "date_of_introduction": "198001",
          "date_of_termination": null,
          "eastings": 530047,
          "european_electoral_region": "London",
          "has_coordinates": true,
          "icb": "NHS North West London Integrated Care Board",
          "incode": "2AA",
          "index_of_multiple_deprivation": 24862,
          "introduced_on": "1980-01",
          "latitude": 51.50354,
          "lep1": "London",
          "lep2": null,
          "longitude": -0.127695,
          "lsoa": "Westminster 018C",
          "lsoa11": "Westminster 018C",
          "lsoa21": "Westminster 018C",
          "map_url": "https://www.openstreetmap.org/?mlat=51.50354&mlon=-0.127695#map=16/51.50354/-0.127695",
          "msoa": "Westminster 018",
          "msoa11": "Westminster 018",
          "msoa21": "Westminster 018",
          "national_park": "England (non-National Park)",
          "nhs_ha": "London",
          "nhs_region": "London",
          "northings": 179951,
          "not_applicable": [
            "admin_county",
            "ced"
          ],
          "nuts": "Westminster",
          "oa21": "E00023938",
          "outcode": "SW1A",
          "parish": "Westminster, unparished area",
          "parliamentary_constituency": "Cities of London and Westminster",
          "parliamentary_constituency_2024": "Cities of London and Westminster",
          "pfa": "Metropolitan Police",
          "postcode": "SW1A 2AA",
          "primary_care_trust": "Westminster",
          "quality": 1,
          "quality_description": "Within the building of the matched address closest to the postcode mean",
          "region": "London",
          "ruc11": "(England/Wales) Urban major conurbation",
          "ruc21": "Urban: Nearer to a major town or city",
          "senedd_constituency": null,
          "senedd_constituency_no": null,
          "summary": "SW1A 2AA - St James's, Westminster, London",
          "ttwa": "London"
        }
      ]
    }
  ],
  "unmatched_count": 0,
  "widesearch": false
}

Reverse geocode to outward codes

Turn a longitude and latitude into the outward codes around it, nearest first. A coarser and much smaller answer than a full postcode: this is the step for 'roughly which postal area is this?', or for grouping a set of points into districts. It works where a postcode lookup finds nothing, because the default radius is 5km rather than 100 metres. No API key required.

Inputs

LongitudelongitudenumberRequired
The east-west coordinate, in WGS84 decimal degrees. Negative is west of Greenwich, which is most of the UK.From -180.0 to 180.0.
LatitudelatitudenumberRequired
The north-south coordinate, in WGS84 decimal degrees.From -90.0 to 90.0.
How many resultslimitnumber
How many outward codes to return, from 1 to 100, nearest first. Leave empty for 10.From 1 to 100. Default: 10.
Search radius (metres)radiusnumber
How far out to look, in metres, from 1 to 25,000. Leave empty for 5,000m. Outward codes are much further apart than postcodes, which is why this reaches further than the postcode search does.From 1 to 25000. Default: 5000.

Outputs

countnumber
foundtrue/false
latitudenumber
limitnumber
longitudenumber
nearestobject
outcodeslist
radius_metresnumber
resultslist
Example output
{
  "count": 1,
  "found": true,
  "latitude": 54.9724,
  "limit": 10,
  "longitude": -1.6115,
  "nearest": {
    "admin_county": [
      "(pseudo) England (UA/MD/LB)"
    ],
    "admin_district": [
      "Newcastle upon Tyne"
    ],
    "admin_ward": [
      "Monument"
    ],
    "constituency_count": 1,
    "country": [
      "England"
    ],
    "distance": 199.7,
    "distance_km": 0.2,
    "distance_metres": 199.7,
    "distance_miles": 0.124,
    "district_count": 1,
    "eastings": 424930,
    "has_coordinates": true,
    "latitude": 54.9738,
    "longitude": -1.61396,
    "map_url": "https://www.openstreetmap.org/?mlat=54.9738&mlon=-1.61396#map=16/54.9738/-1.61396",
    "northings": 564295,
    "not_applicable": [
      "admin_county"
    ],
    "outcode": "NE1",
    "parish": [
      "Newcastle upon Tyne, unparished area"
    ],
    "parliamentary_constituency": [
      "Newcastle upon Tyne Central"
    ],
    "summary": "NE1 - Newcastle upon Tyne",
    "ward_count": 1
  },
  "outcodes": [
    "NE1"
  ],
  "radius_metres": 5000,
  "results": [
    {
      "admin_county": [
        "(pseudo) England (UA/MD/LB)"
      ],
      "admin_district": [
        "Newcastle upon Tyne"
      ],
      "admin_ward": [
        "Monument"
      ],
      "constituency_count": 1,
      "country": [
        "England"
      ],
      "distance": 199.7,
      "distance_km": 0.2,
      "distance_metres": 199.7,
      "distance_miles": 0.124,
      "district_count": 1,
      "eastings": 424930,
      "has_coordinates": true,
      "latitude": 54.9738,
      "longitude": -1.61396,
      "map_url": "https://www.openstreetmap.org/?mlat=54.9738&mlon=-1.61396#map=16/54.9738/-1.61396",
      "northings": 564295,
      "not_applicable": [
        "admin_county"
      ],
      "outcode": "NE1",
      "parish": [
        "Newcastle upon Tyne, unparished area"
      ],
      "parliamentary_constituency": [
        "Newcastle upon Tyne Central"
      ],
      "summary": "NE1 - Newcastle upon Tyne",
      "ward_count": 1
    }
  ]
}

Search places

Find British places by name, from Ordnance Survey's Open Names: towns, villages, suburbs, hamlets and other gazetteer entries, each with its county, region, country, outward code and coordinates. Use it to turn a place name a person typed into a real location. Welsh and Gaelic names are matched too and come back alongside the English one. Great Britain only: Northern Ireland is not in this dataset. No API key required.

Inputs

Place namequerytextRequired
The name to search for, whole or partial. Matches the primary name and the Welsh or Gaelic one.
How many resultslimitnumber
How many places to return, from 1 to 100. Leave empty for 10.From 1 to 100. Default: 10.

Outputs

countnumber
foundtrue/false
limitnumber
nameslist
querytext
resultslist
Example output
{
  "count": 1,
  "found": true,
  "limit": 10,
  "names": [
    "Edinburgh"
  ],
  "query": "Edinburgh",
  "results": [
    {
      "alternate_name": "Dun Eideann",
      "alternate_name_language": "gla",
      "code": "osgb4000000074502842",
      "country": "Scotland",
      "county_unitary": "City of Edinburgh",
      "county_unitary_type": "UnitaryAuthority",
      "district_borough": null,
      "district_borough_type": null,
      "eastings": 326036,
      "has_coordinates": true,
      "latitude": 55.953251,
      "local_type": "City",
      "longitude": -3.188267,
      "map_url": "https://www.openstreetmap.org/?mlat=55.953251&mlon=-3.188267#map=16/55.953251/-3.188267",
      "max_eastings": 335533,
      "max_northings": 680564,
      "min_eastings": 316471,
      "min_northings": 665453,
      "name": "Edinburgh",
      "name_1": "Edinburgh",
      "name_1_lang": null,
      "name_2": "Dun Eideann",
      "name_2_lang": "gla",
      "northings": 673985,
      "outcode": "EH1",
      "region": "Scotland",
      "summary": "Edinburgh - City of Edinburgh, Scotland (City)"
    }
  ]
}

Search postcodes

Find live UK postcodes that start with a string, each with its full record. Use it to turn a partial postcode into real ones, or an outward code into the postcodes inside it. Exact matches win: searching for a postcode the service holds returns that one rather than everything sharing its prefix. Terminated postcodes are never returned. Use Autocomplete a postcode instead when only the postcode strings are wanted. No API key required.

Inputs

Search forquerytextRequired
A whole or partial postcode. An outward code such as 'SW1A' returns the postcodes inside it.
How many resultslimitnumber
How many postcodes to return, from 1 to 100. Leave empty for 10.From 1 to 100. Default: 10.

Outputs

countnumber
foundtrue/false
limitnumber
postcodeslist
querytext
resultslist
Example output
{
  "count": 1,
  "found": true,
  "limit": 10,
  "postcodes": [
    "SW1A 2AA"
  ],
  "query": "SW1A",
  "results": [
    {
      "admin_county": "(pseudo) England (UA/MD/LB)",
      "admin_district": "Westminster",
      "admin_ward": "St James's",
      "bua": "City of Westminster",
      "cancer_alliance": "West London",
      "ccg": "NHS North West London",
      "ced": null,
      "codes": {
        "admin_county": "E99999999",
        "admin_district": "E09000033",
        "admin_ward": "E05013806",
        "bua": "E63012036",
        "cancer_alliance": "E56000021",
        "ccg": "E38000256",
        "ced": "E99999999",
        "icb": "E54000027",
        "lau2": "E09000033",
        "lep1": "E37000051",
        "lep2": null,
        "lsoa": "E01004736",
        "lsoa11": "E01004736",
        "lsoa21": "E01004736",
        "msoa": "E02000977",
        "msoa11": "E02000977",
        "msoa21": "E02000977",
        "national_park": "E65000001",
        "nhs_region": "E40000003",
        "nuts": "TLI35",
        "oa21": "E00023938",
        "parish": "E43000236",
        "parliamentary_constituency": "E14001172",
        "parliamentary_constituency_2024": "E14001172",
        "pfa": "E23000001",
        "ruc11": "A1",
        "ruc21": "UN1",
        "ttwa": "E30000234"
      },
      "country": "England",
      "date_of_introduction": "198001",
      "date_of_termination": null,
      "eastings": 530047,
      "european_electoral_region": "London",
      "has_coordinates": true,
      "icb": "NHS North West London Integrated Care Board",
      "incode": "2AA",
      "index_of_multiple_deprivation": 24862,
      "introduced_on": "1980-01",
      "latitude": 51.50354,
      "lep1": "London",
      "lep2": null,
      "longitude": -0.127695,
      "lsoa": "Westminster 018C",
      "lsoa11": "Westminster 018C",
      "lsoa21": "Westminster 018C",
      "map_url": "https://www.openstreetmap.org/?mlat=51.50354&mlon=-0.127695#map=16/51.50354/-0.127695",
      "msoa": "Westminster 018",
      "msoa11": "Westminster 018",
      "msoa21": "Westminster 018",
      "national_park": "England (non-National Park)",
      "nhs_ha": "London",
      "nhs_region": "London",
      "northings": 179951,
      "not_applicable": [
        "admin_county",
        "ced"
      ],
      "nuts": "Westminster",
      "oa21": "E00023938",
      "outcode": "SW1A",
      "parish": "Westminster, unparished area",
      "parliamentary_constituency": "Cities of London and Westminster",
      "parliamentary_constituency_2024": "Cities of London and Westminster",
      "pfa": "Metropolitan Police",
      "postcode": "SW1A 2AA",
      "primary_care_trust": "Westminster",
      "quality": 1,
      "quality_description": "Within the building of the matched address closest to the postcode mean",
      "region": "London",
      "ruc11": "(England/Wales) Urban major conurbation",
      "ruc21": "Urban: Nearer to a major town or city",
      "senedd_constituency": null,
      "senedd_constituency_no": null,
      "summary": "SW1A 2AA - St James's, Westminster, London",
      "ttwa": "London"
    }
  ]
}

Validate a postcode

Check whether a string is a live UK postcode. This is a real existence check against the Office for National Statistics postcode directory, not a format check: 'ZZ99 9ZZ' is correctly shaped and is not a postcode, and this says so. When the answer is no, the step also says whether the postcode used to exist and when it was withdrawn, so an address form can tell a customer 'that postcode was retired in 2018' rather than just rejecting it. Ideal in a condition before the rest of a workflow runs. No API key required.

Inputs

PostcodepostcodetextRequired
A UK postcode. Spacing and capitalisation do not matter: 'sw1a2aa' and 'SW1A 2AA' reach the same record.

Outputs

messagetext
postcodetext
terminatedtrue/false
terminated_recordobject
validtrue/false
Example output
{
  "message": "SW1A 2AA is a live UK postcode.",
  "postcode": "SW1A 2AA",
  "terminated": false,
  "terminated_record": null,
  "valid": true
}

Politics & War

Previous Page

PostHog

Next Page

On this page

ActionsAutocomplete a postcodeFind nearest outward codesFind nearest postcodesGet a random placeGet a random postcodeLook up a placeLook up a postcodeLook up a Scottish postcodeLook up a terminated postcodeLook up an outward codeLook up postcodes in bulkMeasure the distance between two postcodesReverse geocode coordinatesReverse geocode coordinates in bulkReverse geocode to outward codesSearch placesSearch postcodesValidate a postcode