Address Finder API and Demo

Address Autocomplete Integration with Minimal Code

Quickly add Address Finder to any field with our open sourced autocomplete library

Demo HTML JavaScript

 1<input id="input" type="text" 
 2  placeholder="Search for an address with autocomplete" />
 3<!-- Create an input field to attach autocomplete -->
 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" />

 1IdealPostcodes.AddressFinder.setup({
 2  apiKey: 'iddqd',
 3  inputField: '#input',
 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});

Getting started

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

Links

Simple integration

You can attach Address Finder to any input field.

To get started, create an autocomplete controller instance with a configuration object.

Point this controller to the intended input field as well as the fields you wish to pipe your selected addresses to.

See Example

JavaScript
HTML

 1IdealPostcodes.AddressFinder.setup({
 2  apiKey: 'iddqd',
 3  inputField: '#input',
 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<input id="input" />
 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">

Attach multiple autocomplete instances

You can also attach multiple autocomplete instances to pre-existing address fields.

Each autocomplete instance is isolated and can be configured individually.

See Example

JavaScript
HTML

 1IdealPostcodes.AddressFinder.setup({
 2  apiKey: 'iddqd',
 3  inputField: '#first_line',
 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});
12
13IdealPostcodes.AddressFinder.setup({
14  apiKey: 'iddqd',
15  inputField: '#second_line',
16  outputFields: {
17    line_1: '#first_line',
18    line_2: '#second_line',
19    line_3: '#third_line',
20    post_town: '#post_town',
21    postcode: '#postcode'
22  }
23});

 1<input id="input" />
 2<!-- Create an input field to attach autocomplete -->
 3
 4<!-- Below are your existing input fields -->
 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">

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.

See Example

JavaScript
HTML

 1IdealPostcodes.AddressFinder.setup({
 2  apiKey: 'iddqd',
 3  inputField: '#input',
 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});

 1<input id="input" type="text">
 2
 3<!-- Let's add some new input fields below to house 
 4the additional data points -->
 5<br />
 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    
15<label>Address Line One</label>
16<input id="first_line" type="text">
17<label>Address Line Two</label>
18<input id="second_line" type="text">
19<label>Address Line Three</label>
20<input id="third_line" type="text">
21<label>Post Town</label>
22<input id="post_town" type="text">
23<label>Postcode</label>
24<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, Address Finder 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

JavaScript
HTML

 1IdealPostcodes.AddressFinder.setup({
 2  inputField: '#input',
 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
12  // Invoked if plugin loads
13  onLoaded: function () {
14    document.getElementById('message').textContent = 'Check passed! Try using our test postcode: ID1 1QD';
15  },
16  
17  // Invoked if key fails check
18  onFailedCheck: function () {
19    document.getElementById('message').textContent = 'Check failed. Please manually enter your address';
20  },
21
22  outputFields: {
23    line_1: '#first_line',
24    line_2: '#second_line',
25    line_3: '#third_line',
26    post_town: '#post_town',
27    postcode: '#postcode'
28  }
29});

 1<p id="message"></p>
 2
 3<input id="input" type="text">
 4<br />
 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 onAddressRetrieved callback.

When an address is selected and pulled from the API, combine the address fields and write it to an input field.

See Example

JavaScript
HTML

 1IdealPostcodes.AddressFinder.setup({
 2  apiKey: 'iddqd',
 3  inputField: '#input',
 4  onAddressRetrieved: 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').innerHTML = result;
14  }
15});

1<input id="input" type="text" placeholder="Search for an Address" />
2<br />
3<label>Address</label>
4<textarea id="output_field" type="text"></textarea>

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

JavaScript
HTML

 1IdealPostcodes.AddressFinder.setup({
 2  apiKey: 'iddqd',
 3  inputField: '#input',
 4  removeOrganisation: true,
 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    organisation_name: '#organisation'
12  }
13});

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

Need help?

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

Address Finder Demos

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

Address Autocomplete Integration with Minimal Code

Quickly add Address Finder to any field with our open sourced autocomplete library

Getting started

Links

Simple integration

Attach multiple autocomplete instances

Pulling in additional data

Checking the usability of your key

Write out the entire address in a single field

Omitting organisation name from address lines

Need help?