Export tracking data by day

Introduction

HyperTrack manages your live location data starting with the in-app SDK, storing it securely on our servers, streaming it to you in real time through webhooks, and provisioning access to your location data through data tables, and APIs.

Location tracking data for your devices, trips, geofences and geotags are available as:

  • Insights: Up to 30 days of aggregates and averages for users, trips, geofences, or geotags
  • Views: Day-wise list of devices that you intended to track, along with their tracking status and movement timelines on the map
  • APIs: Data for individual devices, trips and geofences
  • Webhooks: Real-time data for locations, device status (activity changes and outage), geotags, trips (arrival and delays), and geofences (arrival and exits) streamed to your server

HyperTrack retains data available through insights, views and APIs for current month and one previous month.

But this is your data. And we, of course, let you download it to your own servers for archival and re-use.

Insights

Insights allows you to view aggregate KPIs for your app users, trips, geofences, and geotags. To get an aggregate overview of your business operations, check out Insights.

Insights Main

Region and Metadata selector

The first thing that you will see when you launch a new insights page is the region and metadata selector. With this selector, you can dial your query to a region, restricting the data returned to that which is located in the selected area. Or, you can select metadata belonging to your app users, to see data for a group of devices only.

Metadata and Region Selector

Group by Tags

When the data loads for your insights query, you will see your metadata keys as a list of tags.

Group by tags

By selecting a tag, the data shown in the table below will be organized into folders (shown as grey rows with 'show more'), and the numerical fields will shift to be totals or averages. If an additional tag is selected, sub-groups will show once the top level row is expanded, so you can have full visibility of your data in relation to business logic. At any time you can disable the group by selecting the first tag in the tags that you selected.

Insights Main

Exporting Insights

Click the "Export" button on the top right corner of the insights page to get insights data as a CSV file. Share this data with your ops teams to measure productivity, improve efficiency, reward top performers, and fix bad behavior in the system. Exports of insights will respond to the selection of App Users, Trips, Geofences, Geotags, region, or device metadata. See here for instructions on how to set up device metadata.

Insights Main

App Users Insights

App Users insights give a snapshot of your user's performance over the selected time range. In addition to the columns listed below, you will also see your app user's metadata listed alongside, so that you can sort and make groups using it. Grouping by app user metadata allows you to slice and dice HyperTrack data by the attributes that you use to segment users. Data will be included for all trips, geofences, and geotags that your users may have been assigned, or triggered.

ColumnDescription
RatingOverall tracking score of this app user. 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
App UserApp user name
Tracking %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
TripsNumber 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 user. Shown when using trips
Arrived %Percentage of trips that arrived at the destination. A high arrival percentage indicates that the app user made it to the destination more often. Use this to measure address accuracy and user behavior. Shown when using trips
On time %Percentage of trips that arrived on time. A high on-time percentage indicates that the app user arrived at the destination on or before the scheduled time. Use this to measure punctuality. Shown when using trips
GeofencesNumber of geofences the app user visited. Geofences typically corresponds to relevant locations in your business, and a higher number corresponds to more such visits
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
Route (avg)Arithmetic mean of the distance traveled to get to the geofence
Idle TimeTotal time the user was stopped on the way to geofences. A higher number corresponds to less efficient travel to get to the geofence
GeotagsNumber 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. Shown when using geotags
StopsTotal stop duration by the app user on this day. Use this to review time spent at work or customer locations
StepsTotal steps walks by the app user on this day. Use this to review the amount of movement at work or customer locations

Trip Insights

Trip insights provide aggregates of your app user's trips performed in the selected time range. In addition to the columns listed below, you will also see your trip's metadata listed alongside, so that you can sort and make groups using it. Grouping by trip metadata to slice your data by the attributes that segment the journies of your day to day operations. An additional group by tag of 'App User' is provided to slice your data by user.

ColumnDescription
DateDate and time of trip start
App UserThe app user's name
Trip DurationThe trip's elapsed duration. Use this to flag abnormally short trip durations for work orders you expected a full day's worth of work
Time Spent at destinationThe amount of time the app user spent at the destination. User this to flag shorter or longer than expected time at a destination
ArrivedBoolean of whether the app user arrived at the destination
On TimeBoolean of whether the app user was on time upon arriving at the destination
Completed at destinationBoolean of whether the trip was completed at the destination
Drive DistanceTotal distance driven by the app user in the trip's range from start to completion. Use this to review expenses, payouts and reimbursements related to distance driven
Step CountTotal steps walked by the app user in the trip's range from start to completion. Use this to review the amount of movement at work or customer locations

Geofences Insights

Geofences insights proivides aggregates of the geofences that have been hit by your app users in the selected time range. In addition to the columns listed below, you will also see your geofence's metadata listed alongside, so that you can sort and make groups using it. Grouping by geofence metadata to slice your data by the attributes that segment the key locations of your business. An additional group by tag of 'App User' is provided to slice your data by user.

ColumnDescription
Geofence MarkersThe number of times this geofence was visited
App UsersThe app users that visited this geofence
Avg Time SpentThe average time app users spent at the geofence. Use this to flag abnormally long stays and to optimize micro-operations on-site
Avg Route DurationThe average time app users spent getting to the geofence. Use this to flag unexpectedly delayed routes and to improve route efficiency.
Avg Route Idle DurationThe average time app users spent stopped while en-route to the geofence. Use this to flag longer than expected delays.
Avg Route DistanceThe average distance app users travelled getting to the geofence. Use this to flag longer than expected route and to improve route efficiency.

Geotags Insights

Geotags insights proivides aggregates of the geotags that have been logged by your app users in the selected time range. In addition to the columns listed below, you will also see your geotag's metadata listed alongside, so that you can sort and make groups using it. Grouping by geotag metadata to slice your data by the attributes that segment the key moments of your day to day operations. An additional group by tag of 'App User' is provided to slice your data by user.

ColumnDescription
DateDate and time of the geotag
App UserThe app user's name
Avg Time SpentThe average time app users spent at the geofence. Use this to flag abnormally long stays and to optimize micro-operations on-site
Route DurationThe time that the app user spent between the previous geotag to this geotag. Use this to flag unexpectedly delayed routes and to improve route efficiency.
Route DistanceThe distance that the app user travelled between the previous geotag to this geotag. Use this to flag longer than expected route and to improve route efficiency.

Location and marker data

The insights view in our web dashboard allows your operations team 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.

The 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, and device status (activity and outage) - to be consumed by your 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 user in the insights view. Each user contains the following fields:

FieldDescription
ratingOverall tracking score of this app user. 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_nameApp user name
device_idDevice Identifier that uniquely identifies a device within HyperTrack
tracking_percentagePercentage 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.
custom custom_marker_countNumber 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_distanceArithmetic 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_countNumber 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 user.
arrival_percentagePercentage of trips that arrived at the destination. A high arrival percentage indicates that the app user made it to the destination more often. Use this to measure address accuracy and user behavior.
on_time_percentagePercentage of trips that arrived on time. A high on-time percentage indicates that the app user arrived at the destination on or before the scheduled time. Use this to measure punctuality.
drive_distanceTotal distance driven by the app user on this day. Use this to review expenses, payouts and reimbursements related to distance driven.
stop_durationTotal stop duration by the app user on this day. Use this to review time spent at work or customer locations.
stepsTotal steps walks by the app user on this day. Use this to review the amount of movement at work or customer locations.
locationsObject representing the location time series of the trips. Follows GeoJSON geometry of type LineString
markersArray of markers. The markers show you visited geofences, geotags as well as details about the device status.
tripsArray of trips per device

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 user 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": "custom_marker" // marker type (always "custom_marker" for geotags)
}

Device status markers

The device status markers explains what the device was doing at a given time. It gives details about the tracking status (active when the device 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)
}

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.