0151 355 4555

PredictiveAddress

This sample demonstrates using our PredictiveAddress service to add auto-complete functionality to an address form on your website. When they select an address, the details are used to fill out the other address fields on the form.

For the sample to work, you must have first added the domain name of your website to your allowed list for your Ajax key.

The sample assumes you have a form on your website such as that shown below:

By adding the code below the "Address 1" field is immediately transformed into an auto-complete tool.

<link rel="stylesheet" href="https://webservices.data-8.co.uk/content/predictiveaddress.css" />
<script type="text/javascript" src="https://webservices.data-8.co.uk/javascript/predictiveaddress.js"></script>

<script type="text/javascript">

var txt = document.getElementById('address1');
new data8.predictiveaddressui(txt, {
	// Change this to your own Ajax key
	ajaxKey: 'your-ajax-key',
	fields: [
		{ element: 'address1', field: 'line1' },
		{ element: 'address2', field: 'line2' },
		{ element: 'address3', field: 'line3' },
		{ element: 'city', field: 'town' },
		{ element: 'county', field: 'county' },
		{ element: 'postcode', field: 'postcode' }
	]
});

</script>

You could also choose to modify your form to a more auto-complete driven style, where the only input box is a search box.

By adding the code below this is transformed into a PredictiveAddress search box:

<link rel="stylesheet" href="https://webservices.data-8.co.uk/content/predictiveaddress.css" />
<script type="text/javascript" src="https://webservices.data-8.co.uk/javascript/predictiveaddress.js"></script>

<script type="text/javascript">

var txt = document.getElementById('addresssearch');
new data8.predictiveaddressui(txt, {
	// Change this to your own Ajax key
	ajaxKey: 'your-ajax-key',
	lineCount: 6,
	selectAddress: function(address) {
		$('#selectedaddress').empty();
		$(address.Address.Lines).each(function (idx, el) {
			if (el) {
				$('#selectedaddress').append($('<div>').text(el));
			}
		});
		$('#selectedaddress').show();
		$('#addresssearch').val('');
	}
});

</script>

Configuration

There are two main parts to the configuration of this script - the list of elements in your form that should contain the various fields from the address, and the options that give the script details of the Data8 account to use when performing a lookup.

The form elements that should contain the various parts of the address are listed in the fields configuration option as { element: 'id', field: 'name' } pairs. Add one of these for each element in your form that contains part of the address with the element set to the ID or name of the HTML element and the field set to one of the following values:

  • organisation - the field should contain the company name
  • building - the field should contain the building name and/or number
  • line1 - line6 - the field should contain the corresponding line of the address
  • town - the field should contain the town name
  • county - the field should contain the county name
  • postcode - the field should contain the postcode
  • country - the field should contain the country

If you are using the fields option to populate your form you must specify an element for at least the line1 and postcode fields, and you can also include as many or as few of the other fields as you like. Otherwise you should use the selectAddress option to provide a callback method to handle the selected address.

There are a number of options that control the details of how this script works.

  • ajaxKey - your Data8 Ajax key
  • initialCountry - the country that the PredictiveAddress control should search in by default. Use "auto" to select based on the user's location
  • allowedCountries - an array of ISO2 country codes that should be allowed
  • barredCountries - an array of ISO2 country codes that are not allowed
  • fallbackCountry - the country to use if automatic country detection does not indicate a currently supported country
  • countryFieldFormat - set to "ISO2" or "Name" to specify whether the country code or name should be used when populating the address
  • selectAddress - a callback function to be invoked when the user selects an address from the list
  • lineCount - the number of lines to format the address over. If you use the fields option this is worked out automatically, but must be defined explicitly if you use the selectAddress option instead
  • fixTownCounty - true to ensure the last two lines of the formatted address are used to hold the town and county, or false otherwise. If you use the fields option this is worked out automatically
  • fixPostcode - true to ensure the postcode is placed in the last line of the formatted address, or false to place it according to the country-specific formatting rules. If you use the fields option this is worked out automatically
  • separateOrganisation - true to exclude the company name from the formatted address, or false to include it. If you use the fields option this is worked out automatically
  • maxLineLength - the maximum number of characters per line in the formatted address. Defaults to 255
  • unwantedPunctuation - a string containing any characters that should be excluded from the formatted address
  • showResults - a callback function to be invoked when a new set of results are ready to be shown in the autocomplete list
  • minDelay - the time, in milliseconds, between the user pressing a key and the search results being updated. Defaults to 100ms
  • includeUdprn - set to true to include the UDPRN for any UK addresses
  • includeUprn - set to true to include the UPRN for UK addresses. This is not available by default - speak to your account manager to enable this option. Cannot be used in conjunction with includeUdprn - only one of these options can be specified
  • placeholder - the watermark text to show in the input text box when it is blank. Defaults to ""

Getting more control

You can override many of the details of how the PredictiveAddress script works to take fine control. For full details, see the more detailed samples below.