Postcode Lookup & Address Search

The jQuery plugin is the fastest way to integrate postcode lookups on a web page. To see working examples, visit our jQuery Demo page.

Initialisation

This plugin generates an input field to receive postcode inputs from the user and a button to run address lookups via the Ideal Postcodes API. If a matching postcode is found, a dropdown menu is created and the selected address is piped into the form. If no matching postcode is found or an error occurred, the plugin will append an appropriate message.

$('#postcode_lookup_field').setupPostcodeLookup({
    api_key: 'api_key',
    output_fields: {
    line_1: '#first_line',
        line_2: '#second_line',
        line_3: '#third_line',
        post_town: '#post_town',
        postcode: '#postcode'
    }
});

Interface

The plugin provides addresses according to Royal Mail's Addressing Guidelines. This consists of 3 address lines, a Post Town and Postcode and is sufficient to uniquely identify a premise in the UK.

---

Build Info

Latest : GitHub, NPM

Tested against jQuery 1.9, 1.10, 1.11, 2.0, 2.1, 2.2, 3.0, 3.1 and 3.2

---

Latest Build

Current version is 3.0.7. This documentation is applicable to the latest version only.

Version 3.0.0 brings some backwards incompatible changes

• Reformed postcode, address search and key checking APIs
• Request tagging
• Custom error message container
• More appropriately named custom callbacks
• onLookupSuccess is now called onSearchCompleted
• Removed client side postcode validation

The documentation for version 2.2.4 can be found here

---

Getting Started

Download the plugin and add to your page with <script src="postcodes.min.js"></script>

Sign up to get an API key

Setup a Postcode Search Field by inserting an empty div tag and calling .setupPostcodeLookup(). Pass in a configuration object identifying your API Key and address fields (via CSS selectors)

$('#postcode_lookup_field').setupPostcodeLookup({
    api_key: 'your_key_goes_here',
    // Pass in CSS selectors pointing to your input fields
    output_fields: {
        line_1: '#first_line',
        line_2: '#second_line',
        line_3: '#third_line',
        post_town: '#post_town',
        postcode: '#postcode'
    }
});

---

Available Addressing Data

By rigging just 5 fields in the above example, you will have the necessary information you need (and in the correct formatting) to identify any household in the UK by mail.

However, you can extract more information on each address for your address form by passing more properties into the output_fields object.

Here's the complete list of available data fields:

"output_fields": {
    "line_1": "",                      // Address Line 1 
    "line_2": "",                      // Address Line 2
    "line_3": "",                      // Address Line 3
    "post_town": "",                   // Post Town
    "postcode": "",                    // Postcode
    "premise": "",                     // Premise Name
    "udprn" : "",                      // Unique Delivery Point Reference Number
    "organisation_name" : "",          // Organisation Name
    "department_name" : "",            // Department Name
    "po_box" : "",                     // PO Box Number
    "postcode_inward" : "",            // Postcode Inward Code
    "postcode_outward" : "",           // Postcode Outward Code
    "building_number" : "",            // Building Number
    "building_name" : "",              // Building Name
    "sub_building_name" : "",          // Sub Building Name
    "thoroughfare" : "",               // Thoroughfare
    "dependant_thoroughfare" : "",     // Dependant Thoroughfare
    "dependant_locality" : "",         // Dependant Locality
    "double_dependant_locality" : "",  // Double Dependant Locality
    "postcode_type" : "",              // Postcode Type
    "su_organisation_indicator" : "",  // Organisation Type
    "delivery_point_suffix" : "",      // Delivery Point Suffix
    "longitude" : "",                  // Longitude
    "latitude" : "",                   // Latitude
    "northings" : "",                  // Northings
    "eastings" : "",                   // Eastings
    "county" : "",                     // Aggregated County Field
    "postal_county" : "",              // Postal County
    "administrative_county" : "",      // Administrative County
    "traditional_county" : "",         // Traditional County
    "district" : "",                   // District
    "country" : "",                    // Country
    "ward" : ""                        // Ward
}

More information on what these fields mean can be found here

To add them into your form, simply include it in output_fields when initialising Ideal Postcodes. The example below demonstrates how the organisation name can be routed to the input with the id "organisation_field"

<script>
$("#myLookupField").setupPostcodeLookup({
    api_key: 'iddqd',
    output_fields: {
        line_1: '#first_line',
        line_2: '#second_line',
        line_3: '#third_line',
        post_town: '#post_town',
        postcode: '#postcode',
        organisation_name: '#organisation_field'
    }
});
</script>

---

Plugin Configuration Examples

The plugin may also be configured for closer integration on a form. Below is a non-exhaustive list of what may be done:

Pipe additional addressing data to your form like organisation name, county or geolocation

Style input elements generated by the plugin with CSS classes

Provide your own customised input or button elements

Add multiple more than one postcode lookup fields on a page

Handle cases where your key cannot be used. E.g. No balance or limit reached.

---

Other Methods

This plugin also exposes a couple of methods which you may find useful without having to invoke the plugin. These methods are listed below:

$.idealPostcodes.lookupPostcode(options, callback)

Retrieve all addresses at a given postcode

Function Arguments

Example

var API_KEY = 'iddqd';

$.idealPostcodes.lookupPostcode({ 
    postcode: 'ID11QD', 
    api_key: API_KEY 
}, function (error, addresses) {
    if (error) {
        // Handle error
    }
    console.log(addresses[0]); 
    // prints to console: 
    // {  
    //      postcode: "ID1 1QD", 
    //      post_town: "LONDON", 
    //      line_1: "Kingsley Hall", 
    //      line_2: "Powis Road", 
    //      line_3: ""
    //      ...truncated...
    //  } 
});

$.idealPostcodes.lookupAddress(options, callback)

Performs an address search on the Ideal Postcodes API using a search string

Function Arguments

Example

var API_KEY = 'iddqd';

$.idealPostcodes.lookupAddress({ 
    postcode: '10 Downing Street London', 
    api_key: API_KEY 
}, function (error, addresses) {
    if (error) {
        // Handle error
    }
    console.log(addresses[0]); 
    // prints to console: 
    // {  
    //      postcode: "SW1A 2AA", 
    //      post_town: "LONDON", 
    //      line_1: "Prime Minister & First Lord Of The Treasury", 
    //      line_2: "10 Downing Street", 
    //      line_3: ""
    //      ...truncated...
    //  } 
});

---

Available jQuery Configuration Options

Below is a list of optional parameters you can use to style or modify the postcode lookup elements generated by the plugin. Pass this in your configuration object when calling .setupPostcodeLookup().