From 25ae4e9c132d6e68ddb389808b8f22c8f43b17cd Mon Sep 17 00:00:00 2001 From: Ben Burwell Date: Mon, 14 Dec 2015 22:23:28 -0500 Subject: Begin rewrite for new OAuth API --- README.md | 164 ++++++++++++++++---------------------------------------------- 1 file changed, 42 insertions(+), 122 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 9f3048e..6ec5caa 100644 --- a/README.md +++ b/README.md @@ -1,137 +1,57 @@ Active911 for Node.js ===================== -*Note:* This package was built for an older version of the Active911 API. It will be updated for the new version in the coming weeks. - -by Ben Burwell +by Ben Burwell Installation ------------ -Installation is simple: `npm install active911`. - -You can use it in your project by adding `active911` to your dependencies and running `npm install`. Sample ping: - - var active911 = require('active911')('YOUR_APP_KEY', 'YOUR_API_KEY'); - - active911.ping(function (err) { - if (err) { - return console.log('Could not connect to Active911: ' + err); - } - - console.log('Connection to Active911 established.'); - }); - -Usage ------ - -The `active911` package provides support for the current Active911 API functions. We follow the standard Node.js pattern of `function(options, callback(error, data))`. If an error occurs, the first parameter of the callback will contain the error message. Otherwise, the first parameter will be false and the second parameter will contain the API response. - -### `ping(callback)` - -The `ping` command checks that your API and app keys are valid on the server. It takes only a callback function with a parameter for errors. - -### `getDevice(device_id, callback)` - -Returns some data about the device associated with the `device_id`. - -Example response: - - { - "response_action" : "watch", - "response_alert_id" : 4681099, - "lat" : 44.541404, - "name" : "Joseph Sullivan", - "position_accuracy" : 30, - "response_stamp" : 1371315741, - "device_id" : 2435, - "position_stamp" : 1371463606, - "device_type" : "smartphone", - "lon" : -123.364192 - } - -### `getAlert(alert_id, callback)` - -Returns data about the alert associated with the `alert_id`. - -Example response: - - { - "source" : "", - "priority" : "F3", - "cad_code" : "", - "lat" : 44.5379997, - "place" : "", - "agency_id" : 3, - "state" : "OR", - "map_code" : "", - "city" : "Philomath", - "timestamp" : 1369781684, - "address" : "100 S. 16th ST", - "description" : "Cat in tree", - "details" : "", - "unit" : "", - "lon" : -123.3634479, - "cross_street" : "", - "alert_id" : 4264162, - "units" : "" - } - -### `getLocations(north, south, east, west, callback)` - -Returns an array of locations that exist within the area bounded by `north`, `south`, `east`, and `west`. The parameters should be floating point numbers representing the latitude or longitude, whichever is appropriate for the compass direction. - -For example, - - active911.getLocations(46.12345, 44.54321, -122.00021, -124.132132, function (err, locations) { - if (err) { - return console.log('Unable to retrieve locations: ' + err); - } - - console.log('Returned ' + locations.length + ' locations.'); - }); - -Example response: - - [ - { - "resources" : [], - "lat" : 44.540121, - "name" : "Pinehurst Memorial", - "agency_id" : 3, - "icon_filename" : "icon-flag.png", - "description" : "Main Station Hosp.\nNear the depot\n5 entrances", - "id" : 175, - "lon" : -123.367601, - "icon_color" : "blue" - }, - { - "resources" : [ - { - "extension" : "jpg", - "title" : "Photo", - "id" : 5, - "details" : "", - "size" : 963979 - } - ], - "lat" : 44.541252, - "name" : "Hydrant", - "agency_id" : 3, - "icon_filename" : "icon-hydrant.png", - "description" : "15th & College", - "id" : 700, - "lon" : -123.364689, - "icon_color" : "red" - } - ] +Installation is simple: `npm install --save active911`. + +Basic Usage +----------- + +```javascript +var Active911 = require('active911'); +var client = new Active911.RefreshClient('YOUR REFRESH TOKEN'); + +client.getAgency().then(function(agency) { + console.log(agency.name); +}).catch(function(err) { + console.log('Problem getting Agency details:', err); +}); +``` + +API Methods +----------- + +The following public API methods are available: + +* `getAgency()` +* `getDevice(device_id)` +* `getAlerts()` +* `getDeviceAlerts(device_id)` +* `getAlert(alert_id)` +* `getLocations()` +* `getLocation(location_id)` +* `getResource(resource_id)` + +Each method returns a promise for a result, which will resolve as either an +object or an array, depending on the cardinality (e.g. `getAlerts` resolves as +an array, while `getAlert` resolves as an object). + +For details on the format of the result, please see the [Active911 API +wiki](http://wiki.active911.com/wiki/index.php/Accessing_the_API). Contributing ------------ -Contributions are encouraged. For a list of open issues, see . +Contributions are encouraged. For a list of open issues, see +. More Information ---------------- -More information about the API is available on [the Active911 Github wiki](https://github.com/active911/open-api/wiki). +More information about the API is available on [the Active911 +wiki](http://wiki.active911.com/wiki/index.php/Active911_Developer_API). + -- cgit v1.2.3