Data8 Logo

PredictiveAddress

Quickly add auto-complete functionality to the address entry forms on your website.

Basics

Our JavaScript library provides all the standard code you need to add PredictiveAddress to your website.

Add our library to your website with two lines of code:

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

Once you've included our library you can set it to work on your address fields using the data8.predictiveaddressui object:

var txt = document.getElementById('address1');
new data8.predictiveaddressui(txt, {
  // If using an API Key, change this to your own API Key
  ajaxKey: 'your-api-key',
  // OR if using a JWT Token, change this to the JWT token being used for the session.
  jwt: 'jwt-token',
  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' }
  ]
});

This adds the PredictiveAddress tool to the address1 element, and puts the selected address into the elements address1, address2, address3, city, county and postcode

To use the sample code you'll need to get your own API Key from your dashboard.

Example

Try PredictiveAddress yourself in our form below.

Configuration

Get started with the most common configuration settings

There are two main parts to the configuration of this script - the ajaxKey setting defines the Data8 account to use, and the fields setting contains the list of elements in your form that should contain the address.

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. The element should be set to the ID or name of the HTML element, and the field should be set to one of the following values:

Field Meaning
organisation The field should contain the company name, where available
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 name or code

If you are using the fields option to populate your form you must specify an element for at least the line 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.

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.

Auto-Complete Replacement

Provide a bespoke user interface for the auto-complete element of PredictiveAddress.

Auto-Complete Styling

Control the display of the PredictiveAddress autocomplete control

International Forms

Control how PredictiveAddress is applied for different countries.
Advanced Options

There are many more options to get finer control over how PredictiveAddress works

The full list of settings that can be supplied to the data8.predictiveaddressui object is shown below.

General Options

Setting Description Default
ajaxKey Your Data8 API Key - get this from your dashboard null
jwt Alternatively to the the API Key, you can use a JWT token for the session. See the JWT Tokens page for more details of how to obtain and manage tokens. null
showResults A callback function to be invoked when a new set of results are ready to be shown in the autocomplete list. See the Auto-Complete Replacement page for more information null
minDelay The time, in milliseconds, between the user pressing a key and the search results being updated 100
placeholder The watermark text to show in the input text box when it is blank ""

Country-related Options

Setting Description Default
initialCountry The country that the PredictiveAddress control should search in by default. Use "auto" to select based on the user's location, or enter the ISO2 code of your chosen country, e.g. "GB" "auto"
fallbackCountry The ISO2 code of the country to use by default if initialCountry is set to "auto" but the automatic country detection does not indicate a currently supported country "GB"
allowedCountries An array of ISO2 country codes that the user is allowed to select from, e.g. [ "GB", "US" ] to limit the user to UK and US addresses. Leave this set to null to allow the user to select from all the supported countries null
barredCountries An array of ISO2 country codes that the user is not allowed to select from, e.g. [ "RU", "CN" ] to allow the user to select any country other than Russia or China. Leave this set to null to not block any countries null
preferredLanguage The ISO language code to retrieve addresses in, where available. For example, set to "cy" to get Welsh addresses in Welsh. "en"

See the International Forms page for more examples on these options.

Address Retrieval Options

Setting Description Default
countryFieldFormat Set to "ISO2" or "Name" to specify whether the country code or name should be used when populating an address "ISO2"
fields An array of { element: 'id', field: 'name' } pairs as described in the Configuration section above that is used to populate an address form using the selected address null
selectAddress A callback function to be invoked when the user selects an address from the list. The function is called with the selected address and country as two arguments, and can then do whatever logic is necessary to use that data on your form. Both the selectAddress and fields options can be used - the address form is populated according to the rules in the fields option first, then the selectAddress method is called afterwards null
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 6
fixTownCounty Set to true to ensure the last two lines of the formatted address are used to hold the town and county information, or false otherwise. If you use the fields option this is worked out automatically false
fixPostcode Set to 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 false
separateOrganisation Set to 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 false
maxLineLength The maximum number of characters per line in the formatted address 255
unwantedPunctuation A string containing any characters that should be excluded from the formatted address ""
includeUdprn Set to true to include the UDPRN for any UK addresses false
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 false
includeNYB Set to true to include addresses from the Not Yet Built database (requires additional licensing) false
includeMR Set to true to include addresses from the Multiple Residency database (requires additional licensing) false

Address Retrieval Options

Setting Description Default
Formatter If enabled, words such as Avenue and East will be shortened to Ave. and E respectively. "DefaultFormatter"
UseAbbreviations This option can be set to the name of a pre-defined formatting type that controls how the address is formatted. The following values are allowed:
  • DefaultFormatter - This is the standard formatting type as described above.
  • NoOrganisationFormatter - This works in the same way as the DefaultFormatter, but omits any organisation or departmental information from the address.
  • PAFStandardFormatter - This produces an address in the standard format recommended by the Royal Mail for printing addresses on envelopes. It produces a FormattedAddress containing however many lines are necessary to hold the information stored in each particular address, and does not use any county information.
    • ​​
 false
Methods

The following methods are available on the data8.predictiveaddressui object to allow your code to interact with it:

isGeocodingSupported()

Returns a boolean value indicating if searching for addresses based on the user's physical location is supported for the country that is currently selected. Use this in conjunction with the selectCountry callback method to enable or disable a custom user interface that uses the searchByLocation() method to trigger a search.

searchByLocation()

This method triggers a search for addresses based on the user's current location. This allows you to build your own custom user interface for invoking a search by location instead of using the showGeocodeSearch option.

destroy()

This method removes the user interface elements added by the control to return the form to a simple text box.

An error has occurred. This application may no longer respond until reloaded. Reload 🗙