Track distance for financial 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

  1. 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)

  2. 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.

  3. 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 distance

  1. 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.

Tracking gap

  • 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.

Tracking gap

Outage reasonMessage to your app user
Tracking service terminatedPlease turn off power saver settings and apps
Location service disabledPlease enable location service on your phone
Location permissions deniedPlease allow location persmissions for the app
App terminated by OS rebootPlease open app after phone reboot
Location unavailableDO NOT force kill app
note

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.

Tracking distance

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.

App user drive distance

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.

App user drive distance

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.

App user drive distance

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.

Webhook: Trip completed payload
{
"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.

Trip drive distance in scoreboard

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.

App user drive distance

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.

Geofence Hit Real Time with Metadata

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 visted 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.

App user drive distance

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.

App user drive distance

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.

Custom Event Marker in Dashboard

note

Thomas, please update the image. Tracking stopped and unknown segments are distracting.

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.

drive distance

Insights

The insights page shows you the distance between the geotags in the "Route distance" field and can be exported to CSV.

drive distance

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.