Address Autocomplete

gzip file size

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.

Ideal Postcodes Autocomplete Example

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

gzip file size

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

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 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
}

More information on what these fields mean can be found here

Documentation