aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 7122176450d162cd3250fb7afb60e69bc9fd8ea8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
Active911 for Node.js
=====================

by Ben Burwell <bburwell1@gmail.com>

Installation
------------

Add `active911` to your dependencies and run `npm install`. You can use it in your project by using

    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"
        }
      ]

Contributing
------------

Contributions are encouraged. For a list of open issues, see <https://github.com/bburwell/active911/issues>.

More Information
----------------

More information about the API is available on [the Active911 Github wiki](https://github.com/active911/open-api/wiki).