Documentation

Node.js npm version Build Status

Ideal Postcodes maintains a library to perform postcode and address queries using Node.js. This guide demonstrates how to use the node module

Getting Started

Install

npm install ideal-postcodes

Configuration

Obtain the API client by passing your api key when requiring the ideal-postcodes module.

var idealPostcodes = require("ideal-postcodes")("your_key_goes_here")

Methods

Each client instance provides a number of convenience methods to allow you to get specific jobs done quickly and easily. A small number of core methods are listed below for your reference. For the full documentation, see the README on the Github repository.

Get all addresses for a postcode (docs)

This method will retrieve a complete list of addresses at a given postcode.

idealPostcodes.lookupPostcode(postcode, callback)
Argument Type Description
postcode string The postcode to search
callback function Standard callback which accepts 2 arguments: error and addresses. The latter will is an array of address objects. Postcodes which do not exist will yield an empty array.

Use the postcode ID1 1QD to test integration for free. The complete list of test postcodes is available in the documentation.

idealPostcodes.lookupPostcode("ID1 1QD", function (error, addresses) {
    if (error) {
        // Implement error handling
    } 
    console.log(addresses);     
});

//  [{
//      postcode: 'ID1 1QD',
//      post_town: 'LONDON',
//      line_1: 'Kingsley Hall',
//      line_2: 'Powis Road',
//      line_3: '', 
//      organisation_name: '',
//      building_name: 'Kingsley Hall',
//      udprn: 12345678 
//      ...truncated...
//  },

Search for an address (docs)

This will perform a search for addresses which match your search term.

idealPostcodes.lookupAddress(searchQuery, callback)
Argument Type Description
searchQuery string or object The address to search for. If string is passed, the string is used as a search term and default settings are applied (limit 10 results, return first page). If an object is provided, this object requires a query attribute pointing to your search string. It also accepts optional limit and page attributes.
callback function Standard callback which accepts 2 arguments: error and searchResults The latter will is an array of address objects.

Use the postcode "ID1 1QD" to test integration for free. The complete list of test methods is available in the documentation.

idealPostcodes.lookupAddress("ID1 1QD", function (error, searchResults) {
    if (error) {
        // Implement error handling
    } 
    console.log(searchResults);     
});

// or alternatively

idealPostcodes.lookupAddress({
    query: "ID1 1QD",   // required
    limit: 10,                  // optional
    page: 0                         // optional
}, function (error, searchResults) {
    if (error) {
        // Implement error handling
    } 
    console.log(searchResults);     
});

// {
//   "result":{
//     "total":2,
//     "limit":10,
//     "page":0,
//     "hits":[{
//       "dependant_locality" : "",
//       "postcode_type" : "L",
//       "po_box" : "",
//       "post_town" : "LONDON",
//       "delivery_point_suffix" : "1A",
//       "double_dependant_locality" : "",
//       "su_organisation_indicator" : " ",
//       "longitude" : -0.127695242183412,
//       "department_name" : "",
//       "district" : "Westminster",
//
//       continued...

Error Handling

Each convenience method adopts the standard javascript error handling method. I.e. Any error is passed as the first argument of the callback. E.g.

idealPostcodes.lookupPostcode("ID1 1QD", function (error, addresses) {
    if (error) {
        // Handle your errors here
    } 
});

Source

Listed above are only a few of the core methods to perform useful tasks on our API.

For more methods, you can refer to the README or the source on the Github repository.