# Postcodes.io > 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. App · Travel & Places · 18 actions. Web page: https://docs.lodol.com/docs/integrations/postcodes-io ## Actions ### 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 postcode (`postcode`, text, required): As much of the postcode as is known. Spacing and capitalisation do not matter. - How many results (`limit`, number): How many postcodes to return, from 1 to 100. Leave empty for 10. From 1 to 100. Default: `10`. **Outputs** - `count` (number) - `found` (true/false) - `limit` (number) - `postcodes` (list) - `query` (text) **Example output** ```json { "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 code (`outcode`, text, required): The part of a postcode before the space, such as 'SW1A' in 'SW1A 2AA'. Two to four characters. - How many results (`limit`, number): 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) (`radius`, number): 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** - `count` (number) - `found` (true/false) - `limit` (number) - `nearest` (object) - `outcode` (text) - `outcodes` (list) - `radius_metres` (number) - `results` (list) **Example output** ```json { "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** - Postcode (`postcode`, text, required): A UK postcode. Spacing and capitalisation do not matter: 'sw1a2aa' and 'SW1A 2AA' reach the same record. - How many results (`limit`, number): How many postcodes to return, from 1 to 100, nearest first. Leave empty for 10. From 1 to 100. Default: `10`. - Search radius (metres) (`radius`, number): 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** - `count` (number) - `found` (true/false) - `limit` (number) - `nearest` (object) - `postcode` (text) - `postcodes` (list) - `radius_metres` (number) - `results` (list) - `widesearch` (true/false) **Example output** ```json { "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** - `code` (text) - `found` (true/false) - `message` (text) - `name` (text) - `result` (object) **Example output** ```json { "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 code (`outcode`, text): Restrict the pick to one outward code, such as 'SW1A'. Leave empty to draw from the whole of the UK. **Outputs** - `found` (true/false) - `message` (text) - `outcode` (text) - `postcode` (text) - `result` (object) **Example output** ```json { "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 code (`code`, text, required): 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** - `code` (text) - `found` (true/false) - `message` (text) - `name` (text) - `result` (object) **Example output** ```json { "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** - Postcode (`postcode`, text, required): A UK postcode. Spacing and capitalisation do not matter: 'sw1a2aa' and 'SW1A 2AA' reach the same record. **Outputs** - `found` (true/false) - `message` (text) - `postcode` (text) - `result` (object) - `terminated` (true/false) - `terminated_record` (object) **Example output** ```json { "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 postcode (`postcode`, text, required): A postcode in Scotland. Spacing and capitalisation do not matter. **Outputs** - `found` (true/false) - `in_scotland` (true/false) - `message` (text) - `postcode` (text) - `result` (object) **Example output** ```json { "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 postcode (`postcode`, text, required): 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** - `found` (true/false) - `message` (text) - `postcode` (text) - `result` (object) - `terminated_on` (text) **Example output** ```json { "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 code (`outcode`, text, required): The part of a postcode before the space, such as 'SW1A' in 'SW1A 2AA'. Two to four characters. **Outputs** - `found` (true/false) - `message` (text) - `outcode` (text) - `result` (object) **Example output** ```json { "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** - Postcodes (`postcodes`, list, required): 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 return (`fields`, list): 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** - `fields` (list) - `found` (true/false) - `matched` (list) - `matched_count` (number) - `postcodes` (list) - `request_count` (number) - `requested_count` (number) - `results` (list) - `unmatched` (list) - `unmatched_count` (number) **Example output** ```json { "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 postcode (`origin`, text, required): The postcode to measure from. - To postcode (`destination`, text, required): The postcode to measure to. **Outputs** - `destination` (text) - `destination_result` (object) - `distance_km` (number) - `distance_metres` (number) - `distance_miles` (number) - `found` (true/false) - `origin` (text) - `origin_result` (object) - `same_constituency` (true/false) - `same_country` (true/false) - `same_district` (true/false) **Example output** ```json { "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** - Longitude (`longitude`, number, required): 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. - Latitude (`latitude`, number, required): The north-south coordinate, in WGS84 decimal degrees. From -90.0 to 90.0. - How many results (`limit`, number): How many postcodes to return, from 1 to 100, nearest first. Leave empty for 10. From 1 to 100. Default: `10`. - Search radius (metres) (`radius`, number): 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 search (`widesearch`, true/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** - `count` (number) - `found` (true/false) - `latitude` (number) - `limit` (number) - `longitude` (number) - `nearest` (object) - `postcodes` (list) - `radius_metres` (number) - `results` (list) - `widesearch` (true/false) **Example output** ```json { "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** - Coordinates (`coordinates`, list, required): 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 results (`limit`, number): How many postcodes to return, from 1 to 100, nearest first. Leave empty for 10. From 1 to 100. Default: `10`. - Search radius (metres) (`radius`, number): 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 search (`widesearch`, true/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 return (`fields`, list): 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** - `fields` (list) - `found` (true/false) - `limit` (number) - `matched_count` (number) - `radius_metres` (number) - `request_count` (number) - `requested_count` (number) - `results` (list) - `unmatched_count` (number) - `widesearch` (true/false) **Example output** ```json { "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** - Longitude (`longitude`, number, required): 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. - Latitude (`latitude`, number, required): The north-south coordinate, in WGS84 decimal degrees. From -90.0 to 90.0. - How many results (`limit`, number): 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) (`radius`, number): 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** - `count` (number) - `found` (true/false) - `latitude` (number) - `limit` (number) - `longitude` (number) - `nearest` (object) - `outcodes` (list) - `radius_metres` (number) - `results` (list) **Example output** ```json { "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 name (`query`, text, required): The name to search for, whole or partial. Matches the primary name and the Welsh or Gaelic one. - How many results (`limit`, number): How many places to return, from 1 to 100. Leave empty for 10. From 1 to 100. Default: `10`. **Outputs** - `count` (number) - `found` (true/false) - `limit` (number) - `names` (list) - `query` (text) - `results` (list) **Example output** ```json { "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 for (`query`, text, required): A whole or partial postcode. An outward code such as 'SW1A' returns the postcodes inside it. - How many results (`limit`, number): How many postcodes to return, from 1 to 100. Leave empty for 10. From 1 to 100. Default: `10`. **Outputs** - `count` (number) - `found` (true/false) - `limit` (number) - `postcodes` (list) - `query` (text) - `results` (list) **Example output** ```json { "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** - Postcode (`postcode`, text, required): A UK postcode. Spacing and capitalisation do not matter: 'sw1a2aa' and 'SW1A 2AA' reach the same record. **Outputs** - `message` (text) - `postcode` (text) - `terminated` (true/false) - `terminated_record` (object) - `valid` (true/false) **Example output** ```json { "message": "SW1A 2AA is a live UK postcode.", "postcode": "SW1A 2AA", "terminated": false, "terminated_record": null, "valid": true } ```