opd-sdk v0.2.4
#opd-sdk
The javascript sdk for the Open Place Database API
##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 theDEBUG
environment variable toopd-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)
andsavePlace(s)
. Default:null
password: The password to use for authentication. Only required for
deletePlace(s)
andsavePlace(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);
}
}
});