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.
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 reponsitory
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 | array[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 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 |
An optional callback function. This function is invoked when autocomplete has been successfully attached to the input element. |
| onFailedCheck | function optional |
An optional callback function. 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 |
An optional callback function. 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 |
An optional callback function. 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 |
An optional callback function. 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 |
An optional callback function. 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 |
An optional callback function. This function is invoked when the suggestion list is opened. |
| onBlur | function optional |
An optional callback function. This function is invoked when focus is removed from the address suggestion input field. |
| onClose | function optional |
An optional callback function. This function is invoked when the suggestion list is closed. |
| onFocus | function optional |
An optional callback function. This function is invoked when the focus has been moved to the address suggestion input field. |
| onInput | function optional |
An optional callback function. This function is invoked when the address input field has detected a keypress |
Available Addressing Data
By rigging just 5 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
"ward" : "" // Ward
}
More information on what these fields mean can be found here