The javascript sdk for the Open Place Database API
JavaScript
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
build
src
test
.gitignore
LICENSE
README.md
package.json

README.md

#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(response))

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 response) {
    // The error property will either be
    // an Error objects or null
    if(response[id].error){
      handleError(id, response[id].error);
    } else {
      doStuff(id, response[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(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 response) {
    // The error property will either be
    // an Error objects or null
    if(response[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(ids, callback(response))

Delete multiple places or geojsons

var ids = [
  '<place1>',
  '<place2>',
  '<geojson1>'
];

opdClient.deleteMulti(ids, function(response) {
  // Response will be an object with keys matching
  // the requested ids. The values will be {error, data}
  // objects.
  for(var id in response) {
    // The error property will either be
    // an Error objects or null
    if(response[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);
    }
  }
});