Automate distance-based payouts
Introduction
Actual distances covered by app users is an important input to financial systems for field workers. Distances are used to bill customers and pay out partners. This has direct financial impact for the business, and impacts customer and partner satisfaction. Both under-billing and over-billing have negative consequences for one side of the network, and negatively impact the aggregator business. Accurate distance computation for actual movement builds trust with customers and partners, and saves money by eliminating expensive maps costs involved in distance estimation. That means, a better solution at lower cost.
This guide explains how to get accurate distances for app users and orders. You may get distances between geofences and geotags as well.
How we calculate distance
HyperTrack SDKs generate location, activity and outage information from the device OS. Install the HyperTrack SDK to your native or hybrid app (or get our app for Android or iOS)
HyperTrack servers apply a variety of filters and transformations to improve location accuracy. The goal is to precisely compute the primary metric for financial payouts–actual drive distance. This is in stark contrast to the industry-wide usage of coarse estimates using maps.
Stop locations are excluded from distance computation and drive locations are map matched. Locations while moving on paths with no roads are smoothened using Kalman filters. The resulting timeline looks like this.
- Tracking gaps have a meaningful impact on distance accuracy. To address this problem, we detect gaps in real-time and classify them into system driven outages (due to device conditions like battery, OS, GPS availability, etc.) or user driven outages (app permissions, location disabled on device, app killed, etc.).
- System-driven outages: Our SDKs are reliable and apply techniques to ensure that location updates come as frequently as our needed to understand ground truth. However, the fragmented base of device manufacturers, custom Android ROMs, external environment, and unintended user behavior may lead to tracking gaps that make distance less usable. HyperTrack fills such gaps by estimating routes along the road and shows them as dotted lines in the views. Please see this guide for a full enumeration of all system outages.
- User-driven outages: Privacy rules by Android and iOS require that users retain control over the app's ability to use location. Users enjoy a varying degree of controls over permissions. HyperTrack differentiates between these reasons and posts them to you in real-time over webhooks. Distance estimates are not computed for these gaps. We recommend that you communicate with your app users about them. Please see this guide for a full enumeration of all user drive outages and our webhooks guide on how to receive outages notifications in real time.
| Outage reason | Message to your app user |
|---|---|
| Tracking service terminated | Please turn off power saver settings and apps |
| Location service disabled | Please enable location service on your phone |
| Location permissions denied | Please allow location persmissions for the app |
| App terminated by OS reboot | Please open app after phone reboot |
| Location unavailable | DO NOT force kill app |
To avoid violating user privacy and improve tracking rate, only track your app users during work by using Start tracking and Stop tracking APIs. Tracking outside work hours might lead to the users denying permissions or killing the app in ways it is hard to recover from.
Get app user distance using Devices
Get the distance driven for your app users, through app user timeline views, webhooks and Devices API.
Views
Once your device is tracking, go to your App user view and navigate to the app user timeline. Here you will see locations organized as a day-wise timeline of the app user's movement. Total distance driven including estimates for user-driven outages.
API
Location and distance has a lot of value on it's own, but to unlock the full potential of the data, most of our customers need the distance data in their own application database. HyperTrack has a set of APIs to make it easy to consume distance information along with the underlying location, activity and outage data.
The Device History API returns all the tracked data for an app user.
curl -u {AccountId}:{SecretKey} https://v3.api.hypertrack.com/devices/123E4567-E89B-12D3-A456-426614174000/history/2020-10-10
{
"completed_at": "2020-10-11T00:00:00.000Z",
"device_id": "123E4567-E89B-12D3-A456-426614174000",
"distance": 136308, // drive distance in meters
"duration": 86400,
"steps": 2290,
"locations": {
"coordinates": [...],
"type": "LineString"j
},
"markers":[...],
"started_at": "2020-10-10T00:00:00.000Z"
}
The distance field returns the total drive distance in meters. The breakdown of different activities is part of the markers array. In order to get all the data for all your app users on a given day as a single JSON file, you can use the Account export API.
Scoreboard
In our Scoreboard, you see the average distance driven by all app users on a given day along with trends for the last 7 or 30 days. Use this data to get a quick understanding how your fleet is performing daily.
Insights
In our Insights page, you can see the drive distances of each of your app users. Reports may be exported as a CSV file, for viewing in your favorite spreadsheets app or importing into other systems.
Get order distance using Trips
Trips allow you to track live route and ETA for orders. Trip summaries give you access to the distance traveled for the order–from start to completion of the trip. Order distances may be used to bill customers or payout partners or both.
Views
The Trip embed view gives you a visual representation of the Trip, showing all the locations, drive distance and distance breakdown by activity.
Webhooks
When the trip is completed, we send out a webhook to notify you about the trip completion. The distance is included inside the data field.
{
"created_at": "2020-10-10T12:13:14.000Z",
"data": {
"value": "completed",
"trip_id": "123E4567-E89B-12D3-A456-426655440000",
"trip_metadata": { "customer": "1234" },
"distance": 12578, // distance in meters
"duration": 3600, // total duration of the trip in seconds
"duration_at_destination": 903 // total time spent at destination in seconds
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "trip",
"version": "2.0.0"
}
API
To get the data, call the GET Trip API to retrieve all the trip data.
curl -u {AccountId}:{SecretKey} https://v3.api.hypertrack.com/trips/5ce3ec28-3d73-48c0-bf25-fca5563557c5
{
"trip_id":"5ce3ec28-3d73-48c0-bf25-fca5563557c5",
"device_id":"3318AB96-2B43-4BCE-8639-A48D020EEC72",
"started_at":"2020-05-09T06:18:11.541213Z",
"completed_at":"2020-05-09T06:18:27.653353Z",
"status":"completed",
"views":{},
"device_info":{},
"destination":{},
"summary":{
"locations":{
"type":"LineString",
"coordinates":[
...
]
},
"distance":1235, // drive distance in meters
"duration":3600, // total trip duration in seconds
"duration_at_destination": 305, // time spent at destination
"started_at":"2020-05-09T06:18:11.000Z",
"steps":0,
"completed_at":"2020-05-09T07:18:11.000Z",
"device_id":"123E4567-E89B-12D3-A456-426614174000",
"markers":[...]
},
"eta_relevance_data":{
"status":true
}
}
The trip summary follows the same format as the device history. To get the distance for a trip, use the returned summary.distance field.
Scoreboard
In the Scoreboard, you see the average distance of Trips. This represents the average distance driven per order.
Insights
Here you can see the drive distance for all Trips. This data can easily be exported into a CSV file using the export button.
Get distance between Geofences
To track the distance traveled between places of interest like warehouses, use Geofences. Once they are setup, every visit to any of the geofences gives you the distance and time it took the app user to reach the geofence. This represents the route efficiency for each place and productivity of app users.
Views
In the device web view, click on any visited geofence to see the metadata and the route_to with distance.
Webhooks
When an app user enters a geofence, we calculate route_to.distance and send this as part of the webhook.
[
{
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"data": {
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"marker_id": "00001111-3767-2c12-f4ad-e213c130b321",
"geofence_metadata": {
"station": "A"
},
"geometry": {
"type":"Point",
"coordinates": [-122.395223, 37.7947633]
},
"radius":50,
"arrival": {
"location": {
"type":"Point",
"coordinates": [-122.394223, 37.792763]
},
"recorded_at": "2019-07-01T13:45:00.000000Z"
},
"exit": {},
"duration": null,
"route_to": {
"duration": 3600,
"distance": 2374 // distance in meters
},
"value": "entry"
},
"location": {
"type": "Point",
"coordinates": [-122.394223, 37.792763]
},
"recorded_at": "2019-07-01T13:45:00.000000Z",
"created_at": "2019-07-01T13:46:00.000000Z",
"version": "2.0.0",
"type": "geofence"
}
]
API
The Device History API returns
all the tracked data for an app user, this includes visited geofences with the route_to distance.
curl -u {AccountId}:{SecretKey} https://v3.api.hypertrack.com/devices/123E4567-E89B-12D3-A456-426614174000/history/2020-10-10
{
"completed_at": "2020-10-11T00:00:00.000Z",
"device_id": "123E4567-E89B-12D3-A456-426614174000",
"distance": 136308, // drive distance in meters
"duration": 86400,
"steps": 2290,
"locations": {
"coordinates": [...],
"type": "LineString"j
},
"markers":[
{
"data": {
"arrival": {
"location": {
"geometry": {
"type": "Point",
"coordinates": [
-122.395223,
37.7947633,
301.39
]
},
"recorded_at": "2020-10-10T12:00:00.000Z"
}
},
"geofence": {
"geometry": {
"type": "Point",
"coordinates": [
-122.395223,
37.7947633
]
},
"geofence_id": "3de08b30-dda8-443e-a602-0d98eba41a30",
"radius": 50,
"metadata": {
"warehouse_id": "CA-1235",
"warehouse_name": "SF main"
}
},
"route_to": {
"duration": 52529,
"distance": 1225 // distance from previous geofence
},
"exit": {
"location": {
"geometry": {
"type": "Point",
"coordinates": [
-122.395223,
37.7947633,
300.12
]
},
"recorded_at": "2020-10-10T13:00:00.000Z"
}
},
"duration": 3600
},
"marker_id": "df9d58e1-08de-4bcc-bccb-220b61e739fd",
"type": "geofence"
},
... // more markers
],
"started_at": "2020-10-10T00:00:00.000Z"
}
Scoreboard
In our Scoreboard, you see the average route_to distance for Geofence visits. This represents the average distance driven per visit.
Insights
Here you can see average route_to distance for Geofences visited by your users. This data can easily be exported into a CSV file using the export button.
Get distance between Geotags
Need to know the distance between work performed in the app? Integrate HyperTrack geotags to your app and consume the data over webhooks, views and APIs. Geotag combines the app event with the location where it happened, computes distance from the previous Geotag, and tracks deviation from expected location. If your app user is temporarily offline, Geotags get captured on the device and then synced up with the server when the connection is restored.
Views
Geotags show in user views as part of the user timeline.
Each app event is denoted as an interactive blue marker on the timeline and map, numbered in the order visited by user. Once you zoom in and click on the Geotag you are interested in, you can see the card with Geotags and the route_to data showing the distance traveled to this Geotag from the previous Geotag.
Webhooks
If your app business workflow requires real-time tracking of distance between app events, get Geotags on webhooks.
Not only do you get back the payload data your app user generated from the mobile app, you also get route_to data which contain distance in meters, duration in seconds, start_location from the previous app event for which distance and duration is generated, as well as recorded_at timestamp which captures the time this app event was received from your mobile app.
{
"created_at": "2019-07-01T14:01:00.000000Z",
"recorded_at": "2019-07-01T14:00:00.000000Z",
"data": {
"metadata": {
"Route type": "Car",
"Station Id": "1BCX",
"Package Id": "1WUXZ1393",
"Route Id": "2248311",
"Action Type": "Reached Doorstep"
},
"route_to":{
"distance": 238,
"duration": 63,
"start_location": {
"geometry": {
"coordinates": [
-6.271,
57.6398983
],
"type": "Point"
},
"recorded_at": "2019-07-01T13:52:08.213000Z"
}
}
},
"location": {
"type": "Point",
"coordinates": [
-6.2755,
57.6398983
]
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "geotag",
"version": "2.0.0"
}
API
Additionally, you can get this data for a single user by using the Device History API. Or for reporting and analytics purposes, use the Account export API.
In the example below, you can see the payload data your app user generated, as well as route_to with the distance data and location that is recorded for this app event.
{
...
"data": {
"location": {
"coordinates": [
77.5671771,
13.0709144
],
"type": "Point"
},
"metadata": {
"Route type": "Car",
"Station Id": "1BCX",
"Package Id": "1WUXZ1393",
"Route Id": "2248311",
"Action Type": "Reached Doorstep"
}
"recorded_at": "2020-03-10T02:01:59.978000Z",
"route_to": {
"distance": 1243,
"duration": 577,
"start_location": {
"geometry": {
"coordinates": [
77.569829,
13.0655947
],
"type": "Point"
},
"recorded_at": "2020-03-10T01:52:08.213000Z"
}
}
},
"type": "trip_marker" // geotags are called "trip_marker" in summary
...
}
Scoreboard
The Scoreboard shows you the average distance between Geotags. This represents the average distance per app event.
Insights
The insights page shows you the distance between the geotags in the "Route distance" field and can be exported to CSV.
Connect your QuickBooks account to automate financial payouts
Connect your existing QuickBooks account with HyperTrack to automatically capture and expense time your employees spend visiting customer sites and expense travel time between their site visits.
To get started, go to your HyperTrack Dashboard Setup page to connect your QuickBooks account with a few clicks. Once connected, deploy HyperTrack Visits App to your employees.
Each of their visit time and metadata are sent to QuickBooks as time activity. You can use QuickBooks reports to pull down their accurate, automatically captured, travel time and distance and easily automate payouts.
To learn more about QuickBooks and HyperTrack integration, please visit this guide.
Questions?
If you have any questions or comments on any of the topics above, please do not hesitate to contact us.