Live Tracking API

Introduction

Live Tracking is an efficient system that offers a comprehensive solution for managing and monitoring various assets, including vehicles, users, and drivers. Live Tracking API provides real-time information on the location, status, and activity of assets. Additionally, users can also receive events based on the activity of the assets enabling real-time monitoring.

With its advanced capabilities, Live Tracking changes how businesses manage and monitor their assets, providing a powerful tool for optimizing operations and enhancing efficiency.

Current Live Tracking API version provides the following abilities:

Create and manage assets.
Query past track of assets.
Search for assets in an area.
Create monitors to track assets.
Create alerts based on asset activity.

Live Tracking

Examples

To see all tutorials related to the Live Tracking, click this banner

Asset

The Asset services in Live Tracking API allow businesses to create and manage assets. An asset represents an entity that needs to be tracked in your project. Users can define assets using a variety of properties like a unique ID for the asset, custom attributes of the asset for easy search and filter, among other properties. Once an asset is created, users can configure it to be tracked by using the GPS information from the asset.

Live Tracking API helps businesses in tracking real-time information about the location of an asset including their exact position, speed, last location and among other details. The real-time information of an asset can then be used to generate events based on certain pre-defined criteria. A combination of real-time information and events based on this information can be utilized to optimize logistics and improve operational efficiency.

Let’s take a look at some of the methods available to monitor and manage assets.

Create an Asset

Users can create new assets by sending a POST request with relevant details of the asset like name, ID, attributes, etc. The service responds with an asset ID which can be used to perform all other asset operations. A restaurant delivery service, for example, can utilize this API method to create a new set of assets representing each delivery vehicle in their fleet, simplifying management and tracking.

POST

https://api.nextbillion.io/skynet/asset?key={your_api_key}

Request Parameter

Request Body

Response Schema

Sample API Request

1
2
3
4
5
6
7
8
9
curl --location --request POST 'https://api.nextbillion.io/skynet/asset?key=<your_api_key>'
--header 'Content-Type: application/json'
--data-raw '{
  "name": "Delivery Vehicle 001",
  "description": "This vehicle is used for restaurant delivery services",
  "attributes":{"license":"AX 78 TR 5421",
                "driver_name":"David Smith",
                "driver_contact_no":"123-456-1234"}
}'

Sample API Response

1
2
3
4
5
6
{
  "status": "Ok",
  "data": {
    "id": "4ba554b9-ef1c-48f0-9833-636edcf89256"
  }
}

Get an Asset

Users can retrieve a specific asset and its related information by providing the asset ID as a path parameter. The response containing all the details of the requested asset can be easily consumed within the user’s software applications or platforms. For example, a logistics company that provides delivery services to restaurants can use this API method to retrieve the information of a specific delivery truck within its fleet management system.

GET

https://api.nextbillion.io/skynet/asset/{id}?key={your_api_key}

Request Parameter

Response Schema

Sample API Request

curl --location --request GET 'https://api.nextbillion.io/skynet/asset/38a530ca-18c4-482b-8fb4-c40c5b1349ee?key=<your_api_key>'

Sample API Response

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
{
   "status": "Ok",
   "data": {
       "asset": {
           "id": "38a530ca-18c4-482b-8fb4-c40c5b1349ee",
           "device_id": "258c6471-8533-45df-8924-d0be8e508141",
           "name": "Delivery Vehicle 001",
           "description": "This vehicle is used for restaurant delivery services",
           "created_at": 1698692011,
           "updated_at": 1698771931,
           "attributes": {
              "driver_contact_no": "123-456-1234",
              "driver_name": "David Smith",
              "license": "AX 78 TR 5421"
           },
           "latest_location": {
               "location": {
                   "lat": 34.022778,
                   "lon": -118.28147
               },
               "timestamp": 1698773113917,
               "accuracy": 4.819578268302463,
               "altitude": 271.6402533762157
           }
       }
   }
}

Update an Asset

Use this method to update the data related to an asset by sending a PUT request with the asset ID as a path parameter and asset details to be updated in the request body. For example, a restaurant delivery service can utilize this API method to update the metadata of their delivery vehicles. This would allow the service to manage the details of each vehicle more efficiently, ensuring that the information is up-to-date and relevant to their customers.

PUT

https://api.nextbillion.io/skynet/asset/{id}?key={your_api_key}

Request Parameter

Request Body

Response Schema

Sample API Request

1
2
3
4
5
6
7
8
9
10
11
12
13
curl --location --request PUT 'https://api.nextbillion.io/skynet/asset/4ba554b9-ef1c-48f0-9833-636edcf89256?key=<your_api_key>'
--header 'Content-Type: application/json'
--data-raw '{"name": "Delivery Vehicle 001",
"description": "This vehicle is used for restaurant delivery services",
"created_at": 1687104162,
"updated_at": 1687104162,
"attributes": {
    "driver_contact_no": "123-456-1234",
    "driver_name": "David Smith",
    "license": "AX 78 TR 5421",
    "vehicle_type": "pickup_truck"
}
}'

Sample API Response

1
2
3
{
"status": "Ok"
}

Update Asset Attributes

This method enables users to update the attributes of an asset. Users can use this method to maintain custom attributes such as shift timing, driver name or any other useful information related to the asset. These attributes can be utilized for filtering assets in search queries, configuring monitors, and obtaining asset lists.

PUT

https://api.nextbillion.io/skynet/asset/{id}/attributes?key={your_api_key}

Request Parameter

Request Body

Response Schema

Sample API Request

1
2
3
4
5
6
7
8
9
curl --location --request PUT 'https://api.nextbillion.io/skynet/asset/788bfcbb-e067-48fb-a4a8-a09d9530aee8/attributes?key=<your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "attributes":{
                "driver_name": "Jack Hamlin",
                "license": "AR 30 TR 8080",
                "shift_timing": "0930 - 1830"
                }
}'

Sample API Response

1
2
3
{
  "status": "Ok"
}

Bind Device to Asset

This method is used to bind a GPS device to an asset where, a device is any physical GPS device capable of sending tracking information and an asset is any vehicle or moving object that needs to be tracked. An asset needs to be linked to a GPS device to be able to upload location information of its movement. Users can bind one device to multiple assets, but it is not recommended to do so simultaneously (lest multiple assets will have the same tracking information). The devices bound to assets can be updated from time to time as the business requirements change. Users can use this method to do so by providing the new device_id in the request body. The service will overwrite the existing device_id.

This method has applications in fleet management, asset tracking, logistics, supply chain management, asset security and field service management. It enables users to bind GPS devices to assets such as vehicles, equipment, or shipments, allowing real-time tracking, monitoring, and optimization of asset movement.

POST

https://api.nextbillion.io/skynet/asset/{id}/bind?key={your_api_key}

Request Parameter

Request Body

Response Schema

Sample API Request

1
2
3
4
5
curl --location --request POST 'https://api.nextbillion.io/skynet/asset/4ba554b9-ef1c-48f0-9833-636edcf89256/bind?key=<your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "device_id":"A1_543XST2"
}'

Sample API Response

1
2
3
{
  "status": "Ok"
}

Delete An asset

Users can send a DELETE request with the asset id as a path parameter to delete an existing asset. For example, a logistics service provider can leverage this API method to delete assets such as delivery vehicles that are no longer needed or are beyond repair. Please note that on deleting an asset the related tracking data is also deleted.

DELETE

https://api.nextbillion.io/skynet/asset/{id}?key={your_api_key}

Request Parameter

Response Schema

Sample API Request

curl --location --request DELETE 'https://api.nextbillion.io/skynet/asset/cc2987a9-5fc7-438c-b026-09792c6687f8?key=<your_api_key>'

Sample API Response

1
2
3
{
  "status": "Ok"
}

Get Asset List

Use this method to get a list of assets by sending a GET request with filter criteria properties as request parameters. The service returns a paginated response containing a list of assets along with details of their latest tracked location. The pagination feature allows users to break down the list of assets into smaller, more manageable subsets, making it easier for users to navigate through larger sets of data on their software applications or platforms. For example, a restaurant delivery service can use this API method to retrieve a list of all their available delivery vehicles that have specific area attributes. This would enable them to efficiently manage their fleet and ensure that all available vehicles are properly accounted for.

GET

https://api.nextbillion.io/skynet/asset/list?key={your_api_key}

Request Parameter

Response Schema

Sample API Request

curl --location 'https://api.nextbillion.io/skynet/asset/list?include_all_of_attributes=vehicle_type:mini-bus&sort=created_at:desc&ps=500&pn=1&key=<your_api_key>'

Sample API Response

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
{
   "status": "Ok",
   "data": {
       "list": [
           {
               "id": "9cbd6ed2-bf74-4083-85c9-9638668ace2d",
               "device_id": "APL-14-iOS-D430NUA",
               "name": "Staff Transportation 002",
               "description": "This vehicle is used for transporting hospital staff",
               "created_at": 1699433870,
               "updated_at": 1699433982,
               "attributes": {
                   "driver_contact_no": "546-602-158",
                   "driver_name": "Jack Reacher",
                   "license": "9 IB 3719",
                   "vehicle_type": "mini-bus"
               },
               "latest_location": {
                   "location": {
                       "lat": 33.90542689,
                       "lon": -118.23184349
                   },
                   "timestamp": 1686730017000,
                   "accuracy": 7,
                   "speed": 12,
                   "bearing": 25,
                   "altitude": 100.5,
                   "meta_data": {
                       "test": "destination_patient_address"
                   }
               }
           },
           {
               "id": "9a869933-8330-410e-a657-ca07898e31b3",
               "device_id": "APL-14-iOS-X43V21F",
               "name": "Staff Transportation 001",
               "description": "This vehicle is used for transporting hotel staff",
               "created_at": 1699433640,
               "updated_at": 1699433731,
               "attributes": {
                   "driver_contact_no": "595-232-764",
                   "driver_name": "Jack Shipley",
                   "license": "7 BA 3352",
                   "vehicle_type": "mini-bus"
               },
               "latest_location": {
                   "location": {
                       "lat": 34.04510936036783,
                       "lon": -118.26998982639944
                   },
                   "timestamp": 1686730017000,
                   "accuracy": 7,
                   "speed": 12,
                   "bearing": 25,
                   "altitude": 100.5,
                   "meta_data": {
                       "test": "destination"
                   }
               }
           }
       ],
       "page": {
           "total": 2,
           "offset": 0,
           "page": 1,
           "size": 2,
           "hasmore": false
       }
   }
}

Upload locations of an Asset

Use this method to upload location information for assets by sending a POST request with asset ID as a path parameter and the details of the location details in the request body. This API method is useful for building applications that require location-based tracking and monitoring, such as fleet management systems, asset tracking platforms, and logistics management solutions.

For example, when a delivery truck starts its journey, the API method is used to upload the truck's id or external_id, service_id, name along with current location data, such as timestamp, accuracy, speed, bearing, altitude, and metadata. As the truck continues on its journey, the API method can be used to upload the updated location data at regular intervals. The restaurant delivery service provider can use this real-time location data to optimize delivery routes, track the progress of their delivery trucks, and ensure that deliveries are made on time.

POST

https://api.nextbillion.io/skynet/asset/{id}/track?key={your_api_key}

Request Parameter

Request Body

Response Schema

Sample API Request

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
curl --location --request POST 'https://api.nextbillion.io/skynet/asset/4ba554b9-ef1c-48f0-9833-636edcf89256/track?key=<your_api_key>'
--header 'Content-Type: application/json' \
--data-raw '{
            "locations":[
                {
                "location":{
                    "lat": 34.06848239,
                    "lon":-118.30956508
                },
                "timestamp":1686729177000,
                "accuracy":2,
                "speed":5,
                "bearing":25,
                "altitude":110.5,
                "meta_data":{
                    "test": "sample_location_1"
                }
                },
                {
                "location":{
                    "lat": 34.04413804,
                    "lon": -118.30956508
                },
                "timestamp":1686729477000,
                "accuracy":1,
                "speed":8,
                "bearing":25,
                "altitude":110.5,
                "meta_data":{
                    "test": "sample_location_2"
                }
                },
                {
                "location":{
                    "lat": 34.02235033,
                    "lon": -118.30904957
                },
                "timestamp":1686730017000,
                "accuracy":7,
                "speed":12,
                "bearing":25,
                "altitude":100.5,
                "meta_data":{
                    "test": "sample_location_3"
                }
                },
                {
                "location":{
                    "lat": 34.03281768,
                    "lon": -118.30595651
                },
                "timestamp":1686730257000,
                "accuracy":5,
                "speed":4,
                "bearing":115,
                "altitude":89.0,
                "meta_data":{
                    "test": "sample_location_4"
                }
                },
                {
                "location":{
                    "lat": 34.02277760,
                    "lon": -118.28146978
                },
                "timestamp":1686730737000,
                "accuracy":2,
                "speed":9,
                "bearing":95,
                "altitude":68.0,
                "meta_data":{
                    "test": "sample_location_5"
                }
                }
            ],
            "device_id":"A1_543XST2"
        }'

Sample API Response

1
2
3
{
  "status": "Ok"
}

Track locations of an Asset

This method allows users to retrieve the location data of an asset within their software applications or platforms with pagination support. This API endpoint supports optional filters such as start_time, end_time, and geometry_type, providing users with more control over the returned data. For example, a restaurant delivery service provider that wants to track the location of their delivery vehicle can use this method to retrieve the current and past locations of a vehicle, as well as additional details such as accuracy, speed, and timestamp. They can also filter the results based on specific timeframes and choose to display the location data in various formats such as polyline, polyline6, or geojson. This information can help the company optimize its delivery routes, estimate delivery times, and ensure that its trucks are operating efficiently.

GET

https://api.nextbillion.io/skynet/asset/{id}/location/list?key={your_api_key}

Request Parameter

Response Schema

Sample API Request

curl --location --request GET 'https://api.nextbillion.io/skynet/asset/4ba554b9-ef1c-48f0-9833-636edcf89256/location/list?key=<your_api_key>&geometry_type=geojson&correction=mapmatch=1,interpolate=1,mode=car'

Sample API Response

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
134
135
136
137
138
139
140
141
142
143
144
145
146
{
  "status": "Ok",
  "data": {
    "list": [
      {
        "location": {
          "lat": 34.068482,
          "lon": -118.309565
        },
        "timestamp": 1686729177000,
        "accuracy": 2,
        "speed": 5,
        "bearing": 25,
        "altitude": 110.5
      },
      {
        "location": {
          "lat": 34.044138,
          "lon": -118.309565
        },
        "timestamp": 1686729477000,
        "accuracy": 1,
        "speed": 8,
        "bearing": 25,
        "altitude": 110.5
      },
      {
        "location": {
          "lat": 34.02235,
          "lon": -118.30905
        },
        "timestamp": 1686730017000,
        "accuracy": 7,
        "speed": 12,
        "bearing": 25,
        "altitude": 100.5
      },
      {
        "location": {
          "lat": 34.032818,
          "lon": -118.305957
        },
        "timestamp": 1686730257000,
        "accuracy": 5,
        "speed": 4,
        "bearing": 115,
        "altitude": 89
      },
      {
        "location": {
          "lat": 34.022778,
          "lon": -118.28147
        },
        "timestamp": 1686730737000,
        "accuracy": 2,
        "speed": 9,
        "bearing": 95,
        "altitude": 68
      }
    ],
    "page": {
      "total": 5,
      "offset": 0,
      "page": 1,
      "size": 5,
      "hasmore": false
    },
    "geojson": {
      "type": "Feature",
      "geometry": {
        "type": "MultiLineString",
        "coordinates": [
          [
            [-118.309654, 34.068268],
            [-118.30977, 34.067144],
            [-118.309106, 34.067151],
            [-118.309024, 34.044518],
            [-118.30889, 34.022806],
            [-118.308972, 34.032682],
            [-118.30604, 34.032705],
            [-118.306021, 34.030873],
            [-118.305375, 34.03087],
            [-118.305339, 34.025512],
            [-118.28817, 34.025437],
            [-118.281616, 34.022555]
          ]
        ]
      },
      "properties": null
    },
    "distance": 9626,
    "geometry": ["wqj~_Ajp`t`FfeAfFMoh@pek@cD~ki@kGghRbDm@gvDnqBe@Dkg@zmIgAtCap`@bsDsxK"],
    "snapped_points": [
      {
        "bearing": 0,
        "distance": 25,
        "name": "",
        "originalIndex": 0,
        "location": {
          "lat": 34.068268,
          "lon": -118.309654
        }
      },
      {
        "bearing": 0,
        "distance": 65,
        "name": "S Western Ave",
        "originalIndex": 1,
        "location": {
          "lat": 34.044518,
          "lon": -118.309024
        }
      },
      {
        "bearing": 0,
        "distance": 52,
        "name": "W 36th St",
        "originalIndex": 2,
        "location": {
          "lat": 34.022806,
          "lon": -118.30889
        }
      },
      {
        "bearing": 0,
        "distance": 14,
        "name": "",
        "originalIndex": 3,
        "location": {
          "lat": 34.032705,
          "lon": -118.30604
        }
      },
      {
        "bearing": 0,
        "distance": 28,
        "name": "W Jefferson Blvd",
        "originalIndex": 4,
        "location": {
          "lat": 34.022555,
          "lon": -118.281616
        }
      }
    ]
  }
}

Track the last location of an Asset

Use this method to get the last known location of an asset by sendinging the id of the asset as a path parameter to get the last tracked location of the asset along with its details such as accuracy, speed, bearing along with other details of the asset.

Suppose you are developing a restaurant delivery management software and want to display the last location of each delivery vehicle in real-time to the users of your application. You can use this method to fetch the last known location of each vehicle and display it on a map interface in your application. This will provide your users with accurate and up-to-date information about the last location of their delivery vehicles.

GET

https://api.nextbillion.io/skynet/asset/{id}/location/last?key={your_api_key}

Request Parameter

Response Schema

Sample API Request

curl --location --request GET 'https://api.nextbillion.io/skynet/asset/4ba554b9-ef1c-48f0-9833-636edcf89256/location/last?key=<your_api_key>'

Sample API Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "status": "Ok",
  "data": {
    "location": {
      "location": {
        "lat": 34.022778,
        "lon": -118.28147
      },
      "timestamp": 1686730737000,
      "accuracy": 2,
      "speed": 9,
      "bearing": 95,
      "altitude": 68
    }
  }
}

Event History of an Asset

Use this method to get the history of an asset’s events. An event refers to an occurrence or incident that is detected by the tracking system in real-time. Live Tracking API can generate events when an asset

moves into or out of a monitored geofence
exceeds the specified speed limits
is idle for a specified amount of time

Events form a crucial aspect of Live Tracking, as they provide real-time information about the movement and status of assets, enabling businesses to optimize their operations, improve safety and provide better customer service.

Users can send a GET request along with an asset ID as a path parameter to retrieve the event history of an asset within their software applications or platforms with pagination support. This method is useful in building software applications that need to track the movement of their assets to make further decisions like tracking compliance, disbursing reimbursements, ensuring service delivery, etc.

GET

https://api.nextbillion.io/skynet/asset/{id}/event/list?key={your_api_key}

Request Parameter

Response Schema

Sample API Request

curl --location --request GET 'https://api.nextbillion.io/skynet/asset/e232b966-b30c-49b9-9e11-56065409519e/event/list?key=<your_api_key>&monitor_id=6ef9582e-f75e-4ca1-b4f1-e3aedec7274e'

Sample API Response

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
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
{
  "status": "Ok",
  "data": {
    "list": [
      {
        "asset_id": "e232b966-b30c-49b9-9e11-56065409519e",
        "geofence_id": "bb456968-476f-4f02-b9bb-cc1b0cf9e8cb",
        "monitor_id": "6ef9582e-f75e-4ca1-b4f1-e3aedec7274e",
        "monitor_tags": ["monitor_tag"],
        "event_type": "enter",
        "timestamp": 1684390206813,
        "triggered_timestamp": 1683035625000,
        "triggered_location": {
          "location": {
            "lat": 1.3624458701362037,
            "lon": 103.86785626672408
          },
          "timestamp": 1683035625000,
          "speed": 20
        },
        "prev_location": {
          "location": {
            "lat": 1.3636439655170736,
            "lon": 103.8684361783896
          },
          "timestamp": 1683035385000,
          "speed": 20
        }
      },
      {
        "asset_id": "e232b966-b30c-49b9-9e11-56065409519e",
        "geofence_id": "bb456968-476f-4f02-b9bb-cc1b0cf9e8cb",
        "monitor_id": "6ef9582e-f75e-4ca1-b4f1-e3aedec7274e",
        "monitor_tags": ["monitor_tag"],
        "event_type": "exit",
        "timestamp": 1684390206814,
        "triggered_timestamp": 1683035865000,
        "triggered_location": {
          "location": {
            "lat": 1.3617174213906844,
            "lon": 103.86685855925109
          },
          "timestamp": 1683035865000,
          "speed": 20
        },
        "prev_location": {
          "location": {
            "lat": 1.3624458701362037,
            "lon": 103.86785626672408
          },
          "timestamp": 1683035625000,
          "speed": 20
        }
      },
      {
        "asset_id": "e232b966-b30c-49b9-9e11-56065409519e",
        "geofence_id": "bb456968-476f-4f02-b9bb-cc1b0cf9e8cb",
        "monitor_id": "6ef9582e-f75e-4ca1-b4f1-e3aedec7274e",
        "monitor_tags": ["monitor_tag"],
        "event_type": "enter",
        "timestamp": 1684411136922,
        "triggered_timestamp": 1683035625000,
        "triggered_location": {
          "location": {
            "lat": 1.3624458701362037,
            "lon": 103.86785626672408
          },
          "timestamp": 1683035625000,
          "speed": 20
        },
        "prev_location": {
          "location": {
            "lat": 1.3636439655170736,
            "lon": 103.8684361783896
          },
          "timestamp": 1683035385000,
          "speed": 20
        }
      },
      {
        "asset_id": "e232b966-b30c-49b9-9e11-56065409519e",
        "geofence_id": "bb456968-476f-4f02-b9bb-cc1b0cf9e8cb",
        "monitor_id": "6ef9582e-f75e-4ca1-b4f1-e3aedec7274e",
        "monitor_tags": ["monitor_tag"],
        "event_type": "exit",
        "timestamp": 1684411136923,
        "triggered_timestamp": 1683035865000,
        "triggered_location": {
          "location": {
            "lat": 1.3617174213906844,
            "lon": 103.86685855925109
          },
          "timestamp": 1683035865000,
          "speed": 20
        },
        "prev_location": {
          "location": {
            "lat": 1.3624458701362037,
            "lon": 103.86785626672408
          },
          "timestamp": 1683035625000,
          "speed": 20
        }
      },
      {
        "asset_id": "e232b966-b30c-49b9-9e11-56065409519e",
        "geofence_id": "bb456968-476f-4f02-b9bb-cc1b0cf9e8cb",
        "monitor_id": "6ef9582e-f75e-4ca1-b4f1-e3aedec7274e",
        "monitor_tags": ["monitor_tag"],
        "event_type": "enter",
        "timestamp": 1684411905807,
        "triggered_timestamp": 1683035625000,
        "triggered_location": {
          "location": {
            "lat": 1.3624458701362037,
            "lon": 103.86785626672408
          },
          "timestamp": 1683035625000,
          "speed": 20
        },
        "prev_location": {
          "location": {
            "lat": 1.3636439655170736,
            "lon": 103.8684361783896
          },
          "timestamp": 1683035385000,
          "speed": 20
        }
      },
      {
        "asset_id": "e232b966-b30c-49b9-9e11-56065409519e",
        "geofence_id": "bb456968-476f-4f02-b9bb-cc1b0cf9e8cb",
        "monitor_id": "6ef9582e-f75e-4ca1-b4f1-e3aedec7274e",
        "monitor_tags": ["monitor_tag"],
        "event_type": "exit",
        "timestamp": 1684411905808,
        "triggered_timestamp": 1683035865000,
        "triggered_location": {
          "location": {
            "lat": 1.3617174213906844,
            "lon": 103.86685855925109
          },
          "timestamp": 1683035865000,
          "speed": 20
        },
        "prev_location": {
          "location": {
            "lat": 1.3624458701362037,
            "lon": 103.86785626672408
          },
          "timestamp": 1683035625000,
          "speed": 20
        }
      },
      {
        "asset_id": "e232b966-b30c-49b9-9e11-56065409519e",
        "geofence_id": "bb456968-476f-4f02-b9bb-cc1b0cf9e8cb",
        "monitor_id": "6ef9582e-f75e-4ca1-b4f1-e3aedec7274e",
        "monitor_tags": ["monitor_tag"],
        "event_type": "enter",
        "timestamp": 1684414999763,
        "triggered_timestamp": 1683035625000,
        "triggered_location": {
          "location": {
            "lat": 1.3624458701362037,
            "lon": 103.86785626672408
          },
          "timestamp": 1683035625000,
          "speed": 20
        },
        "prev_location": {
          "location": {
            "lat": 1.3636439655170736,
            "lon": 103.8684361783896
          },
          "timestamp": 1683035385000,
          "speed": 20
        }
      },
      {
        "asset_id": "e232b966-b30c-49b9-9e11-56065409519e",
        "geofence_id": "bb456968-476f-4f02-b9bb-cc1b0cf9e8cb",
        "monitor_id": "6ef9582e-f75e-4ca1-b4f1-e3aedec7274e",
        "monitor_tags": ["monitor_tag"],
        "event_type": "exit",
        "timestamp": 1684414999764,
        "triggered_timestamp": 1683035865000,
        "triggered_location": {
          "location": {
            "lat": 1.3617174213906844,
            "lon": 103.86685855925109
          },
          "timestamp": 1683035865000,
          "speed": 20
        },
        "prev_location": {
          "location": {
            "lat": 1.3624458701362037,
            "lon": 103.86785626672408
          },
          "timestamp": 1683035625000,
          "speed": 20
        }
      },
      {
        "asset_id": "e232b966-b30c-49b9-9e11-56065409519e",
        "geofence_id": "bb456968-476f-4f02-b9bb-cc1b0cf9e8cb",
        "monitor_id": "6ef9582e-f75e-4ca1-b4f1-e3aedec7274e",
        "monitor_tags": ["monitor_tag"],
        "event_type": "enter",
        "timestamp": 1684415045127,
        "triggered_timestamp": 1683035625000,
        "triggered_location": {
          "location": {
            "lat": 1.3624458701362037,
            "lon": 103.86785626672408
          },
          "timestamp": 1683035625000,
          "speed": 20
        },
        "prev_location": {
          "location": {
            "lat": 1.3636439655170736,
            "lon": 103.8684361783896
          },
          "timestamp": 1683035385000,
          "speed": 20
        }
      },
      {
        "asset_id": "e232b966-b30c-49b9-9e11-56065409519e",
        "geofence_id": "bb456968-476f-4f02-b9bb-cc1b0cf9e8cb",
        "monitor_id": "6ef9582e-f75e-4ca1-b4f1-e3aedec7274e",
        "monitor_tags": ["monitor_tag"],
        "event_type": "exit",
        "timestamp": 1684415045128,
        "triggered_timestamp": 1683035865000,
        "triggered_location": {
          "location": {
            "lat": 1.3617174213906844,
            "lon": 103.86685855925109
          },
          "timestamp": 1683035865000,
          "speed": 20
        },
        "prev_location": {
          "location": {
            "lat": 1.3624458701362037,
            "lon": 103.86785626672408
          },
          "timestamp": 1683035625000,
          "speed": 20
        }
      },
      {
        "asset_id": "e232b966-b30c-49b9-9e11-56065409519e",
        "geofence_id": "bb456968-476f-4f02-b9bb-cc1b0cf9e8cb",
        "monitor_id": "6ef9582e-f75e-4ca1-b4f1-e3aedec7274e",
        "monitor_tags": ["monitor_tag"],
        "event_type": "enter",
        "timestamp": 1684415297271,
        "triggered_timestamp": 1683035625000,
        "triggered_location": {
          "location": {
            "lat": 1.3624458701362037,
            "lon": 103.86785626672408
          },
          "timestamp": 1683035625000,
          "speed": 20
        },
        "prev_location": {
          "location": {
            "lat": 1.3636439655170736,
            "lon": 103.8684361783896
          },
          "timestamp": 1683035385000,
          "speed": 20
        }
      },
      {
        "asset_id": "e232b966-b30c-49b9-9e11-56065409519e",
        "geofence_id": "bb456968-476f-4f02-b9bb-cc1b0cf9e8cb",
        "monitor_id": "6ef9582e-f75e-4ca1-b4f1-e3aedec7274e",
        "monitor_tags": ["monitor_tag"],
        "event_type": "exit",
        "timestamp": 1684415297272,
        "triggered_timestamp": 1683035865000,
        "triggered_location": {
          "location": {
            "lat": 1.3617174213906844,
            "lon": 103.86685855925109
          },
          "timestamp": 1683035865000,
          "speed": 20
        },
        "prev_location": {
          "location": {
            "lat": 1.3624458701362037,
            "lon": 103.86785626672408
          },
          "timestamp": 1683035625000,
          "speed": 20
        }
      },
      {
        "asset_id": "e232b966-b30c-49b9-9e11-56065409519e",
        "geofence_id": "bb456968-476f-4f02-b9bb-cc1b0cf9e8cb",
        "monitor_id": "6ef9582e-f75e-4ca1-b4f1-e3aedec7274e",
        "monitor_tags": ["monitor_tag"],
        "event_type": "enter",
        "timestamp": 1684416246089,
        "triggered_timestamp": 1683035625000,
        "triggered_location": {
          "location": {
            "lat": 1.3624458701362037,
            "lon": 103.86785626672408
          },
          "timestamp": 1683035625000,
          "speed": 20
        },
        "prev_location": {
          "location": {
            "lat": 1.3636439655170736,
            "lon": 103.8684361783896
          },
          "timestamp": 1683035385000,
          "speed": 20
        }
      },
      {
        "asset_id": "e232b966-b30c-49b9-9e11-56065409519e",
        "geofence_id": "bb456968-476f-4f02-b9bb-cc1b0cf9e8cb",
        "monitor_id": "6ef9582e-f75e-4ca1-b4f1-e3aedec7274e",
        "monitor_tags": ["monitor_tag"],
        "event_type": "exit",
        "timestamp": 1684416246090,
        "triggered_timestamp": 1683035865000,
        "triggered_location": {
          "location": {
            "lat": 1.3617174213906844,
            "lon": 103.86685855925109
          },
          "timestamp": 1683035865000,
          "speed": 20
        },
        "prev_location": {
          "location": {
            "lat": 1.3624458701362037,
            "lon": 103.86785626672408
          },
          "timestamp": 1683035625000,
          "speed": 20
        }
      }
    ],
    "page": {
      "total": 24,
      "offset": 0,
      "page": 1,
      "size": 14,
      "hasmore": true
    }
  }
}

Search

The Search service of Live Tracking API allows users to search for active assets within a specific area or a bounding box. It uses a specified search area to return a list of active assets that fall within it. An asset is considered active if it has been tracked (location uploaded) at least once during the last 7 days. Once a search request is submitted successfully, the service responds with a paginated result listing all the assets found. This can be particularly useful for applications that require proximity-based search functionality such as restaurant or store locators, or for tracking the location of assets in a fleet management system.

Around Search

Use this method to search for active assets within a specified radius of a location coordinate. For example, a restaurant delivery service can search for all available delivery vehicles that are within a 5000 m radius of a specified location using this API method. They can also apply a filter to their search to only retrieve assets that are currently available for use. The API will return a list of available delivery vehicles within the specified radius along with their location, metadata, and other details allowing the company to plan its logistics more efficiently.

GET

https://api.nextbillion.io/skynet/search/around?{center}&{radius}&key={your_api_key}

Request Parameter

Response Schema

Sample API Request

curl --location 'https://api.nextbillion.io/skynet/search/around?key=<your_api_key>&center=34.04937853,-118.27333793&radius=5000&include_all_of_attributes=driver_name:John Blake|vehicle_type:Pickup'

Sample API Response

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
{
   "status": "Ok",
   "msg": "",
   "data": {
       "assets": [
           {
               "id": "a39f8299-e19a-4484-9775-be8ae40f75c9",
               "device_id": "ADR-10-SND-SAM031",
               "name": "Staff Transportation 002",
               "description": "Live Tracking Around Search",
               "latest_location": {
                   "location": {
                       "lat": 34.04909446,
                       "lon": -118.27008086
                   },
                   "timestamp": 1701100800000,
                   "accuracy": 2,
                   "speed": 5,
                   "bearing": 25,
                   "altitude": 110.5,
                   "meta_data": {
                       "test": "sample_location"
                   }
               },
               "attributes": {
                   "driver_contact_no": "422-761-938",
                   "driver_name": "John Blake",
                   "license": "2 BR 2049",
                   "vehicle_type": "Pickup"
               },
               "created_at": 1694541056,
               "updated_at": 1694541187
           }
       ],
       "page": {
           "total": 1,
           "offset": 0,
           "page": 1,
           "size": 1,
           "hasmore": false
       }
   }
}

Bound Search

Use this method to search for active assets within a specified geographic boundary. It takes a bound parameter which is a pipe (|) delimited string of two latitude and longitude coordinates, the first being the southwest coordinate and the second being the northeast coordinate of the bounding box. Please note that the bounding box area is limited to a maximum of 3000 km². The API also supports filtering the search results based on multiple conditions specified in the ‘filter’ parameter as a pipe-delimited string of key-value pairs. Once a valid request is submitted, the service responds with a paginated list of assets found within the specified bound.

This service can be useful to, for example, a restaurant delivery service may use this API method to find all their delivery vehicles that are currently within a specific area. They can use the bound parameter to specify the coordinates of the boundary that defines the area and filter the search results to only include bikes or trucks. This would allow the service to efficiently allocate its resources and optimize its delivery routes. The API method returns a response with information about each asset that matches the search criteria including the asset's ID, name, last tracked location, and any attributes attached to the asset.

GET

https://api.nextbillion.io/skynet/search/bound?{bound}&key={your_api_key}

Request Parameter

Response Schema

Sample API Request

curl --location 'https://api.nextbillion.io/skynet/search/bound?bound=34.04497533,-118.27710928|34.05875233,-118.26048106&include_all_of_attributes=driver_name:John Blake|vehicle_type:Pickup&key=<your_api_key>'

Sample API Response

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
{
   "status": "Ok",
   "msg": "",
   "data": {
       "assets": [
           {
               "id": "a39f8299-e19a-4484-9775-be8ae40f75c9",
               "device_id": "ADR-10-SND-SAM031",
               "name": "Staff Transportation 002",
               "description": "Live Tracking Bound Search",
               "latest_location": {
                   "location": {
                       "lat": 34.04909446,
                       "lon": -118.27008086
                   },
                   "timestamp": 1701100800000,
                   "accuracy": 2,
                   "speed": 5,
                   "bearing": 25,
                   "altitude": 110.5,
                   "meta_data": {
                       "test": "sample_location"
                   }
               },
               "attributes": {
                   "driver_contact_no": "422-761-938",
                   "driver_name": "John Blake",
                   "license": "2 BR 2049",
                   "vehicle_type": "Pickup"
               },
               "created_at": 1694541056,
               "updated_at": 1694541187
           }
       ],
       "page": {
           "total": 1,
           "offset": 0,
           "page": 1,
           "size": 1,
           "hasmore": false
       }
   }
}

GET Polygon Search

The "Polygon Search" API method allows you to search for active assets within a polygon defined by a set of coordinates. With this API, you can filter active assets based on multiple conditions and retrieve information like asset name, description, last tracked location, tags, and attributes.

This API is particularly useful for businesses that need to track assets and equipment in specific geographical areas. Please note that the search polygon size is limited to a maximum area of 3000 km². For example, a restaurant delivery service can use this API to locate all their delivery vehicles within a specific delivery zone. In addition to location tracking, this API also enables the filtering of assets based on different parameters such as the asset's creation and update time, tags, and other details which can help the restaurant delivery service provider to efficiently manage their assets and delivery operations.

GET

https://api.nextbillion.io/skynet/search/polygon?{polygon}&key={your_api_key}

Request Parameter

Response Schema

Sample API Request

curl --location 'https://api.nextbillion.io/skynet/search/polygon?key=<your_api_key>&polygon=34.05875233,-118.26048106|34.04611166,-118.25533831|34.02778645,-118.25705256|34.02991749,-118.30796578|34.07309507,-118.30796578|34.05875233,-118.26048106&include_all_of_attributes=driver_name:John Blake|vehicle_type:Pickup'

Sample API Response

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
{
   "status": "Ok",
   "msg": "",
   "data": {
       "assets": [
           {
               "id": "a39f8299-e19a-4484-9775-be8ae40f75c9",
               "device_id": "ADR-10-SND-SAM031",
               "name": "Staff Transportation 002",
               "description": "Live Tracking Polygon Search",
               "latest_location": {
                   "location": {
                       "lat": 34.04909446,
                       "lon": -118.27008086
                   },
                   "timestamp": 1701100800000,
                   "accuracy": 2,
                   "speed": 5,
                   "bearing": 25,
                   "altitude": 110.5,
                   "meta_data": {
                       "test": "sample_location"
                   }
               },
               "attributes": {
                   "driver_contact_no": "422-761-938",
                   "driver_name": "John Blake",
                   "license": "2 BR 2049",
                   "vehicle_type": "Pickup"
               },
               "created_at": 1694541056,
               "updated_at": 1694541187
           }
       ],
       "page": {
           "total": 1,
           "offset": 0,
           "page": 1,
           "size": 1,
           "hasmore": false
       }
   }
}

POST Polygon Search

POST Polygon Search allows users to search for active assets in a large polygon with many coordinates. The underlying behavior is similar to the GET method. It is recommended to use the POST method in case of large or complex polygons with a big set of boundary coordinates which, otherwise, may cause the request to breach the URL limits of a GET endpoint. You can also use this method if you prefer to input polygon boundaries in GeoJSON format. Please note that the search polygon size is limited to a maximum area of 3000 km².

POST

https://api.nextbillion.io/skynet/search/polygon?key={your_api_key}

Request Parameter

Request Body

Response Schema

Sample API Request

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
curl --location 'https://api.nextbillion.io/skynet/search/polygon?key=<your_api_key>' \
--header 'Content-Type: application/json' \
--data '{
    "polygon":{
        "type":"polygon",
        "coordinates":[
            [
            [
             -118.26048106,
             34.05875233
            ],
            [
                -118.25533831,
                34.04611166
            ],
            [
                -118.25705256,
                34.02778645
            ],
            [
                -118.30796578,
                34.02991749
            ],
            [
                -118.30796578,
                34.07309507
            ],
            [
                -118.26048106,
                34.05875233
            ]
        ]
        ]
    },
    "match_filter":{
    "include_all_of_attributes":{
                "driver_name": "John Blake",
                "vehicle_type": "Pickup"
                }
}
}'

Sample Response

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
{
   "status": "Ok",
   "msg": "",
   "data": {
       "assets": [
           {
               "id": "a39f8299-e19a-4484-9775-be8ae40f75c9",
               "device_id": "ADR-10-SND-SAM031",
               "name": "Staff Transportation 002",
               "description": "Live Tracking Polygon Search",
               "latest_location": {
                   "location": {
                       "lat": 34.04909446,
                       "lon": -118.27008086
                   },
                   "timestamp": 1701100800000,
                   "accuracy": 2,
                   "speed": 5,
                   "bearing": 25,
                   "altitude": 110.5,
                   "meta_data": {
                       "test": "sample_location"
                   }
               },
               "attributes": {
                   "driver_contact_no": "422-761-938",
                   "driver_name": "John Blake",
                   "license": "2 BR 2049",
                   "vehicle_type": "Pickup"
               },
               "created_at": 1694541056,
               "updated_at": 1694541187
           }
       ],
       "page": {
           "total": 1,
           "offset": 0,
           "page": 1,
           "size": 1,
           "hasmore": false
       }
   }
}

Monitor

The monitor service of Live Tracking API is a feature that enables users to define and manage monitoring zones or geofences for tracking assets in real-time. A geofence is a virtual boundary that can be defined around a specific area, such as a building, a parking lot, or a city block. When an asset enters or exits the geofence, the monitoring service generates an event that can be captured by the Live Tracking API. The monitoring service also allows tracking the asset activity while it is on move through the idle and speeding alerts.

The Monitor service can be used in a variety of industries such as logistics, transportation, and security, to track and monitor the movement of assets in real-time. For example, a logistics company may use the monitor service to track the movement of its delivery trucks and monitor their arrival and departure from different warehouses or distribution centers. A security company may use the monitor service to set up speeding and idle alerts to track the movements and flag any suspicious activity by the asset.

Let’s take a look at the methods and properties available for leveraging the Monitor service.

Create a Monitor

This method enables users to create monitors that track specific activities, providing valuable functionality for various purposes. It is particularly beneficial for managing vehicle fleets, tracking deliveries and monitoring equipment in restricted areas. By assigning attributes to monitors, users can conveniently monitor assets that share common attributes, facilitating collective monitoring of asset activities. For instance, attributes like "shift_1" or "area_Los Angeles" can be employed to group assets and monitor their activities efficiently. The method also allows users to specify the type of activity the monitor should detect, enabling focused monitoring of specific events. For example, a monitor can be configured to create an event when an asset enters a geofence, enabling accurate tracking of asset movements or track the speed of the asset while it is moving or just raise a flag when it is idle.

POST

https://api.nextbillion.io/skynet/monitor?key={your_api_key}

Request Parameter

Request Body

Response Schema

Example 1 - Create an enter & exit type Monitor

Let’s create a monitor for tracking the entry and exit of an asset into a geofence. In the create request we:

Set the type to enter_and_exit
Add the ID of the geofence that would be used to determine the monitored area.
Add the attributes matching the asset whose activity needs to be monitored.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl --location --request POST 'https://api.nextbillion.io/skynet/monitor?key=<your_api_key>'
--header 'Content-Type: application/json'
--data-raw '{
  "type": "enter_and_exit",
  "geofence_ids": [
    "1287cd61-fc73-48d2-a82f-6bb4eb0d6f69"
  ],
  "name": "Sheraton Grand Los Angeles monitor",
  "description": "Track activity related to free staff transportation service",
  "match_filter":{
      "include_all_of_attributes":{
                "driver_contact_no": "595-232-764",
                "driver_name": "Jack Shipley",
                "license": "7 BA 3352",
                "vehicle_type": "mini-bus"}
                }
}'

Response

1
2
3
4
5
6
{
  "status": "Ok",
  "data": {
    "id": "9a504acb-1889-4c79-a221-cd2c330f2a5b"
  }
}

Example 2 - Create a speeding type Monitor

Next, we will create a monitor for tracking the entry and exit of an asset into a geofence. In the create request we:

Set the type to speeding
Add the desired configuration to the speeding_config attribute
Add the attributes matching the asset whose activity needs to be monitored.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
curl --location --request POST 'https://api.nextbillion.io/skynet/monitor?key=<your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"type": "speeding",
"speeding_config": {
"time_tolerance": 55000,
"use_admin_speed_limit": false,
"customer_speed_limit": 25
},
"name": "Sheraton Grand Los Angeles monitor",
"description": "Track activity related to free staff transportation service",
"match_filter":{
"include_all_of_attributes":{
"driver_contact_no": "595-232-764",
"driver_name": "Jack Shipley",
"license": "7 BA 3352",
"vehicle_type": "mini-bus"}
}
}'

Response

1
2
3
4
5
6
{
  "status": "Ok",
  "data": {
    "id": "77202940-f2ec-4841-a8b7-f962def95006"
  }
}

Example 3 - Create an idle type Monitor

Next, we will create a monitor for tracking the entry and exit of an asset into a geofence. In the create request we:

Set the type to idle
Add the desired configuration to the idle_config attribute
Add the attributes matching the asset whose activity needs to be monitored.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
curl --location --request POST 'https://api.nextbillion.io/skynet/monitor?key=<your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "type": "idle",
   "idle_config": {
    "distance_tolerance": 120,
    "time_tolerance": 70000
   },
  "name": "Sheraton Grand Los Angeles monitor",
  "description": "Track activity related to free staff transportation service",
  "match_filter":{
      "include_all_of_attributes":{
                "driver_contact_no": "595-232-764",
                "driver_name": "Jack Shipley",
                "license": "7 BA 3352",
                "vehicle_type": "mini-bus"}
                }
}'

Response

1
2
3
4
5
6
{
"status": "Ok",
"data": {
"id": "a272012e-623a-4d74-b434-08801629dbb8"
}
}

Get a Monitor

This method retrieves the details and information of a specific monitor. By using this method, users can access the associated data of a monitor. This allows for easy retrieval of monitor-specific information for analysis, monitoring purposes or making any necessary adjustments to the monitor's settings.

GET

https://api.nextbillion.io/skynet/monitor/{id}?key={your_api_key}

Request Parameter

Response Schema

Sample Request

curl --location 'https://api.nextbillion.io/skynet/monitor/36c171d5-bdf1-47c2-9531-4c02820ab70e?key=<your_api_key>'

Sample Response

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
{
  "status": "Ok",
  "data": {
    "monitor": {
      "id": "36c171d5-bdf1-47c2-9531-4c02820ab70e",
      "type": "speeding",
      "name": "Delivery Monitor The Ritz Hotel, Los Angeles",
      "description": "Track speeding activity of the delivery vehicle",
      "geofences": null,
      "tags": [],
      "created_at": 1694619817,
      "updated_at": 1694672213,
      "match_filter": {
        "include_all_of_attributes": {
          "driver_contact_no": "321-902-838",
          "driver_name": "James Smith",
          "license": "4 ES 7167",
          "vehicle_type": "Delivery"
        }
      },
      "speeding_config": {
        "customer_speed_limit": 18,
        "time_tolerance": 35000,
        "use_admin_speed_limit": false
      }
    }
  }
}

Update a Monitor

This method enables users to modify the settings and parameters of an existing monitor. By using this method, users can make changes to the monitor's type, attributes, description, geofence associations, configurations for speed or idle events, among other properties of the monitor. This flexibility allows for updates and adjustments to the monitoring configuration based on changing requirements or evolving business needs.

PUT

https://api.nextbillion.io/skynet/monitor/{id}?key={your_api_key}

Request Parameter

Request Body

Response Schema

Sample Request

1
2
3
4
5
6
7
8
9
10
11
12
curl --location --request PUT 'https://api.nextbillion.io/skynet/monitor/3123a566-1c64-4ada-846c-d1e9f6bcc049?key=<your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
     "name": "Los Angeles Geofence ",
     "match_filter":{
      "include_all_of_attributes":{ 
                "driver_name": "Ron Taylor",
                "license": "AR 30 TR 8389",
                "shift_timing": "0900 - 1800"
        }
      }
}'

Sample Response

1
2
3
{
  "status": "Ok"
}

Get Monitor List

This method retrieves a list of monitors available in the system along with pagination information. It provides users with an overview of all the monitors that have been created. The method allows for easy access to monitor details such as their names, types, descriptions, and associated attributes. This information can be valuable for monitoring configurations, analyzing monitoring patterns and managing the monitoring system effectively.

GET

https://api.nextbillion.io/skynet/monitor/list?key={your_api_key}

Request Parameter

Response Schema

Sample Request

curl --location 'https://api.nextbillion.io/skynet/monitor/list?key=<your_api_key>&pn=1&ps=4&sort=created_at:desc'

Sample Response

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
{
  "status": "Ok",
  "data": {
    "list": [
      {
        "id": "36c171d5-bdf1-47c2-9531-4c02820ab70e",
        "type": "speeding",
        "name": "Delivery Monitor The Ritz Hotel, Los Angeles",
        "description": "Track speeding activity of the delivery vehicle",
        "geofences": null,
        "tags": [],
        "created_at": 1694619817,
        "updated_at": 1694672213,
        "match_filter": {
          "include_all_of_attributes": {
            "driver_contact_no": "321-902-838",
            "driver_name": "James Smith",
            "license": "4 ES 7167",
            "vehicle_type": "Delivery"
          }
        },
        "speeding_config": {
          "customer_speed_limit": 18,
          "time_tolerance": 35000,
          "use_admin_speed_limit": false
        }
      },
      {
        "id": "1d1b20f1-5f33-4a37-833d-119898b18ff9",
        "type": "idle",
        "name": "Pickup Monitor The Ritz Hotel, Los Angeles",
        "description": "Track idle activity of the pickup vehicle",
        "geofences": null,
        "tags": [],
        "created_at": 1694541966,
        "updated_at": 1694614513,
        "match_filter": {
          "include_all_of_attributes": {
            "driver_contact_no": "422-761-938",
            "driver_name": "John Blake",
            "license": "2 BR 2049",
            "vehicle_type": "Pickup"
          }
        },
        "idle_config": {
          "distance_tolerance": 30,
          "time_tolerance": 10000
        }
      },
      {
        "id": "dae3b4bd-2402-4b53-83dd-c094b79d02cc",
        "type": "enter_and_exit",
        "name": "Monitor The Ritz Hotel, Los Angeles",
        "description": "Track activity related to free staff transportation service",
        "geofences": [
          "7d1b861c-67b8-4128-aef8-179a605263c4"
        ],
        "tags": [],
        "created_at": 1694419506,
        "updated_at": 1694419506,
        "match_filter": {
          "include_all_of_attributes": {
            "driver_contact_no": "422-583-651",
            "driver_name": "John Luther",
            "license": "2 DS 3236",
            "vehicle_type": "SUV"
          }
        },
        "geofence_config": {
          "geofence_ids": [
            "7d1b861c-67b8-4128-aef8-179a605263c4"
          ]
        }
      },
      {
        "id": "a39ef490-130b-4f03-aa91-434ae82ee757",
        "type": "speeding",
        "name": "Sheraton Grand Los Angeles monitor",
        "description": "Track activity related to free staff transportation service",
        "geofences": null,
        "tags": [],
        "created_at": 1694080768,
        "updated_at": 1694080768,
        "match_filter": {
          "include_all_of_attributes": {
            "driver_contact_no": "595-232-764",
            "driver_name": "Jack Shipley",
            "license": "7 BA 3352",
            "vehicle_type": "mini-bus"
          }
        },
        "speeding_config": {
          "customer_speed_limit": 10,
          "time_tolerance": 6000,
          "use_admin_speed_limit": false
        }
      }
    ],
    "page": {
      "total": 4,
      "offset": 0,
      "page": 1,
      "size": 4,
      "hasmore": false
    }
  }
}

Delete a Monitor

This method allows users to delete an existing monitor from the system. It is useful when a monitor is no longer needed or if changes to monitoring requirements are necessary. By removing a monitor, users can effectively stop tracking specific activities associated with that monitor.

DELETE

https://api.nextbillion.io/skynet/monitor{id}?key={your_api_key}

Request Parameter

Response Schema

Sample Request

curl --location --request DELETE 'https://api.nextbillion.io/skynet/monitor/675c983c-8147-4d5a-9c14-d754a8e57c0d?key=<your_api_key>'

Sample Response

1
2
3
{
  "status": "Ok"
}

Capturing Events

Live Tracking API’s Asset and Monitor methods allow users to create events when a desired activity is exhibited by an asset. The events created can be accessed in 2 ways. First is the Event History of an Asset, which would give the requested events upon receiving a request. Another method is by using webhooks.

Webhooks are used for event-driven communication between applications. Therefore, webhooks play a key role in implementing live tracking based alerts. Let’s dive into the webhook capabilities offered by NextBillion’s Live Tracking API.

How does the Live Tracking API use a webhook?

A webhook enables Live Tracking API to push event information in real-time to the user’s application. An HTTPS POST method is used to deliver the JSON payload to a configured webhook URL as soon as an event is created. Live Tracking API currently supports following events:

enter - Entry of an asset into a given geofence.
exit - Exit of an asset from a given geofence.
speeding - Asset is moving at a speed more than the specified limit
idle - Asset is not moving or idle.

The information related to these events can be used to execute multiple actions in user’s application systems as needed.

Steps to set-up a webhook

Get a webhook URL from the application that needs to receive the event information.
Configure the URL to receive events from Live Tracking API using the configurations method listed below.
Use the Test Webhook Configuration method to verify that the webhook is able to receive events from the Live Tracking service.
Start receiving information about the Live Tracking events through a HTTPS POST request on the webhook URL.

Live Tracking API’s configuration methods

Users can view and modify the webhooks configured for their account or key through the config methods available as part of NextBillion’s Live Tracking API.

Add or Update Webhook Configuration

Use this method to add new or modify the existing webhooks. The new or the modified webhooks can be passed using the request body as an array of strings. Multiple webhooks can be configured to receive the events. Please note that the webhooks will be configured to the key that is passed as a request parameter. They will be eligible to receive only those events, through a POST request, that are associated with the same key.

PUT

https://api.nextbillion.io/skynet/config?key={your_api_key}

Request Parameter

Request Body

Response Schema

Sample Request

1
2
3
4
5
6
7
8
curl --location --request PUT 'https://api.nextbillion.io/skynet/config?key=<your_api_key>'
--header 'Content-Type: application/json'
--data-raw '{
    "webhook":[
        "https://my-company/api/testhook",
        "https://my-company/api/testhook1"
    ]
}'

Sample Request

1
2
3
{
  "status": "Ok"
}

Get Webhook Configuration

Please note that the webhooks returned are associated with the key that is used in the input request. The webhooks returned can receive the event information through a POST request.

GET

https://api.nextbillion.io/skynet/config?key={your_api_key}

Request Parameter

Response Schema

Sample Request

curl --location --request GET 'https://api.nextbillion.io/skynet/config?key=<your_api_key>'

Sample Response

1
2
3
4
5
6
7
8
{
  "status": "Ok",
  "data": {
    "config": {
      "webhook": ["https://my-company/api/testhook", "https://my-company/api/testhook1"]
    }
  }
}

Test Webhook Configuration

Use this method to test the webhooks configured. Once the webhooks are added the users can validate, if they are able to receive the events data, through the test service. The Live Tracking API will send a sample event to all the configured webhook URLs if they are validated successfully. Please note that API response will always be Ok and the actual event information will be sent to all the configured webhooks. Please verify the information received.

POST

https://api.nextbillion.io/skynet/config/testwebhook?key={your_api_key}

Request Parameter

Response Schema

Sample Request

curl --location --request POST 'https://api.nextbillion.io/skynet/config/testwebhook?key=<your_api_key>'

Sample Response

1
2
3
{
  "status": "Ok"
}

Sample Event schema

This section gives a walkthrough of the POST request schema that will be used to carry the event information. Let’s take a look at the properties:

Example Event

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
{
  "events": [
    {
      "asset_id": "f1ceb76d-2665-4f72-bc56-aae91c4953e3",
      "geofence_id": "350706bf-cc3b-4e74-a66c-c7f050944c47",
      "monitor_id": "8a8ecd4b-f8b2-49ed-8097-b114ce53e4db",
      "monitor_tags": ["america", "newyork"],
      "event_type": "enter",
      "timestamp": 1662629479859,
      "triggered_timestamp": 1662629479810,
      "triggered_location": {
        "location": {
          "lat": 40.7128,
          "lon": -74.0059
        },
        "timestamp": 1662629479859,
        "accuracy": 20,
        "speed": 20,
        "bearing": 30,
        "altitude": 10,
        "meta_data": {
          "test": "test"
        }
      },
      "prev_location": {
        "location": {
          "lat": 40.7127,
          "lon": -74.0049
        },
        "timestamp": 1662629478659,
        "accuracy": 20,
        "speed": 21,
        "bearing": 31,
        "altitude": 10,
        "meta_data": {
          "test": "test"
        }
      }
    }
  ],
  "timestamp": 1662629482859,
  "extra": { "speed_limit": 25 }
}

Leveraging event information

Once the event information is received on the webhook URL and the JSON payload is parsed into the end application, it can leveraged in multiple ways as per the business need - notifications can be triggered for certain sensitive events on any desired medium, or the event information can be stored in a database, or the information can be pushed to a dashboard for real-time decision making etc.

Namespaces

Namespaces help users to create multiple keys under one parent organization. This feature allows users to share the capabilities of Live Tracking API with multiple consumers (customers, teams, departments etc) while ensuring isolation of underlying data - a key belonging to a namespace can access the data belonging to that namespace only. However, using namespaces is not mandatory to access the capabilities of Live Tracking services. Once a request is successfully submitted, the service responds with a unique key for the namespace along with an expiration date for the key.

Please note that once the namespace keys are created, users can manage them through the APIs & Services > Credentials section of their NextBillion Console.

POST

https://namespaces.nextbillion.io/namespaced-apikeys?{namespace}&key={your_api_key}

Request Parameter

Response Schema

Sample API Request

Let’s create a namespace called sample_namespace for a key represented by <your_api_key>.

curl --location --request POST 'https://namespaces.nextbillion.io/namespaced-apikeys?key=<your_api_key>&namespace=sample_namespace'

Sample API Response

1
2
3
4
5
6
{
   "kid": "af088b64d85e4c2896034d34383deb8b",
   "namespace": "sample_namespace",
   "created_at": "2023-11-21T04:29:15.868Z",
   "expire": "1716805800"
}

API Query Limits

Limitation for the attributes object:
- The maximum number of key:value pairs that can be added is 100.
- The overall size of the object should not exceed 65kb.
For smooth tracking experience, it is recommended to keep the location service of your GPS application to always ON for a constant stream of location data.
This page number parameter pn does not have a maximum limit per se, but would return an empty result set in case a higher value is provided when the result-set itself is smaller.
The maximum value for page size ps parameter is 100, except in case of Track locations of an Asset method where it is 500.
Only the updated_at or created_at fields can be used for sorting the results using the sort parameter.
Search methods will only return active assets in the results. An asset is considered active if it has been tracked at least once in the last 7 days.
In Around Search method, the maximum radius of the search area can not be more than 5000 meters.
In Polygon Search and Bound Search methods, the maximum area of the “polygon” and “bound box”, respectively, can not be more than 3000 km².
The maximum number of assets that can be created for a namespace is 10000, if namespaces are being used. If not, then the same limit applies to an organization as well.
The maximum number of monitors that can be created for a namespace is 200, if namespaces are being used. If not, then the same limit applies to an organization as well.
NextBillion.ai allows a maximum rate limit of 6000 queries per minute or 100 queries/second for continuous requests. Note: We can increase the quota if needed, on request. Contact support@nextbillion.ai for more details.

API Error Codes

Response Code	Description	Additional Notes
200	Normal success case.	Normal success case.
400	Input validation failed.	There is a missing or an invalid parameter or a parameter with an invalid value type is added to the request.
401	APIKEY not supplied or invalid.	This error occurs when the wrong API key is passed in the request or the key is missing altogether.
403	APIKEY is valid but does not have access to requested resources.	You might be querying for a geographical region which is not valid for your account or requesting a service which is not enabled for you.
404	Requested host/path not found.	This error occurs when a malformed hostname is used.
422	Could not process the request.	The request could not be completed for the given set of locations or parameter configuration.
429	Too many requests.	QPM reached or API request count quota reached.
500	Internal Service error.	There was an internal issue with NextBillion.ai services. You can reach out to support@nextbillion.ai for an explanation.
460	Incorrect device ID	This error occurs when an unmatched device is used to upload locations for an asset. Please use the correct device ID which is bound to the asset.