Open Postcode Geo API

Open Postcode Geo - API Version

Description

British postcodes with easting, northing, latitude, and longitude.

With additional fields for geospace applications, including postcode area, postcode district, postcode sector, incode, and outcode.

The same data is available in a flat file here.

Licence

Free to use for any purpose - attribution required.

Open Postcode Geo is derived from the ONS Postcode Directory which is licenced under the Open Government Licence and the Ordnance Survey OpenData Licence. Northern Irish postcodes have been removed as these are covered by a more restrictive licence. You may use the additional fields provided by GetTheData without restriction.

For details of the required attribution statements see the ONS Licences page.

Version

The current version of Open Postcode Geo is derived from the August 2023 Postcode Directory release.

Usage

Open Postcode Geo API takes [input] which can be one of the following:

Unit Postcode
Postcode Sector
Postcode District
Postcode Area

Various formats are supported.

[input] should be URL encoded. In practice this means replacing space characters with either + or %20.

Syntax

http://api.getthedata.com/postcode/[input]

Clickable Examples

Unit Postcode:
Postcode Sector:
Postcode District:
Postcode Area:

Supported Formats

Postcodes are formatted with incode and outcode separated by zero, one, or multiple spaces, any of which formats are supported.

The below examples show this in practice:

Input type	Examples
Unit Postcode	`RG253AB` `RG25 3AB` `RG25 3AB` `RG25 3AB`
Postcode Sector	`RG253` `RG25 3` `RG25 3` `RG25 3`
Postcode District	`RG25`
Postcode Area	`RG`

Ambiguity Resolution

A penalty of this flexible approach is that ambiguities can arise between Postcode Districts and Postcode Sectors where a Postcode District is the same character sequence as a Postcode Sector minus the delimiting space.

An example would be Postcode District RG26 and Postcode Sector RG2 6.

In such cases the Postcode District is always tested first, followed by the Postcode Sector only where no matching Postcode District can be found.

If this is a concern then always test Postcode Sector formatted with one or more delimiting spaces.

Response

The response is provided in JSON.

Field	Possible Values	Comments
status	match no_match	Whether [input] has matched or not.
error	error message	Where [input] does not match a verbose error message will be supplied here.
match_type	unit_postcode postcode_sector postcode_district postcode_area	Where [input] does match, the type of match will be returned.
input		The [input] provided in the request.
data	[array]	See table below.
copyright	[array]	Copyright statements from the data owners.

Fields and values within the data array of the response

The API will attempt to return as many of the below as possible.

Field	Possible Values	Comments
postcode	[outcode][space][incode]	Standard UK postcode.
status	live terminated	Terminated postcodes are no longer in use.
usertype	small large	Large usertypes may not be geographic.
easting	int NULL
northing	int NULL
positional_quality_indicator	int	See Positional Quality Indicator below
country	England Wales Scotland Northern Ireland Channel Islands Isle of Man
latitude	decimal
longitude	decimal
postcode_no_space	[outcode][incode]	Postcode with space removed.
postcode_fixed_width_seven	See comments	Outcode and incode separated by zero, one, or two spaces. Incode right aligned. Always seven characters in total.
postcode_fixed_width_eight	See comments	Outcode and incode separated by one, two or three spaces. Incode right aligned. Always eight characters in total.
postcode_area	[A-Z]{1,2}	One or two letters.
postcode_district	[outcode]
postcode_sector	[outcode][space][number]
outcode	[outcode]
incode	[incode]

Positional Quality Indicator

Shows the status of the assigned grid reference:

Within the building of the matched address closest to the postcode mean.
As for status value 1, except by visual inspection of Landline maps (Scotland only).
Approximate to within 50 metres.
Postcode unit mean (mean of matched addresses with the same postcode, but not snapped to a building).
Imputed by ONS, by reference to surrounding postcode grid references.
Postcode sector mean, (mainly PO Boxes).
Not used.
Postcode terminated prior to Gridlink® initiative, last known ONS postcode grid reference.
No grid reference available.

Example Responses

Unit Postcode

Request: http://api.getthedata.com/postcode/WC1A+1AB

{
	"status": "match",
	"match_type": "unit_postcode",
	"input": "WC1A 1AB",
	"data": {
		"postcode": "WC1A 1AB",
		"status": "live",
		"usertype": "small",
		"easting": 530186,
		"northing": 181384,
		"positional_quality_indicator": 1,
		"country": "England",
		"latitude": 51.516399383545,
		"longitude": -0.1251650005579,
		"postcode_no_space": "WC1A1AB",
		"postcode_fixed_width_seven": "WC1A1AB",
		"postcode_fixed_width_eight": "WC1A 1AB",
		"postcode_area": "WC",
		"postcode_district": "WC1A",
		"postcode_sector": "WC1A 1",
		"outcode": "WC1A",
		"incode": "1AB"
	},
	"copyright": [
		"Contains OS data (c) Crown copyright and database right 2016",
		"Contains Royal Mail data (c) Royal Mail copyright and database right 2016",
		"Contains National Statistics data (c) Crown copyright and database right 2016"
	]
}

Postcode Sector

Request: http://api.getthedata.com/postcode/WC1A+1

{
	"status": "match",
	"match_type": "postcode_sector",
	"input": "WC1A 1",
	"data": {
		"postcode_area": "WC",
		"postcode_district": "WC1A",
		"postcode_sector": "WC1A 1",
		"outcode": "WC1A"
	},
	"copyright": [
		"Contains OS data (c) Crown copyright and database right 2016",
		"Contains Royal Mail data (c) Royal Mail copyright and database right 2016",
		"Contains National Statistics data (c) Crown copyright and database right 2016"
	]
}

Postcode District

Request: http://api.getthedata.com/postcode/WC1A

{
	"status": "match",
	"match_type": "postcode_district",
	"input": "WC1A",
	"data": {
		"postcode_area": "WC",
		"postcode_district": "WC1A",
		"outcode": "WC1A"
	},
	"copyright": [
		"Contains OS data (c) Crown copyright and database right 2016",
		"Contains Royal Mail data (c) Royal Mail copyright and database right 2016",
		"Contains National Statistics data (c) Crown copyright and database right 2016"
	]
}

Postcode Area

Request: http://api.getthedata.com/postcode/WC

{
	"status": "match",
	"match_type": "postcode_area",
	"input": "WC",
	"data": {
		"postcode_area": "WC"
	},
	"copyright": [
		"Contains OS data (c) Crown copyright and database right 2016",
		"Contains Royal Mail data (c) Royal Mail copyright and database right 2016",
		"Contains National Statistics data (c) Crown copyright and database right 2016"
	]
}

Error

Request: http://api.getthedata.com/postcode/WC1

{
	"status": "no_match",
	"error": "No matching postcode district found.",
	"input": "WC1",
	"copyright": [
		"Contains OS data (c) Crown copyright and database right 2016",
		"Contains Royal Mail data (c) Royal Mail copyright and database right 2016",
		"Contains National Statistics data (c) Crown copyright and database right 2016"
	]
}