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, {
  // 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.

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
`what3words`	The field should contain the what3words that the user searched for

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.

International Forms

Control how PredictiveAddress is applied for different countries

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

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`
`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`
`selectCountry`	A callback function to be invoked when a new country has been selected to search in.	`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"`
`showGeocodeSearch`	Indicates if a "Use My Location" option should be shown to allow users to find addresses local to their physical location. This option only takes effect if the user has selected a country for which accurate geocoding information is available.	`false`

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. The UDPRN value is stored in the `UniqueReference` property of the response.	`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. The UPRN value is stored in the `UniqueReference` property of the response.	`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`
`includeCountry`	Set to `true` to include ISO2 and full country name in the response	`false`
`includeAdminArea`	For UK addresses, indicates that additional administrative area details should be included in the returned `RawAddress.Location` fields. Specifically, the following fields will be included when this option is set to `true`: `County` `CountyCode` `District` `DistrictCode` `Ward` `WardCode` `Country` Note that not all these fields are available for all addresses. When this option is set, the `Country` field will be set to the name of the nation within the UK that the address is in, i.e. "England", "Scotland", "Wales" or "Northern Ireland". This overrides the `IncludeCountry` option that would otherwise set it to "United Kingdom"
`includeWhat3Words`	Set to `true` to retrieve the coordinates for the what3words the user originally entered rather than the standard coordinates for the address they select. Using this option consumes a what3words credit in addition to the standard PredictiveAddress credit	`false`

Address Formatter Options

Setting	Description	Default
`Formatter`	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.	`"DefaultFormatter"`
`UseAbbreviations`	If enabled, words such as Avenue and East will be shortened to Ave. and E respectively.	`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.