JavaScript Class

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

It is used in most of our Address Finder Plugins. 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 Class from Github

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 class

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

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

Download a copy of our javascript class 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>

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

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

access_token

  • Value: 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

  • Value: ID

This is the ID of the element that is used for displaying the results of the postcode lookup.

form

  • Value: Name

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

  • Value: Name or ID

Company input element (optional)

elem_house_num

  • Value: Name or ID

House number input element (optional)

elem_street1

  • Value: Name or ID

Address line 1 input element (required)

elem_street2

  • Value: Name or ID

Address line 2 input element (optional)

elem_street3

  • Value: Name or ID

Address line 3 input element (optional)

elem_town

  • Value: Name or ID

Town/city input element (required)

elem_county

  • Value: Name or ID

County/state select/input element (optional)

elem_postcode

  • Value: Name or ID

Postcode input element (required). This is both an input and an output.

traditional_county

  • Value:
    • 0: Former postal county
    • 1: Traditional county name
  • Default: 0

This sets the type of county that will be returned.

busy_img_url

  • Value: A file path
  • Default: ‘crafty_postcode_busy.gif’

Set the location of a ‘busy’ image which is shown while waiting for the server response.

max_width

  • Value: Width in pixels, e.g. “450px”

Set this if you want to limit the width of the result box (in px)

max_lines

  • Value: An integer

Set the maximum number of text lines in the result box

hide_result

  • Value: 1, 0
  • Default: 0

Set whether the result box should disappear when a result is selected

org_uppercase

  • Value:
    • 0: Company name has leading upper case
    • 1: All in upper case
  • Default: 1

Set format of organisation that is returned

town_uppercase

  • Value:
    • 0: Town has leading upper case
    • 1: All in upper case (recommended by Royal Mail)
  • Default: 1

Set format of town/city that is returned

county_uppercase

  • Value:
    • 0: County has leading upper case
    • 1: All in upper case
  • Default: 0

Set format of county/state that is returned

addr_uppercase

  • Value:
    • 0: Rest of address lines have leading upper case
    • 1: All in upper case
  • Default: 0

Set format of other address lines that are returned

delimiter

  • Value: Any character, eg “,
  • Default: “,

Set the delimiter to use between parts of the address

msg1

  • Value: A string
  • Default: 'Please wait while we find the address’

Message to attach as a title to the busy image

err_msg1

  • Value: A string
  • Default: 'This postcode could not be found, please try again or enter your address manually’

Error message if the postcode does not exist

err_msg2

  • Value: A string
  • Default: 'This postcode is not valid, please try again or enter your address manually’

Error message if the postcode is not correctly formatted

err_msg3

  • Value: A string
  • Default: 'Unable to connect to address lookup server, please enter your address manually.’

Error message if there is a network problem

err_msg4

  • Value: A string
  • Default: (err_num) + 'An unexpected error occurred, please enter your address manually.’

Error message to cover any other problem

res_autoselect

  • Value: 1, 0
  • Default: 1

Option to auto-select the first result as soon as the result box is shown

res_select_on_change

  • Value:
    • 1: Results will be selected
    • 0: User must explicitly click to select
  • Default: 1

Option to select results as the user scrolls through the results box

first_res_line

  • Value: A string, e.g. '—– please select your address —–’
  • Default: blank

Option to add a dummy first line to the results box

debug_mode

  • Value: 1, 0
  • Default: 0

If debug mode is on, more descriptive error messages will be displayed.

lookup_timeout

  • Value: Time in milliseconds
  • Default: 10000 (10 seconds)

Maximum time to spend waiting for lookup server response

on_result_ready

  • Value: A function

Callback function name called when result is received from the lookup server

on_result_selected

  • Value: A function

Callback function name called when the user clicks on a result

on_error

  • Value: A function

Callback function called if there is an error

pre_populate_common_address_parts

  • Value: 1, 0
  • Default: 0

Option for placing all common parts of the address on the form every time the drop-down is shown

lookup_url

  • Value: File path
  • Default: Accesses the CraftyClicks web service directly

Set this option to use a data relay script

basic_address

  • Value:
    • 0: Rapid/Flexi Address
    • 1: BasicAddress
  • Default: 0

Set whether BasicAddress is used

single_res_autoselect

  • Value: 1, 0
  • Default: 1

Option for auto-selecting a result if only one result is found

single_res_notice

  • Value: A string

If single_res_autoselect = 1 and there is only a single result, this message wil 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@craftyclicks.co.uk. We will be happy to help.

Last Updated: 9/3/2018, 4:26:05 PM