unlockplaces-node

About

A node.js module to make interfacing with the Unlock Places API by EDINA easy. The API documentation is available here.

Install

Install as a standard npm module.

  $ npm install unlock-places

Usage

The most straight forward use case is to require the module and simply call methods that are exposed by the API as explained in the docs.

Each request to the API will by default use the 'unlock' gazetteer and 'json' as the format option. These can be overridden by using setResponseFormat, setGazetteer, setDefaults or by creating a new Unlock object and providing defaults to the constructor.

  var unlock = require('unlock-places');

  // Do a loaction search
  unlock.search({
    name: 'dublin',
    country: 'ireland'
  }, function(err, res) {
    // Assuming we're using json as format
    res = JSON.parse(res);
  });

An alternative use case might be to create multiple Unlock Places objects and use them for different purposes. This will allow you to apply defualts to each request without applying them as defaults to the originally required Unlock Places object.

  var unlock = require('unlock-places');

  // Each request using this object will include the 'country' parameter
  var useIreland = new unlock.Class({
    country: 'ireland'
  });

  // Do a search for places named 'Dublin' in ireland and use the 'os' gazetteer
  useIreland.search({
    name: 'dublin',
    gazetteer: 'os'
  }, function(err, res) {
    // Assuming we're using json as format
    res = JSON.parse(res);
  });

Documentation

• setResponseFormat
• getResponseFormat
• setGazetteer
• getGazetteer
• setDefaults
• getDefaults
• search
• footprintLookup
• featureLookup
• closestMatchSearch
• supportedFeatureTypes

Set the default response format for each API request. Can be 'json', 'xml', 'kml' or 'txt'.

Returns the default response format to use.

Set the default gazetteer for each API request. Can be 'unlock', 'os' or 'naturalearth'

Returns the default gazetteer to use for each request.

Set default parameters to add to each request. For example:

  var places = require('unlock-places');

  // All of these are optional. Old defaults will be erased.
  places.setDefaults({
    format: 'xml',
    name: 'london',
    gazetteer: 'naturalearth'
  });

Return the defaults being used in each request.

Run a locations search against the API. Params is an object that contains any items to add to the request querystring. Any params included that conflict those in defaults will override the default setting.

  var places = require('unlock-places');

  // All of these are optional. Old defaults will be erased.
  places.setDefaults({
    format: 'xml',
    name: 'london',
    gazetteer: 'naturalearth'
  });

  // Do a request but override the xml response format default.
  places.search({
    name: 'paris',
    format: 'txt'
  });

Run a footprintLookup against the API. The params object must contain an 'id' parameter.

Run a featureLookup against the API. The params object must contain an 'id' parameter.

Run a search against the API and returns a single result only.

Returns the supported feature types for the given params.