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
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 specify 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 specify 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 specify 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 specify 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 specify 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 info …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. |