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