UK Postcode Geocodes

---

HTTP(S) Request

GET/POST http://pcls1.craftyclicks.co.uk/json/geocode

or

GET/POST https://pcls1.craftyclicks.co.uk/json/geocode

Query Parameters

Pass parameters either in GET or in JSON. Some parameters are only available in JSON.

Key	Type	Required	Available	Description
key	string	✔️	Both	Using the API requires a 20 character access token, which you should insert here. You will receive an access token when you sign up for an account.
postcodes	array of strings	✔️ (if postcode parameter is not set)	JSON	These are the postcodes for which you request data (max 25). This parameter is not case sensitive, and it also handles the optional space in the middle of the postcodes.
postcode	string	✔️ (if postcodes parameter is not set)	GET	The postcode for which you request data. This parameter is not case sensitive, and it also handles the optional space in the middle of the postcode.
callback	string		Both	If callback is set, the JSON data will be wrapped as JSONP with the function name from the callback.
distance	object		JSON	Specify an extra location to calculate distance to
preserve_index	boolean		JSON	Specify how the results should be grouped. false: index by formatted postcode, true: keep input order and return array

Example request

function getTestData(){
    // Pass parameters via JSON
    var parameters = {
        key: "xxxxx-xxxxx-xxxxx-xxxxx",
        // supply the array of postcodes to geocode. max 25.
        postcodes: ["SW1A 2AA", "SL6 1QZ"],
        distance: {
            // supply a postcode to measure to
            "base_postcode": "aa11ae"
            /* or northing easting
            "base_ne" : {
                "northing" : 182949,
                "easting"  : 542267
            }
            */
        },
        preserve_index: 1
    };
    var url = "http://pcls1.craftyclicks.co.uk/json/geocode";
    // or via GET parameters
    // var url = "http://pcls1.craftyclicks.co.uk/json/geocode?key=xxxxx-xxxxx-xxxxx-xxxxx&postcode=aa11aa";

    request = new XMLHttpRequest();
    request.open('POST', url, false);
    // Only needed for the JSON parameter pass
    request.setRequestHeader('Content-Type', 'application/json');
    // Wait for change and then either JSON parse response text or throw exception for HTTP error
    request.onreadystatechange = function() {
        if (this.readyState === 4){
            if (this.status >= 200 && this.status < 400){
                // Success!
                data = JSON.parse(this.responseText);
            } else {
                throw 'HTTP Request Error';
            }
        }
    };
    // Send request
    request.send(JSON.stringify(parameters));
    return data;
}

// console.log(getTestData());

import urllib2
import urllib
import json

def getTestData():
    url = "https://pcls1.craftyclicks.co.uk/json/"

    url += 'basicaddress'
    params = {
        'postcode': 'SW1A 2AA',
        'key': 'xxxxx-xxxxx-xxxxx-xxxxx',
        'response': 'data_formatted'
    }

    req = urllib2.Request(url + '?' + urllib.urlencode(params))

    res = urllib2.urlopen(req)
    data = json.loads(res.read())
    return data

#print json.dumps(getTestData(), sort_keys=True, indent=4, separators=(',', ': '))

<?php
function getTestData(){
    $data = array(
        "postcodes" => ["SW1A 2AA", "SL6 1QZ"],
        "key" => "xxxxx-xxxxx-xxxxx-xxxxx",
        "distance" => [
            "base_postcode" => "aa11ae"
        ]
    );
    $data_string = json_encode($data);

    $ch = curl_init('http://pcls1.craftyclicks.co.uk/json/geocode');
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'Content-Type: application/json',
        'Content-Length: ' . strlen($data_string))
    );

    $result = curl_exec($ch);
    return $result;
}
// echo '<pre>'.getTestData().'</pre>';
?>

Response

For each postcode, the response contains the following information:

Key	Description
lat	Latitude
lng	Longitude
os	If the postcode exists in OS Code Point Open, northing and easting is available, with further Code Point Open data (adminstrative area information and NHS codes). If the data is not part of the OS dataset, only geocoding information is provided, and the location information is only an estimate. Every text value comes with an OS code, and a matching text.
distance	Distance between the postcode and the 'base postcode' in metres.

OS data

Key	Description
easting	UK grid reference numbers
northing	UK grid reference numbers
country_code	England / Wales / Scotland / Northern Ireland
country_name	England / Wales / Scotland / Northern Ireland
nhs_regional_ha_code	NHS regional health authority code
nhs_regional_ha_text	NHS regional health authority name
nhs_ha_code	NHS health authority code
nhs_ha_text	NHS health authority name
administrative_county_code	Administrative county
administrative_county_text	Administrative county
administrative_district_code	Administrative district
administrative_district_text	Administrative district
administrative_ward_code	Administrative ward
administrative_ward_text	Administrative ward

The API will respond to the request with the following structure, if preserve_index is unset or false.

{
    "SW1A2AA": {
        "lat": 51.5035,
        "lng": -0.127695,
        "os": {
            "easting": "530047",
            "northing": "179951",
            "country_code": "E92000001",
            "country_text": "England",
            "nhs_regional_ha_code": "E19000003",
            "nhs_regional_ha_text": "London Programme for IT (LPFiT)",
            "nhs_ha_code": "E18000007",
            "nhs_ha_text": "London",
            "administrative_county_code": "",
            "administrative_county_text": "",
            "administrative_district_code": "E09000033",
            "administrative_district_text": "City of Westminster London Boro",
            "administrative_ward_code": "E05000644",
            "administrative_ward_text": ""
        }
    },
    "SL61QZ": {
        "lat": 51.5233,
        "lng": -0.718984,
        "os": {
            "easting": "488971",
            "northing": "181267",
            "country_code": "E92000001",
            "country_text": "England",
            "nhs_regional_ha_code": "E19000002",
            "nhs_regional_ha_text": "Southern Programme for IT (SPFiT)",
            "nhs_ha_code": "E18000009",
            "nhs_ha_text": "South Central",
            "administrative_county_code": "",
            "administrative_county_text": "",
            "administrative_district_code": "E06000040",
            "administrative_district_text": "Windsor and Maidenhead (B)",
            "administrative_ward_code": "E05002367",
            "administrative_ward_text": "Oldfield Ward"
        }
    }
}

The API will respond to the request with the following structure, if preserve_index is true.

[
    {
        "lat": 51.5035,
        "lng": -0.127695,
        "os": {
            "easting": "530047",
            "northing": "179951",
            "country_code": "E92000001",
            "country_text": "England",
            "nhs_regional_ha_code": "E19000003",
            "nhs_regional_ha_text": "London Programme for IT (LPFiT)",
            "nhs_ha_code": "E18000007",
            "nhs_ha_text": "London",
            "administrative_county_code": "",
            "administrative_county_text": "",
            "administrative_district_code": "E09000033",
            "administrative_district_text": "City of Westminster London Boro",
            "administrative_ward_code": "E05000644",
            "administrative_ward_text": ""
        },
        "postcode": "SW1A2AA"
    },
    {
        "lat": 51.5233,
        "lng": -0.718984,
        "os": {
            "easting": "488971",
            "northing": "181267",
            "country_code": "E92000001",
            "country_text": "England",
            "nhs_regional_ha_code": "E19000002",
            "nhs_regional_ha_text": "Southern Programme for IT (SPFiT)",
            "nhs_ha_code": "E18000009",
            "nhs_ha_text": "South Central",
            "administrative_county_code": "",
            "administrative_county_text": "",
            "administrative_district_code": "E06000040",
            "administrative_district_text": "Windsor and Maidenhead (B)",
            "administrative_ward_code": "E05002367",
            "administrative_ward_text": "Oldfield Ward"
        },
        "postcode": "SL61QZ"
    }
]

In case the postcode is not part of the Code Point Open dataset, a simplified result is returned.

{
    "AA11AA": {
        "lat": 51.5132253,
        "lng": -0.0748047,
        "os": {
            "easting": 533689,
            "northing": 181123
        },
        "distance": 46922
    },
    "AA11AB": {
        "lat": 51.513362,
        "lng": -0.0891883,
        "os": {
            "easting": 532691,
            "northing": 181112
        },
        "distance": 45930
    }
}