UK Postcode Lookup

Our JavaScript library provides a convenient API for client-side UK postcode lookup integration into any HTML page.

It is used in most of our Address Finder Pluginsopen in new window. It’s the quickest way to add postcode lookup to your website without having to write much code.

Download the latest version of the JavaScript library from Githubopen in new window

NOTE : This code gives access to UK address data only.

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

Creating a lookup object

Include our core library

Link to JavaScript library file (you will need to change src property to your own file path)

    <script src="crafty_postcode.class.js"></script>

Downloadopen in new window a copy of our javascript library and upload crafty_postcode.class.js your server. Include it in your HTML page.

Instantiate the object

Instantiate the object

<script>
    var cp_obj = CraftyPostcodeCreate();
    cp_obj.set("access_token", "xxxxx-xxxxx-xxxxx-xxxxx"); // your token here

    cp_obj.set("option_1", "value_1");
    ...
    cp_obj.set("option_n", "value_n");
</script>

Instantiate an object and set the config (for detail on all the options, see lower down this page).

Add multiple lookups

If you want to use address lookup more than once on a page, you can create multiple objects. Each object can be used independently of the others.

Add multiple lookups

<script>
    var cp_obj_1 = CraftyPostcodeCreate();
    ...
    var cp_obj_n = CraftyPostcodeCreate();
</script>

Select form elements

There are two methods to tell the object where to find the address form fields:

Method 1

Attach unique IDs to all the fields. Leave the “form” config blank.

Method 2

Tell the script the name of the form and the names of the fields.

Method 1

<script>
    cp_obj.set("form", ""); //blank!
    cp_obj.set("elem_company", "companyname_id"); // input field ID
    cp_obj.set("elem_street1", "address1_id"); // input field ID
    //... etc ...
</script>

Method 2

<script>
    cp_obj.set("form", "XYZ"); //form name
    cp_obj.set("elem_company", "companyname"); // input field name
    cp_obj.set("elem_street1", "address1"); // input field name
    //... etc ...
</script>

Minimum configuration

Here you can find a simple, minimum configuration of our library.

Minimum configuration

<script>
    var cp_obj = CraftyPostcodeCreate();
    cp_obj.set("access_token", "xxxxx-xxxxx-xxxxx-xxxxx"); // your token here
    cp_obj.set("form", "");
    cp_obj.set("elem_company", "");
    cp_obj.set("elem_street1", "address1");
    cp_obj.set("elem_street2", "");
    cp_obj.set("elem_street3", "");
    cp_obj.set("elem_town", "town");
    cp_obj.set("elem_county", "");
    cp_obj.set("elem_postcode", "postcode");
    cp_obj.set("elem_house_num", "");
</script>

All configuration options

KeyTypeValuesDefaultDescription
access_token RequiredstringYour 20 digit tokenUsing 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.
result_elem_id RequiredstringIDThis is the ID of the element that is used for displaying the results of the postcode lookup.
formstringNameEmpty stringThe name of the address form to be used (names will be used to find elements). If left blank, IDs will be used to find form elements.
elem_companystringName or IDCompany input element
elem_house_numstringName or IDHouse number input element
elem_street1stringName or IDAddress line 1 input element
elem_street2stringName or IDAddress line 2 input element
elem_street3stringName or IDAddress line 3 input element
elem_townstringName or IDTown/city input element
elem_countystringName or IDCounty/state select/input element
elem_postcode RequiredstringName or IDPostcode input element. This is both an input and an output.
traditional_countyboolean0: Former postal county, 1: Traditional county name0This sets the type of county that will be returned.
busy_img_urlstringA file pathSet the location of a ‘busy’ image which is shown while waiting for the server response.
max_widthstringWidth in pixels, e.g. 450pxSet this if you want to limit the width of the result box (in px)
max_linesintegerSet the maximum number of text lines in the result box
hide_resultboolean0, 10Set whether the result box should disappear when a result is selected
org_uppercaseboolean0: Company name has leading upper case, 1: All in upper case1Set format of organisation that is returned
town_uppercaseboolean0: Town has leading upper case, 1: All in upper case (recommended by Royal Mail)1Set format of town/city that is returned
county_uppercasestring0: County has leading upper case, 1: All in upper case0Set format of county/state that is returned
addr_uppercasestring0: Rest of address lines have leading upper case, 1: All in upper case0Set format of other address lines that are returned
delimiterstringAny character, e.g. ,,Set the delimiter to use between parts of the address
msg1stringPlease wait while we find the addressMessage to attach as a title to the busy image
err_msg1stringThis postcode could not be found, please try again or enter your address manuallyError message if the postcode does not exist
err_msg2stringThis postcode is not valid, please try again or enter your address manuallyError message if the postcode is not correctly formatted
err_msg3stringUnable to connect to address lookup server, please enter your address manually.Error message if there is a network problem
err_msg4string(err_num) + An unexpected error occurred, please enter your address manually.Error message to cover any other problem
res_autoselectboolean0, 11Option to auto-select the first result as soon as the result box is shown
res_select_on_changeboolean1: Results will be selected, 0: User must explicitly click to select1Option to select results as the user scrolls through the results box
first_res_linestringA string, e.g. —– please select your address —–blankOption to add a dummy first line to the results box
debug_modestring0, 10If debug mode is on, more descriptive error messages will be displayed.
lookup_timeoutintegerTime in milliseconds10000 (10 seconds)Maximum time to spend waiting for lookup server response
on_result_readyfunctionCallback function name called when result is received from the lookup server
on_result_selectedfunctionCallback function name called when the user clicks on a result
on_errorfunctionCallback function called if there is an error
pre_populate_common_address_partsboolean0, 10Option for placing all common parts of the address on the form every time the drop-down is shown
lookup_urlstringFile pathAccesses the Fetchify web service directlySet this option to use a data relay script
basic_addressboolean0: Rapid/Flexi Address, 1: BasicAddress0Set whether BasicAddress is used
single_res_autoselectboolean0, 11Option for auto-selecting a result if only one result is found
single_res_noticestringIf single_res_autoselect = 1 and there is only a single result, this message will be shown

Example of configuration using all available options

<script>
    var cp_obj = CraftyPostcodeCreate();
    cp_obj.set("access_token", "xxxxx-xxxxx-xxxxx-xxxxx"); // Your access token
    cp_obj.set("result_elem_id", "crafty_postcode_result_display");
    cp_obj.set("form", ""); // Use IDs to find the form elements
    cp_obj.set("elem_company", "");
    cp_obj.set("elem_street1", "address1"); // ID of address line 1 element
    cp_obj.set("elem_street2", "");
    cp_obj.set("elem_street3", "");
    cp_obj.set("elem_town", "town");
    cp_obj.set("elem_county", "");
    cp_obj.set("elem_postcode", "postcode");
    cp_obj.set("elem_house_num", "");
    cp_obj.set("traditional_county", 1);
    cp_obj.set("busy_img_url", file); // Set a custom busy image
    cp_obj.set("max_width", "500px"); // Set width of result box to 500px
    cp_obj.set("max_lines", 5); // Set max no of lines in result box to 5
    cp_obj.set("hide_result", 1); // Set result box to disappear when result selected
    cp_obj.set("org_uppercase", 0); // Return company name in leading upper case
    cp_obj.set("town_uppercase", 1); // Return town in upper case
    cp_obj.set("county_uppercase", 0); // Return county in leading upper case
    cp_obj.set("addr_uppercase", 0); // Return rest of address in leading upper case
    cp_obj.set("delimiter", ","); // Set delimiter to comma
    cp_obj.set("msg1", "Please wait while we find the address"); // Set busy image title
    // Set error messages
    cp_obj.set("err_msg1", "This postcode could not be found");
    cp_obj.set("err_msg2", "This postcode is not valid");
    cp_obj.set("err_msg3", "Unable to connect to server");
    cp_obj.set("err_msg4", "An unexpected error occurred");
    cp_obj.set("res_autoselect", 1); // Auto-select the first result
    cp_obj.set("res_select_on_change", 1); // Select results as user scrolls through box
    cp_obj.set("first_res_line", "—– please select your address —–"); // Adds a dummy first line
    cp_obj.set("debug_mode", 1); // Debug mode on
    cp_obj.set("lookup_timeout", 10000); // Timeout after 10 seconds
    cp_obj.set("on_result_ready", function(){
    // Do something when result received from server
    });
    cp_obj.set("on_result_selected", function(){
    // Do something when result selected by user
    });
    cp_obj.set("on_error", function(){
    // Do something when an error occurs
    });
    cp_obj.set("pre_populate_common_address_parts", 1); // Place common parts of address on form
    cp_obj.set("lookup_url", file);  // Use data relay script
    cp_obj.set("basic_address", 0); // Use RapidAddress
    cp_obj.set("single_res_autoselect", 1); // Auto-select a single result
    cp_obj.set("single_res_notice", "Search result auto-selected"); // Display on auto-select
</script>

Debugging

If things don’t work right away, set the object into debug mode and see if the error messages give any clues:

Setting debug mode

<script>
    cp_obj.set("debug_mode",   "1");
</script>

If you still have no luck – email any error codes/messages to us at support@fetchify.com. We will be happy to help.