Fetchify Documentation

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

← Testing →