v 3.1 (revised on 02/12/2009)

Introduction

The CraftyClicks lookup server provides an XML API to the address databse.

To make use of the API you need to sign up for an account at www.craftyclicks.co.uk. When you sign up, a free evaluation access token will be automatically generated for you to allow for any evaluation and integration work to take place. This evaluation token allows up to 5 different postcodes to be looked up each day free of charge.

Before going live, you must purchase credits by logging into MyAccount. Every time a properly formatted postcode is submitted for lookup some of your credit is used up. Please check our prices page for details.

Accessing the Lookup Server

The lookup server is accessed via HTTP, the URLs:

Parameters

Cost

Each successful request consumes some credits:

Examples

Best way to see what the response XML looks like is to simply try a few requests in your browser using your trial token.

Here is a few examples of how to format the requests. Simply replace the xxxx's with your access token.

• http://pcls1.craftyclicks.co.uk/xml/getAddressListByPostcode.php?key=xxxxx&postcode=AB119NW
• http://pcls1.craftyclicks.co.uk/xml/getAddressListByPostcode.php?key=xxxxx&postcode=AB119NW&response=data_formatted&lines=3
• http://pcls1.craftyclicks.co.uk/xml/getThoroughfareListByPostcode.php?key=xxxxx&postcode=AB119NW
  

Error Codes

Web Forms and Optional Data

The PAF database does not guarantee that all fields will be populated in a response. CraftyPostcode web service will return as much data as is contained in the PAF database for the requested postcode.

In particular, the county name should not be relied on. Royal Mail stopped maintaining county names in 2000 and they are included only for historical reasons.

In our view the best approach is to collect only address information which is necessary for addressing mail/shipments. This keeps address web  forms shorter and easier for visitors to understand. Easy to understand web forms make for happier website visitors who are more likely to become customers!

We recommend that a UK address web form contains a total of 4 or 5 fields only:

• Postcode – required.
• Town - required.
• Address line 1 – required.
• Address line 2 (and 3 if desired) – optional.

Only three fields are compulsory – postcode, town, one address line. This should be sufficient to capture all required information to address a shipment in the UK.

One or two additional address fields can be useful for rural addresses which may need a locality. These should be made optional. Forcing visitors to enter any more information is unnecessary and can be frustrating as it will only slow down the entry process.

Summary

We hope this guide was clear and that you find accessing the lookup server easy. If you have any questions, we are only an email away – support@craftyclicks.co.uk