Open Nav

Postcode Lookup Integration Examples


Integrate or adapt our HTML & JavaScript snippets below to get started in moments

Integrate quickly and with confidence


Implement postcode search that works across browsers by leveraging our Postcode Lookup library

Demo HTML JavaScript 
 1<!-- Add a div to house your 
 2     postcode input field -->
 3<div id="lookup_field"></div>
 4
 5<!-- This is your existing form -->
 6<label>Address Line One</label>
 7<input id="first_line" type="text" />
 8
 9<label>Address Line Two</label>
10<input id="second_line" type="text" />
11
12<label>Address Line Three</label>
13<input id="third_line" type="text" />
14
15<label>Post Town</label>
16<input id="post_town" type="text" />
17
18<label>Postcode</label>
19<input id="postcode" type="text" />
 1<script>
 2// Add this after your form
 3IdealPostcodes.PostcodeLookup.setup({
 4  // Add your API key
 5  apiKey: 'ak_htaapr1fkpQCzbA66WHfMRAIjotF5',
 6  // Identify a container for postcode lookup
 7  context: '#lookup_field',
 8  // Identify your fields with CSS selectors
 9  outputFields: {
10    line_1: '#first_line',  
11    line_2: '#second_line',         
12    line_3: '#third_line',
13    post_town: '#post_town',
14    postcode: '#postcode'
15  }
16});
17</script>

Getting started

  1. 1. Add to your project with npm or directly to your webpage with our drop-in script
  2. 2. Activate with your Key and point the plugin to your address fields
  3. 3. Customise behaviour and appearance with JavaScript and CSS

Open Sourced

GitHub

Review, track or audit the library on on GitHub

Links

Simple integration

In a typical address form, you have an existing set of address fields you wish to populate with accurate user data.

Create a <div> container to house the postcode lookup elements and identify it with context.

Your context will create input and button elements to facilitate a postcode lookup. The context will also generate a select element for address suggestions and a possible p tag for error messages.

You may then use CSS to style these elements.

Add your API Key with apiKey and identifiers for your address fields with outputFields.


See Example

 1IdealPostcodes.PostcodeLookup.setup({
 2  apiKey: 'iddqd',
 3  context: "#lookup_field",
 4  outputFields: {
 5    line_1: '#first_line',  
 6    line_2: '#second_line',         
 7    line_3: '#third_line',
 8    post_town: '#post_town',
 9    postcode: '#postcode'
10  }
11});

 1<div id="lookup_field"></div> 
 2<!-- The above empty div tag will allow the 
 3  plugin to create the lookup fields -->
 4
 5<!-- Below are your existing input fields -->
 6<label>Address Line One</label> 
 7<input id="first_line" type="text">
 8
 9<label>Address Line Two</label>
10<input id="second_line" type="text">
11
12<label>Address Line Three</label>
13<input id="third_line" type="text">
14
15<label>Post Town</label>
16<input id="post_town" type="text">
17
18<label>Postcode</label>
19<input id="postcode" type="text">

Using a user interface

You may have a specific postcode lookup user interface in mind and don't wish to rely on just specifying a context to generate Postcode Lookup elements and CSS to style those elements.

In these instances, you can create your UI with HTML and tell Postcode Lookup to use your elements to drive the address search process.

For example, you can create a postcode lookup interface with Bootstrap and tell Postcode Lookup which elements should form the postcode input field and search button with input and button elements respectively.

This will also prevent the context from generating its own input and button elements, leaving the context with just the address select element and alerts. So in this example, the context will also serve as its own Bootstrap form-group.

The result is a Postcode Lookup which is more closely tailored to your specific framework and user interface goals.


See Example

 1IdealPostcodes.PostcodeLookup.setup({
 2  apiKey: 'iddqd',
 3  context: '#lookup_field',
 4  button: '#button',
 5  input: '#input',
 6  selectClass: 'form-control',
 7  outputFields: {
 8    line_1: '#first_line',
 9    line_2: '#second_line',
10    line_3: '#third_line',
11    post_town: '#post_town',
12    postcode: '#postcode'
13  }
14});

 1<div class="container mt-3">
 2  <div class="row">
 3    <div class="col-md-4">
 4      <form>
 5        <!-- Put together your own postcode lookup UI -->
 6        <div class="form-group">
 7          <label for="input">Search your Postcode</label>
 8          <input class="form-control" type="text" id="input">
 9          <button id="button" class="btn btn-dark mt-3">
10            Lookup Address
11          </button>
12        </div>
13        <!-- The context will now only return the address dropdown and notifications -->
14        <div id="lookup_field" class="form-group"></div>
15        <div class="form-group">
16          <label for="first_line">Address Line One</label>
17          <input type="text" class="form-control" id="first_line">
18        </div>
19        <div class="form-group">
20          <label for="second_line">Address Line Two</label>
21          <input type="text" class="form-control" id="second_line">
22        </div>
23        <div class="form-group">
24          <label for="third_line">Address Line Three</label>
25          <input type="text" class="form-control" id="third_line">
26        </div>
27        <div class="form-group">
28          <label for="post_town">Post Town</label>
29          <input type="text" class="form-control" id="post_town">
30        </div>
31        <div class="form-group">
32          <label for="postcode">Postcode</label>
33          <input type="text" class="form-control" id="postcode">
34        </div>
35      </form>
36    </div>
37  </div>
38</div>

Pulling in additional data

We can also pull in more data from the Postcode Address File by passing more arguments into the outputFields object.

In this instance, we pull location, organisation name (if any) and the Unique Delivery Point Reference Number.

You can access the full list of available datapoints.

Try a postcode with lots of local businesses like NW1 0BG.


See Example

 1IdealPostcodes.PostcodeLookup.setup({
 2  apiKey: 'iddqd',
 3  context: "#lookup_field",
 4  outputFields: {
 5    line_1: '#first_line',
 6    line_2: '#second_line',
 7    line_3: '#third_line',
 8    post_town: '#post_town',
 9    postcode: '#postcode',
10    organisation_name: '#organisation_name',
11    longitude: '#longitude',
12    latitude: '#latitude',
13    udprn: '#udprn'
14  }
15});
16
17// Note the new properties passed into output_fields along with their associated CSS selectors

 1<div id="lookup_field"></div>
 2
 3<!-- Let's add some new input fields below to house
 4  the additional data points -->
 5
 6<label>Organisation Name</label>
 7<input id="organisation_name" type="text">
 8<label>Longitude</label>
 9<input id="longitude" type="text">
10<label>Latitude</label>
11<input id="latitude" type="text">
12<label>Unique Delivery Point Reference Number</label>
13<input id="udprn" type="text">
14<label>Unique Property Reference Number</label>
15<input id="uprn" type="text">
16
17
18<label>Address Line One</label>
19<input id="first_line" type="text">
20<label>Address Line Two</label>
21<input id="second_line" type="text">
22<label>Address Line Three</label>
23<input id="third_line" type="text">
24<label>Post Town</label>
25<input id="post_town" type="text">
26<label>Postcode</label>
27<input id="postcode" type="text">

Styling with CSS & classes

The input field and buttons can be styled by declaring classes in the configuration object.

In this example the input and button classes have been set to my-input-class and my-button-class and styled using CSS.


See Example

 1IdealPostcodes.PostcodeLookup.setup({
 2  apiKey: 'iddqd',
 3  context: '#lookup_field',
 4  outputFields: {
 5    line_1: '#first_line',
 6    line_2: '#second_line',
 7    line_3: '#third_line',
 8    post_town: '#post_town',
 9    postcode: '#postcode'
10  },
11  buttonClass: 'my-button-class',
12  inputClass: 'my-input-class'
13});

 1<div id="lookup_field"></div>
 2
 3<label>Address Line One</label>
 4<input id="first_line" type="text">
 5
 6<label>Address Line Two</label>
 7<input id="second_line" type="text">
 8
 9<label>Address Line Three</label>
10<input id="third_line" type="text">
11
12<label>Post Town</label>
13<input id="post_town" type="text">
14
15<label>Postcode</label>
16<input id="postcode" type="text">

Adding multiple lookups on a page

You can create multiple, independent Postcode Lookup fields on the same page. This is useful for certain requirements, e.g. separate billing and shipping addresses.

PostcodeLookup.setup() can be invoked multiple times on different DOM elements to create multiple fields.

Each lookup field is independent and so can behave differently if you pass in different configuration settings.


See Example

 1// Initialize each lookup field individually. You can specify completely different configurations. Each is isolated from the other.
 2
 3// Hookup the first lookup field
 4IdealPostcodes.PostcodeLookup.setup({
 5  apiKey: 'iddqd',
 6  context: '#lookup_field',
 7  outputFields: {
 8    line_1: '#first_line',  
 9    line_2: '#second_line',         
10    line_3: '#third_line',
11    post_town: '#post_town',
12    postcode: '#postcode'
13  }
14});
15
16// Hookup the second lookup field
17IdealPostcodes.PostcodeLookup.setup({
18  apiKey: 'iddqd',
19  context: '#lookup_field_2',
20  outputFields: {
21    line_1: '#first_line_2',  
22    line_2: '#second_line_2',         
23    line_3: '#third_line_2',
24    post_town: '#post_town_2',
25    postcode: '#postcode_2'
26  }
27});

 1<div class="box">
 2  <h2>Lookup Field 1</h2>
 3  <div id="lookup_field"></div> 
 4
 5  <label>Address Line One</label> 
 6  <input id="first_line" type="text">
 7
 8  <label>Address Line Two</label>
 9  <input id="second_line" type="text">
10
11  <label>Address Line Three</label>
12  <input id="third_line" type="text">
13
14  <label>Post Town</label>
15  <input id="post_town" type="text">
16
17  <label>Postcode</label>
18  <input id="postcode" type="text">
19</div>
20        
21<div class="box">
22  <h2>Lookup Field 2</h2>
23  <div id="lookup_field_2"></div>
24
25  <label>Address Line One</label> 
26  <input id="first_line_2" type="text">
27
28  <label>Address Line Two</label>
29  <input id="second_line_2" type="text">
30
31  <label>Address Line Three</label>
32  <input id="third_line_2" type="text">
33
34  <label>Post Town</label>
35  <input id="post_town_2" type="text">
36
37  <label>Postcode</label>
38  <input id="postcode_2" type="text">
39</div>

Pulling in your own input field

You may not want the plugin to create its own postcode input field. Instead, you may wish to use an existing field.

The plugin allows you to define a pre-existing element to accept inputs for your postcode lookup.

To enable this behaviour identify your custom input via the input property.


See Example

 1IdealPostcodes.PostcodeLookup.setup({
 2  apiKey: 'iddqd',
 3  context: '#lookup_field',
 4  outputFields: {
 5    line_1: '#first_line',
 6    line_2: '#second_line',
 7    line_3: '#third_line',
 8    post_town: '#post_town',
 9    postcode: '#postcode'
10  },
11  input: '#customInput'
12});

 1<!-- Below is the custom input field, we're using a textarea in this example -->
 2
 3<textarea 
 4  id="customInput" 
 5  type="text" 
 6  value="This is my custom input element"
 7>This is my custom input element. It can be an input, select or textarea element.
 8</textarea>
 9
10<div id="lookup_field"></div>
11
12<label>Address Line One</label> 
13<input id="first_line" type="text">
14
15<label>Address Line Two</label>
16<input id="second_line" type="text">
17
18<label>Address Line Three</label>
19<input id="third_line" type="text">
20
21<label>Post Town</label>
22<input id="post_town" type="text">
23
24<label>Postcode</label>
25<input id="postcode" type="text">

Applying your own button

You may also specify any clickable DOM element as a trigger to lookup a postcode.

Identify your custom input via the button property.


See Example

 1IdealPostcodes.PostcodeLookup.setup({
 2  apiKey: 'iddqd',
 3  context: '#lookup_field',
 4  outputFields: {
 5    line_1: '#first_line',  
 6    line_2: '#second_line',         
 7    line_3: '#third_line',
 8    post_town: '#post_town',
 9    postcode: '#postcode'
10  },
11  button: '#customButton'
12});
13
14// Define the button parameter with the id of your custom DOM element. This element will trigger a Postcode Lookup when clicked.

 1<div id="lookup_field"></div>
 2
 3<!-- Here we've created a link to be used as a trigger for a Postcode Lookup -->
 4
 5<h3><a href="" id="customButton">My Custom Lookup Link</a></h3>
 6
 7<label>Address Line One</label>
 8<input id="first_line" type="text">
 9
10<label>Address Line Two</label>
11<input id="second_line" type="text">
12
13<label>Address Line Three</label>
14<input id="third_line" type="text">
15
16<label>Post Town</label>
17<input id="post_town" type="text">
18
19<label>Postcode</label>
20<input id="postcode" type="text">

Omitting organisation name from address lines

If an organisation is registered at an address, clear addressing guidelines indicate that the organisation name should appear on the first line of the address (line_1).

By setting removeOrganisation to true, the plugin will remove any organisation name from address lines if it is not the only premise identifier.


See Example

 1IdealPostcodes.PostcodeLookup.setup({
 2  apiKey: 'iddqd',
 3  context: '#lookup_field',
 4  removeOrganisation: true,
 5  outputFields: {
 6    organisation_name: '#organisation',
 7    line_1: '#first_line',
 8    line_2: '#second_line',
 9    line_3: '#third_line',
10    post_town: '#post_town',
11    postcode: '#postcode'
12  }
13});

 1<div id="lookup_field"></div> 
 2
 3<label>Organisation</label> 
 4<input id="organisation" type="text">
 5
 6<label>Address Line One</label> 
 7<input id="first_line" type="text">
 8
 9<label>Address Line Two</label>
10<input id="second_line" type="text"> 
11
12<label>Address Line Three</label>
13<input id="third_line" type="text">
14
15<label>Post Town</label>
16<input id="post_town" type="text">
17
18<label>Postcode</label>
19<input id="postcode" type="text">

Checking the usability of your key

Your key may not be available at some times. For instance:

  • Your key may have reached its daily cap set by you
  • Your user has reached their individual usage cap for the day
  • The balance on your key is exhausted

By default, Postcode Lookup will not initialise if your key is not usable for whatever reason. You may use the onLoaded and onFailedCheck callbacks to make necessary adjustments.

To disable key checking, set checkKey to false.


See Example

 1IdealPostcodes.PostcodeLookup.setup({
 2  context: "#lookup_field",
 3
 4  // Test key: "iddqd" passes the check
 5  apiKey: "iddqd",
 6  // Test key: "idkfa" fails the key check
 7  // api_key: 'idkfa',
 8
 9  // By default, checkKey is enabled
10  checkKey: true,
11  // Invoked if the plugin succeeds in loading (with or without key checking)
12  onLoaded: function() {
13    document.getElementById('resultCheck').textContent = 'Try using our test postcode: ID1 1QD';
14  },
15
16  // Invoked if key checking is enabled and key fails check
17  onFailedCheck: function() {
18    document.getElementById('resultCheck').textContent = 'Please manually enter your address';
19  },
20
21  outputFields: {
22    line_1: '#first_line',
23    line_2: '#second_line',
24    line_3: '#third_line',
25    post_town: '#post_town',
26    postcode: '#postcode'
27  }
28});

 1<p id="resultCheck"></p>
 2
 3<div id="lookup_field"></div> 
 4
 5<label>Address Line One</label> 
 6<input id="first_line" type="text">
 7
 8<label>Address Line Two</label>
 9<input id="second_line" type="text"> 
10
11<label>Address Line Three</label>
12<input id="third_line" type="text">
13
14<label>Post Town</label>
15<input id="post_town" type="text">
16
17<label>Postcode</label>
18<input id="postcode" type="text">
19

Enable full address search

You can also enable a full address search, i.e. combine a postcode with house number.

Set striclyPostcodes to false.


See Example

 1IdealPostcodes.PostcodeLookup.setup({
 2  context: '#lookup_field',
 3  apiKey: 'iddqd',
 4  // Enable address search
 5  strictlyPostcodes: false,
 6  // Add a custom label
 7  placeholder: 'Search for a postcode or address',
 8  // Populate the address if a single match found
 9  selectSinglePremise: true,
10  outputFields: {
11    line_1: '#first_line',
12    line_2: '#second_line',
13    line_3: '#third_line',
14    post_town: '#post_town',
15    postcode: '#postcode'
16  }
17});

 1<div id="lookup_field"></div> 
 2
 3<label>Address Line One</label> 
 4<input id="first_line" type="text">
 5
 6<label>Address Line Two</label>
 7<input id="second_line" type="text">
 8
 9<label>Address Line Three</label>
10<input id="third_line" type="text">
11
12<label>Post Town</label>
13<input id="post_town" type="text">
14
15<label>Postcode</label>
16<input id="postcode" type="text">

Run a custom callback upon API request

By passing a function to onSearchCompleted, you can execute a custom callback.

This option is useful if you want to run custom code after the user has searched for an address and before the user selects from the dropdown menu.


See Example

 1IdealPostcodes.PostcodeLookup.setup({
 2  context: '#lookup_field',
 3  apiKey: 'iddqd',
 4  outputFields: {
 5    line_1: '#first_line',
 6    line_2: '#second_line',
 7    line_3: '#third_line',
 8    post_town: '#post_town',
 9    postcode: '#postcode'
10  },
11  onSearchCompleted: function(error, addresses) {
12    if (error) {
13      document.getElementById('successStatus').textContent = 'Some error occurred';
14    }
15
16    // Message dependent on postcode existence
17    if (addresses.length === 0) { 
18      document.getElementById('successStatus').textContent = 'Postcode does not exist';
19    } else {
20      document.getElementById('successStatus').textContent = 'Success!';
21    }
22  }
23});
24
25// onSearchCompleted is invoked with a data object representing the JSON body of the request. You should check the code `data.code` to observe the outcome of the request. 2000 means success. 4040 means postcode does not exist. Other codes will mean an error occurred. Use the following postcodes to test:
26
27// ID11QD - Success
28// ID1KFA - No Postcode
29// ID1 CLIP - Your key is out of lookups

 1<pre id="successStatus"></pre>
 2
 3<div id="lookup_field"></div> 
 4
 5<label>Address Line One</label> 
 6<input id="first_line" type="text">
 7
 8<label>Address Line Two</label>
 9<input id="second_line" type="text">
10
11<label>Address Line Three</label>
12<input id="third_line" type="text">
13
14<label>Post Town</label>
15<input id="post_town" type="text">
16
17<label>Postcode</label>
18<input id="postcode" type="text">

Write out the entire address in a single field

Instead of writing address attributes to specific input fields, you can also write out the entire address to a general input like a textarea.

This is achieved by using the onAddressSelected callback.

Postcode Lookup provides a number of callbacks to enable custom behaviours.

See Example

 1IdealPostcodes.PostcodeLookup.setup({
 2  context: '#lookup_field',
 3  apiKey: 'iddqd',
 4  onAddressSelected: function(address) {
 5    const result = [
 6        address.line_1,
 7        address.line_2,
 8        address.line_3,
 9        address.post_town,
10        address.postcode,
11      ].filter(elem => elem !== '')
12      .join("\n");
13      document.getElementById('output_field').textContent = result;
14  }
15});

1<div id="lookup_field"></div> 
2
3<label>Address</label>
4<textarea id="output_field"></textarea>
5

Hide address fields prior to address selection

If you wish to encourage your users to perform postcode search, you can also configure the plugin to hide your address fields using the hide parameter.

The elements assigned to hide will be hidden when Postcode Lookup successfully initialises. These elements will be unhidden if an address is selected or the user opts to manually insert an address.

The onUnhide callback can be used to perform further customisation if required.

See Example

 1IdealPostcodes.PostcodeLookup.setup({
 2  apiKey: 'iddqd',
 3  context: "#lookup_field",
 4  hide: ["#address_form"],
 5  outputFields: {
 6    line_1: '#first_line',  
 7    line_2: '#second_line',         
 8    line_3: '#third_line',
 9    post_town: '#post_town',
10    postcode: '#postcode'
11  }
12});

 1<div id="lookup_field"></div>
 2<!-- The above empty div tag will allow the plugin to create the lookup fields -->
 3
 4<div id="address_form">
 5  <label>Address Line One</label>
 6  <input id="first_line" type="text">
 7
 8  <label>Address Line Two</label>
 9  <input id="second_line" type="text">
10
11  <label>Address Line Three</label>
12  <input id="third_line" type="text">
13
14  <label>Post Town</label>
15  <input id="post_town" type="text">
16
17  <label>Postcode</label>
18  <input id="postcode" type="text">
19</div>
contact us

Need help?

If you have any questions or need help debugging, come talk to us