Documentation

Browser Client

BrowserStack Status Build Status npm version gzip file size file size

This library provides a core set of API's to interact with the Ideal Postcodes API on the browser.

You may accomplish the following jobs using this library:

  • Query addresses for a postcode
  • Query for an address with an address fragment
  • Autocomplete an address
  • Lookup an address by its ID
  • Check key usability

This library also provides a number of convenient features for interacting with the Ideal Postcodes API including:

  • Local caching of API requests which affect your account balance. This prevents unnecessary expense and potentially speeds up response times
  • Natively debounces certain methods, like autocomplete requests, thereby minimising unnecessary HTTP calls

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 and address lookups.

Getting Started

Install

You may install it via npm with,

npm install ideal-postcodes-core --save

You may also use Bower with,

bower install ideal-postcodes-core --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

Initialise a Client Instance

Create a client instance with IdealPostcodes.Client

const client = new IdealPostcodes.Client({
    api_key: "iddqd"
});

Configuration Options

Property Type Description
api_key string Your key to access the Ideal Postcodes API
tls boolean optional If false, forces encryption to be disabled on outbound requests. We do not recommend setting this to false. Defaults to true

Client Methods

Lookup Addresses for a Postcode

client.lookupPostcode(options, callback);

Retrieve all addresses at a given postcode

Function Arguments

Argument Type Description
options object A configuration object. Configurable attributes listed below
options.postcode string Required. Postcode to extract address list
options.filter string[] Optional. Restrict address response attributes to those listed in the filter argument. E.g. ['line_1', 'post_town', 'postcode'] will return first line, post town and postcode only of matching addresses
options.tags string[] Optional. Label your requests using tags, which can be queried later. For more information see our documentation on tagging
options.licensee string Optional. For sublicensed keys, this is where you specifiy your applicable licensee
callback function Asynchronous handler when data addresses are received. This function accepts 2 arguments. The first is error, which will be null for successful requests. The second argument is addresses, which is an array of address objects matching your query. Invalid postcodes will return an empty array.

Example

const client = new IdealPostcodes.Client({api_key: "iddqd"});

client.lookupPostcode({ 
        postcode: 'ID1 1QD', 
}, function (error, addresses) {
        if (error) {
        // Handle error
    }
        console.log(addresses[0]); 
        // prints to console: 
        // {  
        //      postcode: "ID1 1QD", 
        //      post_town: "LONDON", 
        //      line_1: "Kingsley Hall", 
        //      line_2: "Powis Road", 
        //      line_3: ""
        //      ...truncated...
        //  } 
});

Query for an address

client.lookupAddress(options, callback);

Lookup an address given a partial address string or address query

Function Arguments

Argument Type Description
options object A configuration object. Configurable attributes listed below
options.query string Required. Address string query
options.limit number Optional. Maximum number of results to return. Default is 10, maximum is 100.
options.page number Optional. Page number of result to return. Default is 0, maximum is 9999.
options.filter string[] Optional. Restrict address response attributes to those listed in the filter argument. E.g. ['line_1', 'post_town', 'postcode'] will return first line, post_town and postcode only of matching addresses
options.tags string[] Optional. Label your requests using tags, which can be queried later. For more information see our documentation on tagging
options.licensee string Optional. For sublicensed keys, this is where you specifiy your applicable licensee
options.postcode_outward string[] Optional. Restrict queryable dataset to a list of postcode outward codes. E.g. ["SW1A","SW10"]
options.post_town string[] Optional. Restrict queryable dataset to a list of post towns codes. E.g. ["london","bromley"]
callback function Asynchronous handler when query response is received. This function accepts 2 arguments. The first is error, which will be null for successful requests. The second argument is result of your query. This contains a list of address objects in result.hits as well as query metadata such as result.page, result.limit and result.total.

Example

const client = new IdealPostcodes.Client({api_key: "iddqd"});

client.lookupAddress({ 
    query: '10 High Street', 
}, function (error, result) {
    if (error) {
        // Handle error
    }
    console.log(result);
    // {
    //  "total":2401,
    //  "limit":10,
    //  "page":0,
    //  "hits":[
    //      {
    //      "postcode":"OX39 4DH",
    //      "post_town":"CHINNOR",
    //      "building_number":"10",
    //      "line_1":"10 High Street",
    //      "line_2":"",
    //      "line_3":"",
    //      "premise":"10",
    //      "longitude":-0.906458969568777,
    //      "latitude":51.7041175564189,
    //      "eastings":475664,
    //      "northings":201163,
    //      "country":"England",
    //      "traditional_county":"Oxfordshire",
    //      "administrative_county":"Oxfordshire",
    //      "postal_county":"Oxfordshire",
    //      "county":"Oxfordshire",
    //      "district":"South Oxfordshire",
    //      "ward":"Chinnor"
    //      }
    //      ...truncated...
    //  ]
    // }
});

Autocomplete an Address

client.registerAutocompleteCallback(callback);

client.autocompleteAddress(options);

The autocomplete interface for this library has been separated into two parts. Since autocomplete will typically fire off multiple HTTP requests in quick succession, this client exposes an API which allows it to automatically debounce and cache behind the scenes. The overall effect will be to reduce unneeded HTTP requests and reduce latency.

To access the internal API which invokes the autocomplete request, please see the source code

The two part autocomplete API works as follows:

Register a callback for autocomplete results with,

client.registerAutocompleteCallback(callback);

Then invoke an autocomplete query with,

client.autocompleteAddress(options);

Typically the last phase of the autocomplete process is to query for the entire address based on the suggestion selected. You can do this using the .lookupUdprn or .lookupUmprn methods.

Function Arguments

client.registerAutocompleteCallback(callback);

You may only register one callback at a time. Each call to .registerAutocompleteCallback will overwrite the previous.

Argument Type Description
callback function Asynchronous handler when query response is received. This function accepts 2 arguments. The first is error, which will be null for successful requests. The second argument is result of your autocomplete query. This contains a list of address suggestions in result.hits.
client.autocompleteAddress(options);

Upon invocation, the request will be queued and executed unless a successive invocation is called within a short span of time.

Argument Type Description
options object A configuration object. Configurable attributes listed below
options.query string Required. Autocomplete query string
options.limit number Optional. Maximum number of results to return. Default is 10, maximum is 100.
options.postcode_outward string[] Optional. Restrict queryable dataset to a list of postcode outward codes. E.g. ["SW1A","SW10"]
options.post_town string[] Optional. Restrict queryable dataset to a list of post towns codes. E.g. ["london","bromley"]

Example

const client = new IdealPostcodes.Client({api_key: "iddqd"});
let suggestions;

client.registerAutocompleteCallback(function (error, response) {
    if (error) {
        // Handle error
    }
    console.log(response);
    suggestions = response.hits;
});

client.autocompleteAddress({
    query: "10 Downing Street Lon"
});

// Printed to console via callback:
// {
//  "hits":[
//      {
//          "suggestion":"Prime Minister & First Lord Of The Treasury, 10 Downing Street, London, SW1A",
//          "urls":{
//              "udprn":"/v1/udprn/23747771"
//          },
//          "udprn":23747771
//          },
//      {
//          "suggestion":"Flat 10, Downing Court, Grenville Street, London, WC1N",
//          "urls":{
//              "udprn":"/v1/udprn/26245117"
//          },
//          "udprn":26245117
//      }
//  ]
// }

// Finally, you typically want to follow up with a .lookupUdprn request to retrieve the full address

client.lookupUdprn({
    id: suggestions[0].udprn
}, function (error, address) {
    // Handle the full address here
})

Retrieve an Address by UDPRN

client.lookupUdprn(options, callback);

Retrieve an address using its Unique Delivery Point Reference Number (UDPRN).

Function Arguments

Argument Type Description
options object A configuration object. Configurable attributes listed below
options.id number Required. UDPRN ID to query
options.filter string[] Optional. Restrict address response attributes to those listed in the filter argument. E.g. ['line_1', 'post_town', 'postcode'] will return first line, post_town and postcode only of matching addresses
options.tags string[] Optional. Label your requests using tags, which can be queried later. For more information see our documentation on tagging
options.licensee string Optional. For sublicensed keys, this is where you specifiy your applicable licensee
callback function Asynchronous handler when data addresses are received. This function accepts 2 arguments. The first is error, which will be null for successful requests. The second argument is the address object, which matches the ID provided in the query. An invalid UDPRN will return `null` as well as an error with `error.responseCode` as 4044.

Example

const client = new IdealPostcodes.Client({api_key: "iddqd"});

client.lookupUdprn({ 
    id: 0, 
}, function (error, address) {
    if (error) {
        // Handle error
    }
        console.log(address); 
        // prints to console: 
        // {  
        //      postcode: "ID1 1QD", 
        //      post_town: "LONDON", 
        //      line_1: "Kingsley Hall", 
        //      line_2: "Powis Road", 
        //      line_3: ""
        //      ...truncated...
        //  } 
});

Retrieve an Address by UMPRN

client.lookupUmprn(options, callback);

If your key has access to the additional Multiple Residence dataset, you may also retrieve an address using its Unique Multiple Residence Delivery Point Reference Number (UMPRN).

Function Arguments

Argument Type Description
options object A configuration object. Configurable attributes listed below
options.id number Required. UMPRD ID to query
options.filter string[] Optional. Restrict address response attributes to those listed in the filter argument. E.g. ['line_1', 'post_town', 'postcode'] will return first line, post_town and postcode only of matching addresses
options.tags string[] Optional. Label your requests using tags, which can be queried later. For more information see our documentation on tagging
options.licensee string Optional. For sublicensed keys, this is where you specifiy your applicable licensee
callback function Asynchronous handler when data addresses are received. This function accepts 2 arguments. The first is error, which will be null for successful requests. The second argument is the address object, which matches the ID provided in the query. An invalid UDPRN will return `null` as well as an error with `error.responseCode` as 4046.

Example

const client = new IdealPostcodes.Client({api_key: "iddqd"});

client.lookupUmprn({ 
    id: 0, 
}, function (error, address) {
    if (error) {
        // Handle error
    }
        console.log(address); 
        // prints to console: 
        // {  
        //      postcode: "ID1 1QD", 
        //      post_town: "LONDON", 
        //      line_1: "Kingsley Hall", 
        //      line_2: "Powis Road", 
        //      line_3: ""
        //      ...truncated...
        //  } 
});

Check Key Usability

client.checkKeyUsability(options, callback);

Check whether a key can be used. This test can fail if:

  • User has no lookup balance
  • Daily limit has been reached on key
  • Requesting IP has exhausted usage limit for the day
  • Current page is not authorized by key

Function Arguments

Argument Type Description
options object A configuration object. Configurable attributes listed below
options.licensee string Optional. For sublicensed keys, this is where you specifiy your applicable licensee
callback function Asynchronous handler when data addresses are received. This function accepts 2 arguments. The first is error, which will be null for successful requests. The second argument is the response object, containing an `available` property. `response.available` will be false if key is not immediately usable.

Example

const client = new IdealPostcodes.Client({api_key: "iddqd"});

client.checkKeyUsability({}, function (error, response) {
    if (error) {
        // Handle error
    }
    console.log(response); 
    // {
    //   available: true
    // }
});

Response Caching

The client will by default cache addressing data responses in client.cache. You can opt to enable, disable or clear the cache with the following methods:

const client = new IdealPostcodes.Client({api_key: "iddqd"});

// Enable the cache (default)
client.cache.enable(); 

// Disable the cache
// - All responses will not be cached
// - Any previously cached responses will not be returned by the cache.
client.cache.disable(); 

// Clears the cache by reinitialising the store
client.cache.initialiseStore();

Error Handling

Invoking asynchronous requests against the Ideal Postcodes API will return an instance of Error as the first argument of a callback or null if no unexpected response has been received.

For example,

IdealPostcodesApiError {message: "Ideal Postcodes Error: Invalid Key. For more infor…postcodes.co.uk/documentation/response-codes#4010", status: 401, responseCode: 4010}
Error Property Type Description
message string A human readable message explaining the nature of the error
responseCode number Our internal error code, which describes the nature of the error
status number The HTTP Status code of the request