Documentation

Address Autocomplete

BrowserStack Status Build Status npm version gzip file size 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


Build Info

Build Status npm version gzip file size 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

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