API Reference
Insights
Insights
The Insights API enables a deeper understanding of device activity and usage patterns. This API provides access to a variety of metrics, including trips, stops, alerts, hours of operation, and areas of interest, among others. These insights are generated using Hapn algorithms and machine learning techniques.
Alerts
One of the key features of the platform is its ability to generate near real-time alerts based on specific conditions. These conditions can be based on device location, battery level, speed, and many other parameters. When a condition is met, the system generates an alert and sends it to the user through various channels, such as email, SMS, or push notifications. The Hapn platform supports different alert types, which are all available through the API as alert records.
Example
{
...
"result": {
"items": [
...
{
"alertType": "GeofenceEntry",
"created": "2022-07-29T13:49:02.218Z",
"sendTime": "2022-07-29T13:49:02.218Z",
"userId": "2bcbcw23-24c8-4cda-9e16-0a7836dcd007",
"imei": 866258043384068,
"address": "5880 Green Blvd, Naples, FL 34116",
"value": 377489,
"coordinates": {
"latitude": 26.199173,
"longitude": -81.725688
},
"isBuffer": false,
"isNotification": true,
"clientId": 5689098,
"alertId": 1136639121
},
...
],
}
}Activities
The Hapn platform automatically classifies tracker behaviors based on their movement patterns into trips and stops. Using the API, developers have access to the list of trips and stops for a given date range. These activities include information about the distance traveled, duration, and location where they occurred. In the case of trips, the actual positions are also available.
Example
{
...
"result": {
"items": [
...
{
"created": "2022-07-29T23:51:01.044Z",
"imei": 865134050130039,
"clientId": 5689098,
"completionStatus": "Completed",
"distance": 0.012,
"duration": 15,
"endAddress": "5214 Green Way, Naples, FL 34110",
"endCoordinates": {
"latitude": 26.285988,
"longitude": -81.75134
},
"startCoordinates": {
"latitude": 26.285952,
"longitude": -81.751346
},
"endDate": "2022-07-29T23:43:43.000Z",
"startDate": "2022-07-29T23:43:28.000Z",
"startAddress": "5216 Green Way, Naples, FL 34110",
"tripId": 115696639121,
"type": "Trip"
},
...
],
}
}Device Metrics
Device metrics are aggregations of device data over time. They can include distance traveled, time spent moving or inside boundaries, and hours of operation. These metrics vary depending on the type of device.
Example
{
...
"result": {
"imei": "865134050130039",
"clientId": 457025096,
"metricActualStartDate": "2020-02-25T18:00:00Z",
"metricActualEndDate": "2020-02-25T22:00:00Z",
"timeMovingSeconds": 381,
"totalMessages": 179,
"distanceTraveledMiles": 1.576058702134033,
"timeInBoundaries": [
{
"boundaryId": 323151,
"duration": 33
},
{
"boundaryId": 331646,
"duration": 392
}
]
}
}Areas of Interest
An "Area of Interest" (AOI) refers to a specific geographical region generated by a machine learning clustering algorithm. The algorithm analyzes GPS location data collected from devices and identifies groups of data points that have a spatial and temporal relationship with each other. Using the location and size of these clusters, the algorithm generates an AOI. These AOIs help to uncover the movement patterns of the trackers.
Example
{
...
"result": {
"items": {
"imei": 865134050130039,
"area": 14.156012912280858,
"density": 15,
"minUTCTime": "2021-12-02T17:44:02.000Z",
"maxUTCTime": "2022-01-02T18:08:42.000Z",
"daysOfWeek": [
"Saturday",
"Sunday",
],
"diameter": 33.46870680704336,
"clusterId": 457025096,
"from": "2021-12-01T13:04:27.000Z",
"to": "2022-01-04T22:44:39.000Z",
"meanSpeed": 5.999999920527141,
"minSpeed": 1.7000000476837158,
"maxSpeed": 10.399999618530273,
"geometry": [
[
-81.78437042236328,
26.395950317382812
],
[
-81.78469848632812,
26.396013259887695
],
[
-81.78439331054688,
26.39596176147461
],
[
-81.78437042236328,
26.395950317382812
]
],
"address": "10201 Cape Roman Rd, Bonita Springs, FL 34135",
"hoursOfDay": [
...
],
"centroidLat": 26.39597511291504,
"centroidLon": -81.78448740641277,
"minTimeOfTheDay": "2022-01-02T19:44:02.000Z",
"maxTimeOfTheDay": "2022-01-02T19:44:02.000Z",
"place": {
"formatted_address": "10201 Cape Roman Rd, Bonita Springs, FL 34135",
...
},
"category": "low-speed",
"clientId": 5689098,
"createdAt": 1642938639209000
},
}
}Endpoints
The device insights are available through these endpoints:
- Get Device Alerts Get the list of the alerts generated by a device.
- Get Device Activities Get the list of activities generated by a device.
- Get Activity Positions Get a list of the positions for a given activity.
- Get Device Metrics Get the location and operation metrics for a given device.
- Get Areas of Interest Get a list of the areas of interest generated by a device.