Address Autocomplete
This library will create an autocomplete box for any input field specified and pipe the details of a selected address to address fields designated by you.
Initialisation Example
With several lines of JavaScript you can start autocompleting addresses on any input field.
const controller = new IdealPostcodes.Autocomplete.Controller({
api_key: "iddqd",
inputField: "#input",
outputFields: {
line_1: "#line_1",
line_2: "#line_2",
line_3: "#line_3",
post_town: "#post_town",
postcode: "#postcode"
}
});
Interface
As you type an address, suggestions begin to appear. You may select an address selection with the cursor, a finger tap or arrow keys. Once a suggestion is selected, the full address will be pulled from our API and your predefined address fields will be populated. You will only be charged upon the final API call for the full address and not the retrieval of address suggestions.
Additional Links
When you are finished with this guide you may find more additional resources:
- Source code is available on GitHub
- More demonstrations available at ideal-postcodes.co.uk/autocomplete
- Low level documentation available at ideal-postcodes.github.io/ideal-postcodes-autocomplete/
Build Info
Latest available on GitHub or NPM
This documentation is applicable to the latest version only
For any bugs or feature requests, please use our GitHub issue tracker
Requirements
This client library has no external dependencies
This library has been tested across a wide variety of desktop and mobile browsers. However, with regards to Internet Explorer, it is only compatible with IE9 and greater.
For IE7 and above, consider using our jQuery plugin for basic postcode lookups and address search.
Getting Started
Install
You may install it via npm with,
npm install ideal-postcodes-autocomplete --save
You may also use Bower with,
bower install ideal-postcodes-autocomplete --save
Finally you can install it manually by copying the minified build from our GitHub repository
Obtain an API Key
Sign up to get an API key
Create an autocomplete instance
Create an autocomplete instance with IdealPostcodes.Autocomplete.Controller
. Specify the input field you wish to attach autocomplete to with inputField
and specify the address output fields you wish to populate with outputFields
.
const controller = new IdealPostcodes.Autocomplete.Controller({
api_key: "iddqd",
inputField: "#input",
outputFields: {
line_1: "#line_1",
line_2: "#line_2",
line_3: "#line_3",
post_town: "#post_town",
postcode: "#postcode"
}
});
Configuration Options
General Configuration Options
Property | Type | Description |
---|---|---|
api_key |
string |
Your key to access the Ideal Postcodes API. |
licensee |
string |
Optional. Include this if you need to identify a licensee for API requests. |
tags |
string[] |
Optional. Label your requests using tags , which can be queried later. For more information see our documentation on tagging. |
tls |
boolean |
Optional. If false, forces encryption to be disabled on outbound requests. We do not recommend setting this to false. Defaults to true. |
inputField |
string |
A CSS selector that identifies which input field the autcomplete list should bind to. |
checkKey |
boolean |
Optional. An optional field to check whether the key is usable against the Ideal Postcodes API. This should be used in conjunction with the onFailedCheck callback to specify the necessary behaviour when the API Key is not in a usable state. This is false by default. |
removeOrganisation |
boolean |
Optional. An optional field to remove organisation name from address lines. Be aware that for some large organisation postcodes, the organisation name is the only identifying premise element of an address. This is false by default. |
outputFields |
object |
An object specifying where address field data points should be piped. Please find a complete list of address fields in the PAF documentation. The attribute of the document should be the same as the address attribute as found in the documentation. E.g. line_1 , post_town , postcode . You may use a CSS selector (string) or array of CSS selector strings. E.g. { line_1: "#line_1"} or { line_1: ["#line_1", "#premise"] . |
Available Callbacks
Property | Type | Description |
---|---|---|
onLoaded |
function |
Optional. This function is invoked when autocomplete has been successfully attached to the input element. |
onFailedCheck |
function |
Optional. This function is invoked when checkKey is enabled and the key is discovered to be in an unusable state (e.g. daily limit reached, no balance, etc). |
onSuggestionsRetrieved |
function |
Optional. This function is invoked immediately after address suggestions are retrieved from the API. The first argument is an array of address suggestions. |
onAddressSelected |
function |
Optional. This function is invoked immediately after the user has selected a suggestion (either by click or keypress). The first argument is an object which represents the suggestion selected. |
onAddressRetrieved |
function |
Optional. This function is invoked when the autocomplete client has retrieved a full address from the API following a user accepting a suggestion. The first argument is an object representing the address that has been retrieved. |
onSearchError |
function |
Optional. This function is invoked when an error has occurred following an attempt to retrieve an address suggestion or full address. The first argument is an error instance (i.e. inherits from Error ) representing the error which has occurred. |
onOpen |
function |
Optional. This function is invoked when the suggestion list is opened. |
onBlur |
function |
Optional. This function is invoked when focus is removed from the address suggestion input field. |
onClose |
function |
Optional. This function is invoked when the suggestion list is closed. |
onFocus |
function |
Optional. This function is invoked when the focus has been moved to the address suggestion input field. |
onInput |
function |
Optional. This function is invoked when the address input field has detected a keypress. |
Available Addressing Data
By rigging just five fields in the above example, you will have the necessary information you need (and in the correct formatting) to identify any household in the UK by mail.
However, you can extract more information on each address for your address form by passing more properties into the outputFields
object.
Here's the complete list of available data fields:
"outputFields": {
"line_1": "", // Address Line 1
"line_2": "", // Address Line 2
"line_3": "", // Address Line 3
"post_town": "", // Post Town
"postcode": "", // Postcode
"premise": "", // Premise Name
"udprn" : "", // Unique Delivery Point Reference Number
"organisation_name" : "", // Organisation Name
"department_name" : "", // Department Name
"po_box" : "", // PO Box Number
"postcode_inward" : "", // Postcode Inward Code
"postcode_outward" : "", // Postcode Outward Code
"building_number" : "", // Building Number
"building_name" : "", // Building Name
"sub_building_name" : "", // Sub Building Name
"thoroughfare" : "", // Thoroughfare
"dependant_thoroughfare" : "", // Dependant Thoroughfare
"dependant_locality" : "", // Dependant Locality
"double_dependant_locality" : "", // Double Dependant Locality
"postcode_type" : "", // Postcode Type
"su_organisation_indicator" : "", // Organisation Type
"delivery_point_suffix" : "", // Delivery Point Suffix
"longitude" : "", // Longitude
"latitude" : "", // Latitude
"northings" : "", // Northings
"eastings" : "", // Eastings
"county" : "", // Aggregated County Field
"postal_county" : "", // Postal County
"administrative_county" : "", // Administrative County
"traditional_county" : "", // Traditional County
"district" : "", // District
"country" : "", // Country
"ward" : "", // Ward
"uprn" : "" // Unique Property Reference Number
}
More information on what these fields mean can be found in our PAF documentation.