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 February 2017 ONS Postcode Directory release.

Usage

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

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:
http://api.getthedata.com/postcode/SW1A+1AA
Postcode Sector:
http://api.getthedata.com/postcode/SW1A+1
Postcode District:
http://api.getthedata.com/postcode/SW1A
Postcode Area:
http://api.getthedata.com/postcode/SW

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:

  1. Within the building of the matched address closest to the postcode mean.
  2. As for status value 1, except by visual inspection of Landline maps (Scotland only).
  3. Approximate to within 50 metres.
  4. Postcode unit mean (mean of matched addresses with the same postcode, but not snapped to a building).
  5. Imputed by ONS, by reference to surrounding postcode grid references.
  6. Postcode sector mean, (mainly PO Boxes).
  7. Not used.
  8. Postcode terminated prior to Gridlink® initiative, last known ONS postcode grid reference.
  9. 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"
	]
}