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)
  • 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 some 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 
//          ...and so on...
//      }, ...

Search for an address (docs)

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

idealPostcodes.lookupAddress(searchQuery, callback)
  • searchQuery (string | 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

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