jQuery Plugin

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

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 drop down 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.

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 and 2.1.

---

Getting Started

1) Download the plugin and add to your page

<script src="jquery.postcodes.min.js"></script>

2) Sign up to get an API key

3) 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)

<div id="postcode_lookup_field"></div>
<script>
$('#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'
    }
});
</script>

---

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 addresss 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" : "",                     // Administrative County
    "district" : "",                   // Administrative District
    "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.

---

Advanced Usage

$.idealPostcodes.lookupPostcode(postcode, api_key, success[, error])

Performs a postcode lookup on the Ideal Postcodes API

Function Arguments

Example

var API_KEY = 'iddqd';

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

---

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().