UK Postcode Lookup

The XML API gives access to Royal Mail PAF data only (Geocoding is not available). It supports CORS.

XML is useful for implementing server side UK postcode lookup on systems where JSON is hard to use. Please also check our list of Address Finder Plugins. You might find something suitable there and save yourself some integration work.

WARNING

This API gives access to UK address data only.

If you are looking to implement an international solution, please look at our Global Address Auto-Complete API.

Full Address (RapidAddress)

RapidAddress returns full address details for every address matching the search query postcode.

HTTP(S) Request

GET http://pcls1.craftyclicks.co.uk/xml/rapidaddress

or

GET https://pcls1.craftyclicks.co.uk/xml/rapidaddress

Query Parameters

Pass parameters in GET.

Key	Type	Values	Required	Default	Description
key	string	Your 20 digit code	✔️		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.
postcode	string	A UK postcode	✔️		This is the postcode for which you want to request data.
response	string	paf_compact: All address data returned, data_formatted: Address lines are pre-formatted		paf_compact	This sets the format of the response from the API.
lines	integer	1, 2, 3		2	Only active when response is set to data_formatted. This sets the number of address lines in the response from the API.

TIP

We suggest using response=data_formatted in most cases, as it’s easier to work with. Use response=paf_compact only if you require all address parts separated out.

Example request (Python and PHP only)

import urllib2
import urllib
import xml.dom.minidom

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

    url += 'rapidaddress'
    params = {
        'postcode': 'aa11aa',
        'key': 'xxxxx-xxxxx-xxxxx-xxxxx',
        'response': 'data_formatted'
    }

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

    return xml.dom.minidom.parseString( res.read() )

xmldata = getTestData()
print xmldata.toprettyxml()

<?php
function getTestData(){
    $data = array(
        "postcode"  => "aa11aa",
        "key"       => "xxxxx-xxxxx-xxxxx-xxxxx",
        "response"  => "data_formatted"
    );

    $ch = curl_init('http://pcls1.craftyclicks.co.uk/xml/rapidaddress?key='.$data["key"].'&postcode='.$data["postcode"].'&response='.$data["response"]);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

Response: data_formatted

For each postcode, the response contains the following information:

Key	Description
delivery_points	Each delivery point contains the data for an individual address. See the table below for more details of the information the delivery point contains.
delivery_point_count	Number of delivery points
postal_county	Former postal county for this postcode
traditional_county	Traditional county for this postcode
town	Town name in uppercase (Royal Mail standard)
postcode	Formatted Postcode

delivery_points

Key	Description
organisation_name	Registered organisation at the address.
department_name	Specific department of said organisation.
line_1	Line 1 of the address
line_2	Line 2 of the address
line_3	Line 3 of the address
udprn	Royal Mail unique identifier

The API will respond to the request with the following structure.

<?xml version="1.0" encoding="UTF-8" ?>
<CraftyResponse>
    <address_data_formatted>
        <delivery_point>
            <organisation_name>THE BAKERY</organisation_name>
            <department_name></department_name>
            <line_1>1 HIGH STREET</line_1>
            <line_2>CRAFTY VALLEY</line_2>
            <udprn>12345678</udprn>
        </delivery_point>
        <delivery_point>
            <organisation_name>FILMS R US</organisation_name>
            <department_name></department_name>
            <line_1>3 HIGH STREET</line_1>
            <line_2>CRAFTY VALLEY</line_2>
            <udprn>12345679</udprn>
        </delivery_point>
        <delivery_point_count>5</delivery_point_count>
        <town>BIG CITY</town>
        <postal_county>POSTAL COUNTY</postal_county>
        <traditional_county>TRADITIONAL COUNTY</traditional_county>
        <postcode>AA1 1AA</postcode>
    </address_data_formatted>
</CraftyResponse>

Response: paf_compact

For each postcode, the response contains the following information:

Key	Description
thoroughfares	This contains delivery_points, which contains all the address details for every address matching the postcode, and thoroughfare details. See the table below for more.
thoroughfare_count	Number of thoroughfares
postal_county	Former postal county for this postcode
traditional_county	Traditional county for this postcode
town	Town name in uppercase (Royal Mail standard)
postcode	Formatted Postcode
dependent_locality	Sub-locality within town or city
double_dependent_locality	District within sub-locality

thoroughfares

This object contains the following information:

Key	Description
delivery_points	Each delivery point contains the data for an individual address. See the table below for more details of the information the delivery point contains.
delivery_point_count	Number of delivery points
dependent_thoroughfare_name	Name of the dependent thoroughfare
dependent_thoroughfare_descriptor	The dependent thoroughfare descriptor, e.g. Road, Street, Avenue
thoroughfare_name	Name of the thoroughfare
thoroughfare_descriptor	The thoroughfare descriptor, e.g. Road, Street, Avenue

delivery_points

This is an array of objects. Each object represents a delivery point and contains the following information:

Key	Description
organisation_name	Registered organisation at the address.
department_name	Specific department of said organisation.
po_box_number	PO Box number
building_number	Number of building
sub_building_name	Sub-name of building
building_name	Name of building
udprn	Royal Mail Unique Delivery Point Reference Number (UDPRN)

The API will respond to the request with the following structure.

<?xml version="1.0" encoding="UTF-8" ?>
<CraftyResponse>
    <address_data_paf_compact>
        <thoroughfare_count>1</thoroughfare_count>
        <thoroughfare>
            <delivery_point_count>5</delivery_point_count>
            <delivery_point>
                <organisation_name>THE BAKERY</organisation_name>
                <department_name></department_name>
                <po_box_number></po_box_number>
                <building_number>1</building_number>
                <sub_building_name></sub_building_name>
                <building_name></building_name>
                <udprn>12345678</udprn>
            </delivery_point>
            <delivery_point>
                <organisation_name>FILMS R US</organisation_name>
                <department_name></department_name>
                <po_box_number></po_box_number>
                <building_number>3</building_number>
                <sub_building_name></sub_building_name>
                <building_name></building_name>
                <udprn>12345679</udprn>
            </delivery_point>
            <dependent_thoroughfare_name></dependent_thoroughfare_name>
            <dependent_thoroughfare_descriptor></dependent_thoroughfare_descriptor>
            <thoroughfare_name>HIGH</thoroughfare_name>
            <thoroughfare_descriptor>STREET</thoroughfare_descriptor>
        </thoroughfare>
        <double_dependent_locality></double_dependent_locality>
        <dependent_locality>CRAFTY VALLEY</dependent_locality>
        <town>BIG CITY</town>
        <postal_county>POSTAL COUNTY</postal_county>
        <traditional_county>TRADITIONAL COUNTY</traditional_county>
        <postcode>AA1 1AA</postcode>
    </address_data_paf_compact>
</CraftyResponse>

Street Level (BasicAddress)

BasicAddress returns details of every street matching the search query postcode.

HTTP(s) Request

GET http://pcls1.craftyclicks.co.uk/xml/basicaddress

or

GET https://pcls1.craftyclicks.co.uk/xml/basicaddress

Query Parameters

Pass parameters either in GET or in JSON.

Key	Type	Values	Required	Default	Description
key	string	Your 20 digit code	✔️		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.
postcode	string	A UK postcode	✔️		This is the postcode for which you want to request data
response	string	paf_compact: All address data returned, data_formatted: Address lines are pre-formatted		paf_compact	This sets the format of the response from the API.
lines	integer	1, 2, 3		2	Only active when response is set to data_formatted. This sets the number of address lines in the response from the API.

::: info We suggest using response=data_formatted in most cases, as it’s easier to work with. Use response=paf_compact only if you require all address parts separated out. :::

Example request (Python and PHP only)

import urllib2
import urllib
import xml.dom.minidom

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

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

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

    return xml.dom.minidom.parseString( res.read() )

xmldata = getTestData()
print xmldata.toprettyxml()

<?php
function getTestData(){
    $data = array(
        "postcode"  => "aa11aa",
        "key"       => "xxxxx-xxxxx-xxxxx-xxxxx",
        "response"  => "data_formatted"
    );

    $ch = curl_init('http://pcls1.craftyclicks.co.uk/xml/basicaddress?key='.$data["key"].'&postcode='.$data["postcode"].'&response='.$data["response"]);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

Response: data_formatted

For each postcode, the response contains the following information:

Key	Description
thoroughfares	Each thoroughfare contains details for a thoroughfare matching the postcode. See the table below for more details.
thoroughfare_count	Number of thoroughfares
postal_county	Former postal county for this postcode
traditional_county	Traditional county for this postcode
town	Town name in uppercase (Royal Mail standard)
postcode	Formatted Postcode

thoroughfare

Key	Description
line_1	Line 1 of the formatted address
line_2	Line 2 of the formatted address
line_3	Line 3 of the formatted address

The API will respond to the request with the following structure.

<?xml version="1.0" encoding="UTF-8" ?>
<CraftyResponse>
    <address_data_formatted>
        <thoroughfare>
            <line_1>HIGH STREET</line_1>
            <line_2>CRAFTY VALLEY</line_2>
        </thoroughfare>
        <town>BIG CITY</town>
        <postal_county>POSTAL COUNTY</postal_county>
        <traditional_county>TRADITIONAL COUNTY</traditional_county>
        <postcode>AA1 1AA</postcode>
    </address_data_formatted>
</CraftyResponse>

Response: paf_compact

The API will respond to the request with the following structure.

For each postcode, the response contains the following information:

Key	Description
thoroughfares	Each thoroughfare contains details for a thoroughfare matching the postcode. See the table below for more details.
thoroughfare_count	Number of thoroughfares
postal_county	Former postal county for this postcode
traditional_county	Traditional county for this postcode
town	Town name in uppercase (Royal Mail standard)
postcode	Formatted Postcode
dependent_locality	Sub-locality within town or city
double_dependent_locality	District within sub-locality

thoroughfare

Key	Description
dependent_thoroughfare_name	Name of the dependent thoroughfare
dependent_thoroughfare_descriptor	The dependent thoroughfare descriptor, e.g. Road, Street, Avenue
thoroughfare_name	Name of the thoroughfare
thoroughfare_descriptor	The thoroughfare descriptor, e.g. Road, Street, Avenue

<?xml version="1.0" encoding="UTF-8" ?>
<CraftyResponse>
    <address_data_paf_compact>
        <thoroughfare_count>1</thoroughfare_count>
        <thoroughfare>
            <dependent_thoroughfare_name></dependent_thoroughfare_name>
            <dependent_thoroughfare_descriptor></dependent_thoroughfare_descriptor>
            <thoroughfare_name>HIGH</thoroughfare_name>
            <thoroughfare_descriptor>STREET</thoroughfare_descriptor>
        </thoroughfare>
        <double_dependent_locality></double_dependent_locality>
        <dependent_locality>CRAFTY VALLEY</dependent_locality>
        <town>BIG CITY</town>
        <postal_county>POSTAL COUNTY</postal_county>
        <traditional_county>TRADITIONAL COUNTY</traditional_county>
        <postcode>AA1 1AA</postcode>
    </address_data_paf_compact>
</CraftyResponse>