Browser Client

This library provides a core set of APIs 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

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 repository

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

---

Client Methods

Lookup Addresses for a Postcode

client.lookupPostcode(options, callback);

Retrieve all addresses at a given postcode

Function Arguments

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

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.

client.autocompleteAddress(options);

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

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

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

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

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 info …postcodes.co.uk/documentation/response-codes#4010", status: 401, responseCode: 4010}