PredictiveAddress
Quickly add auto-complete functionality to the address entry forms on your website.
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, { // Change this to your own API Key ajaxKey: 'your-api-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' } ] });
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.
Try PredictiveAddress yourself in our form below.
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.
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 |
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:
|
false |
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.