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

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

Key	Type	Values	Default	Description
`access_token` Required	string	Your 20 digit token		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.
`result_elem_id` Required	string	ID		This is the ID of the element that is used for displaying the results of the postcode lookup.
`form`	string	Name	Empty string	The 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_company`	string	Name or ID		Company input element
`elem_house_num`	string	Name or ID		House number input element
`elem_street1`	string	Name or ID		Address line 1 input element
`elem_street2`	string	Name or ID		Address line 2 input element
`elem_street3`	string	Name or ID		Address line 3 input element
`elem_town`	string	Name or ID		Town/city input element
`elem_county`	string	Name or ID		County/state select/input element
`elem_postcode` Required	string	Name or ID		Postcode input element. This is both an input and an output.
`traditional_county`	boolean	`0`: Former postal county, `1`: Traditional county name	`0`	This sets the type of county that will be returned.
`busy_img_url`	string	A file path		Set the location of a ‘busy’ image which is shown while waiting for the server response.
`max_width`	string	Width in pixels, e.g. `450px`		Set this if you want to limit the width of the result box (in px)
`max_lines`	integer			Set the maximum number of text lines in the result box
`hide_result`	boolean	`0`, `1`	`0`	Set whether the result box should disappear when a result is selected
`org_uppercase`	boolean	`0`: Company name has leading upper case, `1`: All in upper case	`1`	Set format of organisation that is returned
`town_uppercase`	boolean	`0`: Town has leading upper case, `1`: All in upper case (recommended by Royal Mail)	`1`	Set format of town/city that is returned
`county_uppercase`	string	`0`: County has leading upper case, `1`: All in upper case	`0`	Set format of county/state that is returned
`addr_uppercase`	string	`0`: Rest of address lines have leading upper case, `1`: All in upper case	`0`	Set format of other address lines that are returned
`delimiter`	string	Any character, e.g. `,`	`,`	Set the delimiter to use between parts of the address
`msg1`	string		`Please wait while we find the address`	Message to attach as a title to the busy image
`err_msg1`	string		`This postcode could not be found, please try again or enter your address manually`	Error message if the postcode does not exist
`err_msg2`	string		`This postcode is not valid, please try again or enter your address manually`	Error message if the postcode is not correctly formatted
`err_msg3`	string		`Unable to connect to address lookup server, please enter your address manually.`	Error message if there is a network problem
`err_msg4`	string		(err_num) + `An unexpected error occurred, please enter your address manually.`	Error message to cover any other problem
`res_autoselect`	boolean	`0`, `1`	`1`	Option to auto-select the first result as soon as the result box is shown
`res_select_on_change`	boolean	`1`: Results will be selected, `0`: User must explicitly click to select	`1`	Option to select results as the user scrolls through the results box
`first_res_line`	string	A string, e.g. `—– please select your address —–`	blank	Option to add a dummy first line to the results box
`debug_mode`	string	`0`, `1`	`0`	If debug mode is on, more descriptive error messages will be displayed.
`lookup_timeout`	integer	Time in milliseconds	`10000` (10 seconds)	Maximum time to spend waiting for lookup server response
`on_result_ready`	function			Callback function name called when result is received from the lookup server
`on_result_selected`	function			Callback function name called when the user clicks on a result
`on_error`	function			Callback function called if there is an error
`pre_populate_common_address_parts`	boolean	`0`, `1`	`0`	Option for placing all common parts of the address on the form every time the drop-down is shown
`lookup_url`	string	File path	Accesses the Fetchify web service directly	Set this option to use a data relay script
`basic_address`	boolean	`0`: Rapid/Flexi Address, `1`: BasicAddress	`0`	Set whether BasicAddress is used
`single_res_autoselect`	boolean	`0`, `1`	`1`	Option for auto-selecting a result if only one result is found
`single_res_notice`	string			If `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.

# UK Postcode Lookup

# Creating a lookup object

# Include our core library

# Instantiate the object

# Add multiple lookups

# Select form elements

# Method 1

# Method 2

# Minimum configuration

# All configuration options

# Debugging

UK Postcode Lookup

Creating a lookup object

Include our core library

Instantiate the object

Add multiple lookups

Select form elements

Method 1

Method 2

Minimum configuration

All configuration options

Debugging