opd-sdk

0.2.4 • Public • Published

opd-sdk

The javascript sdk for the Open Place Database API

NPM version

Install

npm install opd-sdk --save

Requiring

var opdSDK = require('opd-sdk'),
    opdClient = opdSDK.createClient();

Again, but with options

var opdSDK = require('opd-sdk'),
    opdClient = opdSDK.createClient({
      host: 'localhost:8080'
    });

Notes

  • All returned or thrown errors are standard javascript error objects created via new Error('message here')
  • This library uses the debug module (found here). To enable it, set the DEBUG environment variable to opd-sdk (DEBUG=opd-sdk)
  • To view the schemas for places and geojsons, go here.

Methods

createClient(options)

// Overwrite ALL the options. Bwahahahaha.
var opdSDK = require('opd-sdk'),
    opdClient = opdSDK.createClient({
      host: 'http://localhost:8080/api',
      username: 'nananananananananananananananana',
      password: 'BATMAAAN'
    });
  • host: The base url to use for the requests. Make sure to include the port if you are running locally. Default: http://www.openplacedatabase.com/api/

  • username: The username to use for authentication. Only required for deletePlace(s) and savePlace(s). Default: null

  • password: The password to use for authentication. Only required for deletePlace(s) and savePlace(s). Default: null

validate

Validate OPD data via the opd-validate library. Read it's docs for more information.

var opdSDK = require('opd-sdk');
 
try {
  opdSDK.validate.place(placeObj);
  opdSDK.validate.geojson(geojson);
} catch(e) {
  // Validation failed
}

Client Methods

searchPlaces(query, [options], callback(error, data))

Find some historical places. Booyah. Note that options is optional.

var options = {
  count: 42, // Must be between 1 and 100, default 10
  offset: 76 // Must be an integer > 0, default 0
};
 
opdClient.searchPlaces("Essex County, England", options, function(error, data) {
  if(error) {
    // Whoops.
    console.error(error);
  } else {
    // data is an object with 2 keys, results and total
    console.log('We found this many results:',data.total);
    for(var x in data.results) {
      var place = data.results[x];
    }
  }
});

get(id, callback(error, data))

Get a place or geojson.

opdClient.get("<place id>", function(error, data) {
  if(error) {
    // Whoops.
    console.error(error);
  } else {
    // data is the place object. Mmmm, tasty.
    doAwesomeStuff(data);
  }
});

getMulti(ids, callback(error, data))

Get several places or geojson.

var stuffIWant = ["<place1>","<place2>","<geojsonId>"];
 
opdClient.getMulti(stuffIWant, function(response) {
  // Response will be an object with keys matching
  // the requested ids. The values will be {error, data}
  // objects.
  for(var id in data) {
    // The error property will either be
    // an Error objects or null
    if(data[id].error){
      handleError(id, data[id].error);
    } else {
      doStuff(id, data[id].data);
    }
  }
});

save(id, place, callback(error))

Save a place or geojson

opdClient.save("<id>", data, function(error) {
  if(error) {
    // Whoops.
    console.error(error);
  } else {
    // Save successful. Time for pie.
  }
});

saveMulti(places, callback(error, data))

Save multiple places or geojsons at once

var dataToSave = {
  '<place1>': placeOneObject,
  '<place2>': placeTwoObject,
  '<geojsonid1>': geojsonObject
};
 
opdClient.saveMulti(dataToSave, function(response) {
  // Response will be an object with keys matching
  // the requested ids. The values will be {error, data}
  // objects.
  for(var id in data) {
    // The error property will either be
    // an Error objects or null
    if(data[id].error){
      // Save failed
    } else {
      // Save successfull
    }
  }
});

delete(id, callback(error))

Delete a place

opdClient.delete("<placeId>", function(error) {
  if(error) {
    // Whoops, that didn't go as planned.
    console.error(error);
  } else {
    // The place is no more. :(
  }
});

deleteMulti(places, callback(error))

Delete multiple places or geojsons

var places = [
  '<place1>',
  '<place2>'
];
 
opdClient.deleteMulti(places, function(error, data) {
  // Response will be an object with keys matching
  // the requested ids. The values will be {error, data}
  // objects.
  for(var id in data) {
    // The error property will either be
    // an Error objects or null
    if(data[id].error){
      // Delete failed
    } else {
      // Delete successfull
    }
  }
});

getChanges(from, to, callback(error, data))

Get changes for a given time range.

// Only get places that have changed  since our last sync time
var from = getLastSyncTime();
// Yup, timestamp magic. Oh yeah.
var to = Date.now();
 
opdClient.getChanges(from, to, function(error, data) {
  if(error) {
    // Whoops.
    console.error(error);
  } else {
    // data is an object where the keys are ids and the values are places
    for(var id in data) {
      var place = data[id];
      consumeMoarPlaces(place);
    }
  }
});

Readme

Keywords

none

Package Sidebar

Install

npm i opd-sdk

Weekly Downloads

0

Version

0.2.4

License

MIT

Last publish

Collaborators

  • openplacedatabase