XML API

Examples for the XML API are only available in PHP and Python.

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 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

  • Required: yes
  • Values: 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

  • Required: yes
  • Values: A UK postcode

This is the postcode for which you want to request data

response

  • Required: no
  • Values:
    • paf_compact: All address data returned
    • data_formatted: Address lines are pre-formatted
  • Default: paf_compact

This sets the format of the response from the API.

lines

  • Required: no
  • Values: 1, 2, 3
  • Default: 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:

delivery_point

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_point

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:

thoroughfares

This contains delivery_points, which contain 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

thoroughfare

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_point

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 identifier.

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

  • Required: yes

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.

  • Values: Your 20 digit code

postcode

  • Required: yes

This is the postcode for which you want to request data

  • Values: A UK postcode

response

  • Required: no

This sets the format of the response from the API.

  • Values:
    • paf_compact: All address data returned
    • data_formatted: Address lines are pre-formatted
  • Default: paf_compact

lines

  • Required: no

Only active when ‘response’ is set to data_formatted. This sets the number of address lines in the response from the API.

  • Values: 1, 2, 3
  • Default: 2

::: 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:

thoroughfare

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

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:

thoroughfare

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

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>
Last Updated: 9/4/2018, 12:45:44 PM