Get Insights from tracked data
Introduction
Use Insights to drill down in to business KPIs.
- Use Driver Insights for KPIs related to drivers
- Use Orders Insights for KPIs related to orders
- Use Geofences Insights for KPIs related to geofence visits
- Use Geotags Insights for KPIs related to geotags
- Use Nearby Insights for KPIs related to Nearby Searches
All Insights views are available as embeddable views and CSV exports.
Metadata Filters
Insights may be viewed by drivers, orders, geofences, geotags or nearby searches. For each entity, you may select metadata based filters to view specific segments of data. Filters for state, city and country are provided out of the box to help you get started fast.
Search for specific data
You may search against the values of any column like Driver, Order Destination, etc to produce an even more finely filtered view as needed.
Driver Insights
Driver Explore views provide a snapshot of your drivers’ performance over a selected time range. In addition to the columns listed below, you will also see driver profile metadata listed alongside, so that you can sort and make groups using it. Grouping by driver metadata allows you to slice and dice data by the attributes that you use to segment drivers.
| Column | Description |
|---|---|
| Driver | App user name |
| Map | See the driver timeline on a map |
| Outages | Outages that happened during selected period and impacted the tracking rate. For a full list of outages check out the Track App Users guide. |
| Tracking Rate | Percentage of the time when device was tracked, relative to the time you intended to track the device that day. Disabling permissions for example would reduce the percentage. Use this to review devices that did not track as intended, understand the reasons why, and take corrective action |
| Tracked | Total tracked duration |
| Active | Total duration the driver was active |
| Activity | Time spent in different types of activities |
| Drives | Total drive distance |
| Time Spent (avg) | Arithmetic mean of the time spent at the geofences. A higher time spent at geofences corresponds to more time spent at your relevant locations |
| Estimate | Estimated Distance |
| Stops | Total stop duration by the app user on this day. Use this to review time spent at work or customer locations |
| Steps | Total steps walks by the app user on this day. Use this to review the amount of movement at work or customer locations |
Orders Insights
Orders insights shows data about the orders serviced by your drivers within the selected time range. In addition to the columns listed below, you will also see your order metadata table, so you can analyze specific groups of orders as needed.
| Column | Description |
|---|---|
| Date | Date and time of order delivery start |
| Order ID | The id of the order you provided HyperTrack |
| Destination | The order destination |
| App User | The driver this order was dispatched through |
| Service Time | The service time provided for the order |
| Delay | Delay in the order completion if the scheduled at was provided |
| Deviation | Deviation in the order destination and the actual completion marker |
| Arrived | THe time the order arrived in the destination geofence |
| On Time | Boolean of whether the app user was on time upon arriving at the destination |
| Completed at destination | Boolean of whether the order was completed at the destination |
| Trip Id | The id of the trips that the order was a part of |
| Order Autocancelled | Whether the order was autocancelled when the trip was completed or not |
| Distance | Route distance travelled to the order |
| Duration | Route duration travelled to the order |
| Scheduled at | The time the order was scheduled |
| Completed at | The time the order was compeleted |
Geofences Insights
Geofences insights provide aggregates of the geofences that have been visitd by drivers in the selected time range. In addition to the columns listed below, you will also see your geofences’ metadata to support analysis.
| Column | Description |
|---|---|
| Arrived | The time of the Geofence visit |
| Visited time | The duration of the geofence visit |
| Driver | The name of the driver who visited the geofence |
| Route time | The average time app users spent getting to the geofence. Use this to flag unexpectedly delayed routes and to improve route efficiency. |
| Route Idle time | The average time app users spent stopped while en-route to the geofence. Use this to flag longer than expected delays. |
| Route Distance | The average distance app users travelled getting to the geofence. Use this to flag longer than expected route and to improve route efficiency. |
| Geofence ID | The ID of the geofence visited |
Geotags Insights
Geotags insights provide aggregates of the geotags that have been logged by your drivers in the selected time range. In addition to the columns listed below, you will also see your geotags' metadata to support analysis.
| Column | Description |
|---|---|
| Date | Date and time of the geotag |
| Driver | The name of the driver who created the geotag |
| Route time | The average time drivers spent enroute prior to the geotag. Use this to flag unexpectedly delayed routes and to improve route efficiency. |
| Route Distance | The average distance drivers travelled getting to the geotag location. Use this to flag longer than expected route and to improve route efficiency. |
| Geotag ID | The ID of the geotag created |
Nearby Insights
Nearby Search insights provide aggregates of the nearby searches by your account in the selected time range. In addition to the columns listed below, you will also see your nearby search metadata to support analysis.
| Column | Description |
|---|---|
| Date | Date and time of the nearby search |
| Search Results | The number of results returned |
| Radius | The radius of the search |
| Destination | The destination of the order around which the search was made |
| State | The geographical state of the order destination |
Export Search Insights
You can export Insights into your favorite BI tool.
The “Export” button at the top right corner of the Insights page produces a CSV file, created in response to the selection of Drivers, Trips, Geofences, Geotags, Nearby Searches and filters. Learn more about working with driver and profile metadata.
The Insights view allows operations teams to download a CSV file and share across your organization. While this allows the ops team to use location data without engineering help, some use cases need more detailed data.
HyperTrack’s data export API gives you all the insights data plus the data the insights view is based on—locations and marker data for geotags, trips, geofences, nearby searches and device status (activity and outages)—to be consumed by data and engineering teams.
To get the data, call our history API:
curl -u {AccountId}:{SecretKey} https://v3.api.hypertrack.com/devices/history/2020-05-15
{
"url": "https://live-misc.s3.amazonaws.com/device-leaderboard-api/42256004-3cee-4953-883c-1f57f0e602c9/2020-05-15T00%3A00%3A00%2B00%3A00-2020-05-16T00%3A00%3A00%2B00%3A00-28f53956-4b94-45f2-b3ac-7d944a7e7bc1.json.gz?AWSAccessKeyId=123&Signature=123%2B6ZYezNLickN%2FTK%2BX4&Expires=1591142754"
}
The API call returns a pre-signed URL that you can easily download. Here is a full shell example using jq:
curl -u {AccountId}:{SecretKey} https://v3.api.hypertrack.com/devices/history/2020-05-15 \
| jq .url \
| xargs curl -o out.json.gz
Note the link is pre-signed and will expire after 60min. Once you downloaded the file, use your favorite gzip tool (e.g., gunzip) or library (e.g., python gzip) to decompress to get the full json file.
The returned json file contains an array of devices, which each entry given you details about the device. Here is a sample in pseudo json (with comments added for clarity):
[
{
"rating": 5, // Overall tracking score of this app user
"device_name": "Wonder Women", // App user name
"device_id": "123E4567-E89B-12D3-A456-426614174000", // Device Identifier that uniquely identifies a device within HyperTrack
"tracking_percentage": 100, // Percentage of the time when device was tracked
"custom_marker_count": 0, // Number of app events resulting in geotags
"custom_marker_mean_distance": null, // Arithmetic mean of distance between geotags
"trip_count": 1, // Number of trips
"arrival_percentage": null, // Percentage of trips that arrived at the destination
"on_time_percentage": null, // Percentage of trips that arrived on time
"drive_distance": 1234, // Total distance driven by the app user on this day in meter
"stop_duration": 0, // Total stop duration by the app user on this day.
"steps": 0, // Total steps walks by the app user on this day
"locations": { // array of GeoJSON locations
"type": "LineString",
"coordinates": [
[
-123.456789, // longitude
12.345678, // latitude
257, // altitude in meter
"2020-02-20T01:02:03.000Z" // timestamp in ISO 8601 format
]]
},
"markers": [
{
"marker_id": "b6914fe1-8776-4a19-ad4f-09e1af954481", // unique identifier for this marker
"type": "device_status", // marker type, can be device_status, geofence or trip_marker
"data": {
"value": "active",
"start": { // details about the start of the marker such as location and time
"recorded_at": "2020-02-20T01:02:03.000Z",
"location": {
"geometry": {
"type": "Point",
"coordinates": [
-123.456789, // longitude
12.345678, // latitude
]
},
"recorded_at": "2020-02-20T01:02:03.000Z"
}
},
"end": { // details about the end of the marker such as location and time
"recorded_at": "2020-02-20T02:02:03.000Z",
"location": {
"geometry": {
"type": "Point",
"coordinates": [
-123.456789, // longitude
12.345678, // latitude
]
},
"recorded_at": "2020-02-20T02:02:03.000Z"
}
},
"activity": "drive", // activity type (drive, walk, stop)
"distance": 1234, // distance of this activity in meter
"duration": 3600 // duration of this activity in seconds
}
}],
"trips": [
{
"trip_id": "bc7c745c-b684-495b-aff3-8ad48a078982", // unique trip identifier
"started_at": "2020-02-20T01:32:03.000Z", // time trip was started
"completed_at": "2020-02-20T02:34:03.000Z", // time trip was completed
"device_id": "DC12E5E2-84CA-40B6-BACA-46A6EAB21C38", // unique device identifier
"views": { // links to web views
// embed_url: add to your dashboard
"embed_url": "https://embed.hypertrack.com/trips/bc7c745c-b684-495b-aff3-8ad48a078982?publishable_key=your_ht_publishable_key",
// share_url: share with your end customers
"share_url": "https://trck.at/nx6jtddo3d93da23"
},
"metadata": { // trip metadata, as provided at trip creation time
"foo": "bar"
}
"destination": { // trip destination, as provided at trip creation time
"geometry": {
"coordinates": [
-123.456789, // longitude
12.345678, // latitude
],
"type": "Point"
},
"radius": 30,
"scheduled_at": "2020-02-20T02:34:03.000Z", // time the trip was scheduled to arrive
"arrived_at": "2020-02-20T02:30:00.000Z", // time user arrived at destination
"exited_at": "2020-02-20T02:33:00.000Z" // time user exited destination again
}
}
]
}
}]
The json file contains a json array, with each item representing one driver in the insights view. Each driver contains the following fields:
| Field | Description |
|---|---|
| rating | Overall tracking score of this driver. This is computed using tracking percentage, and behavior for trips, geotags and geofences. A 5-star rating means the user performed perfectly as expected. Use this to measure productivity and reward top performers. |
| device_name | Driver name |
| device_id | Device Identifier that uniquely identifies a device within HyperTrack |
| tracking_percentage | Percentage of the time when driver was tracked, relative to the time you intended to track the device that day. Disabling permissions for example would reduce the percentage. Use this to review drivers that did not track as intended, understand the reasons why, and take corrective action. |
| custom custom_marker_count | Number of app events resulting in geotags. The number of markers typically correspond to your orders, and depends on your use case and implementation. Use this to review how much work was done by each user. |
| custom_marker_mean_distance | Arithmetic mean of distance between geotags. A higher number means there was a larger average distance covered from marker to marker. This indicates lower efficiency where more work needs to happen per unit distance, and higher efficiency where more distance implies more work done. Use this to measure route efficiency. |
| trip_count | Number of trips. The number of trips typically corresponds to your orders, routes or work days, depending on your use case and implementation. Use this to review how much work was done by each driver. |
| arrival_percentage | Percentage of trips that arrived at the destination. A high arrival percentage indicates that the drivers made it to the destination more often. Use this to measure address accuracy and driver behavior. |
| on_time_percentage | Percentage of trips that arrived on time. A high on-time percentage indicates that the driver arrived at the destination on or before the scheduled time. Use this to measure punctuality. |
| drive_distance | Total distance driven by the driver on this day. Use this to review expenses, payouts and reimbursements related to distance driven. |
| stop_duration | Total stop duration by the driver on this day. Use this to review time spent at work or customer locations. |
| steps | Total steps walks by the driver on this day. Use this to review the amount of movement at work or customer locations. |
| locations | Object representing the location time series of the trips. Follows GeoJSON geometry of type LineString |
| markers | Array of markers. The markers show you visited geofences, geotags as well as details about the device status. |
| trips | Array of trips per device |
Device status markers
The device status markers explains what the driver was doing at a given time. It gives details about
the tracking status (active when the driver is tracking properly, inactive when the device can't be tracked or
disconnected when HyperTrack lost device-server communications). For active devices, we furthermore split the
markers into activities like stop, drive or walk:
{
"data": {
"value": "active", // can be either active, inactive or disconnected
"start": { // data about the start of the marker
"recorded_at": "2020-07-08T00:00:00.000Z", // start time of marker
"location": {
"geometry": {
"type": "Point",
"coordinates": [
-122.294234, // longitude
37.865077 // latitude
]
},
"recorded_at": "2020-07-07T23:59:49.245Z" // time the location was recorded
}
},
"end": { // data about the end of the marker
"recorded_at": "2020-07-08T01:10:56.167Z",
"location": {
"geometry": {
"type": "Point",
"coordinates": [
-122.294234, // longitude
37.865077 // latitude
]
},
"recorded_at": "2020-07-08T01:10:53.165Z" // time the location was recorded
}
},
"address": "123 Main St, Springfield, USA", // address, available for stops
"activity": "stop", // activity type (stop, walk, drive)
"steps": 177, // number of steps during this activity
"duration": 4256 // duration of the activity
},
"marker_id": "20766acc-db0c-45e6-9fc0-35dd59dff3d0", // unique marker id
"type": "device_status" // marker type (always "device_status" for device status markers)
}
Geofence markers
For every visit to one of your geofences, we add a marker to the markers array. The geofence marker gives you detailed data about the geofence arrival, exit, time spent inside and how the driver got to this geofence. Here is an example:
{
"data": {
"arrival": { // location and time of geofence arrival
"location": {
"geometry": {
"type": "Point",
"coordinates": [
-123.456789, // longitude
12.345678, // latitude
1231 // altitude in meter
]
},
"recorded_at": "2020-02-20T01:02:03.000Z"
}
},
"geofence": { // geofence as setup via API
"geometry": {
"type": "Point",
"coordinates": [
-123.456789, // longitude
12.345678, // latitude
]
},
"geofence_id": "aeb8ace8-6973-41fd-81e7-a003a2eadf1f",
"radius": 50,
"metadata": {
"foo": "bar"
}
},
"exit": { // location and time of geofence exit
"location": {
"geometry": {
"type": "Point",
"coordinates": [
-123.456789, // longitude
12.345678, // latitude
1231 // altitude in meter
]
},
"recorded_at": "2020-02-20T02:02:03.000Z"
}
},
"duration": 3600, // duration inside geofence in seconds
"route_to": { // data how the user got to this geofence, based on previous geofence
"distance": 1337, // distance in meters of travel to this geofence
"duration": 1800, // duration in seconds of travel to this geofence
"start_location": { // start location of route_to calcuation
"geometry": {
"type": "Point",
"coordinates": [
-122.294234, // longitude
37.865077 // latitude
]
},
"recorded_at": "2020-02-20T01:32:03.000Z"
}
}
},
"marker_id": "34dda70e-c89d-430d-ab30-07322ff2deef", // unique marker id
"type": "geofence" // marker type (always "geofence" for geofence markers)
Geotag markers
Geotags let you geotag import app events. The geotag markers provide detailed data such as location and metadata provided:
{
"data": {
"location": { // location the geotag marker was created; geojson point
"coordinates": [
-122.294234, // longitude
37.865077 // latitude
],
"type": "Point"
},
"metadata": { // metadata passed in when creating the geotag
"Route type": "Car",
"Station Id": "1BCX",
"Package Id": "1WUXZ1393",
"Route Id": "2248311",
"Action Type": "Reached Doorstep"
},
"recorded_at": "2020-02-20T01:32:03.000Z", // timestamp the geotag was cretaed
"route_to": { // data on the route to this geotag (from previous geotag)
"distance": 1337, // distance in meters of travel to this geotag
"duration": 1800, // duration in seconds of travel to this geotag
"start_location": { // start location of route_to calcuation
"geometry": {
"type": "Point",
"coordinates": [
-122.294234, // longitude
37.865077 // latitude
]
},
"recorded_at": "2020-02-20T01:32:03.000Z"
}
}
},
"marker_id": "b0cbe3ac-1118-49bd-a179-89baa072cc62", // unique marker id
"type": "trip_marker" // marker type (always "trip_marker" for geotags)
}
Questions?
For urgent needs to help you get your data, or for questions or comments on this topic, please do not hesitate to contact us.