Track live route, ETA, delays with Trips
Introduction
Order tracking with live location is a popular use case across industries and regions. From high growth startups to enterprises delivering products and services to customers, "where's my order?" is a moment of anxiety for customers and ops teams. Operations teams can proactive handle delays & no shows, reduce customer support cost, improve NPS scores, and power a great customer experience with this feature.
Pickups, deliveries and visits in your system would translate to trips with destination & scheduled time in HyperTrack. Upon starting a trip, the API generates a share URL for use in the customer experience, and embed URL for use in ops dashboards. = Destination is required to estimate routes & ETAs with live traffic conditions and re-routes. Using scheduled_at is required to notify delays and generate on-time arrival scores. Live data for trips is available for native tracking experiences through callbacks in iOS and Android SDKs. Trip data is used to generate insights using route efficiency, on-time arrival, completion at destination, and time spent at destination. Past trips may be replayed for non-repudiation in case of escalations or other exceptions.
Create and track trips with multiple orders
HyperTrack released a new update for Trips API to empower you to create and track a single trip with multiple orders.
You can perform the following operations with Trips API:
- Create a trip with multiple orders: This API method allows you to create a trip with multiple orders, where each order contains a destination.
- Complete or cancel an order inside an ongoing trip: These API methods can be called once the delivery for the order is either complete or otherwise canceled. Once the order is canceled, it is permanently removed from the user's trip route, a new route is planned, and ETAs are updated.
- Enable or disable an order: Use these API calls whenever delivery recipient is not available and thus removing immediate requirement for package delivery until further notice.
- Update existing orders or add another to the existing trip: Use this API whenever you need to modify a given order attributes, such as its destination coordinates due to, for example, customer's address update. With add API you may add another order to the list of orders for the trip.
- Change sequence of orders inside the trip: Use ths operation to reorder previously given orders. For example, an operations manager may discover an urgent need to raise delivery priority for a given customer and thus trigger a trip route change for the delivery driver.
Start trip with multiple orders
To start a trip with multiple orders, you must define an order payload that is structured as follows:
Note that order_id must be a unique identifier for your order, while destination is required and scheduled_at and service_time parameters are optional.
Please see code examples below:
POST
https://v3.api.hypertrack.com/trips
- Shell
- JavaScript
- Python
- Java
- PHP
- Ruby
Process webhook notifications for trips with multiple orders
Each action performed on with Trips API results in a webhook notification to your configured end point. Please refer to this guide for more information.
important
Whenever you use scheduled_at for an order in the trip with multiple orders, you will get delay notifications webhooks whenever HyperTrack detects that delivery driver is not able to deliver a given order by scheduled time.
Get live route and ETA
Start trip to destination
Use Trips API to start trip when the order is assigned and complete the trip when the order is done. Starting and completing trips will automatically start and stop tracking on the assigned user's device. This way, you manage device tracking through just one API.
note
Automatically starting tracking on trip creation requires you to integrate silent push notifications for iOS and Android. The device will start tracking (unless already tracking) when you start a trip for the device. The device will stop tracking when all active trips for device are completed. HyperTrack uses a combination of silent push notifications and sync method on the SDK to ensure that tracking starts and stops on the device as expected.
The destination object is required to estimate route and ETA. The object should include a GeoJSON object called geometry with a Point that represents the location coordinates. By default, destination gets set with a circular arrival radius of 30 meters.
important
Location coordinates in geoJSON require longitude before latitude. To change the default radius, you can pass a radius property (interger in meters) to the destination object.
POST
https://v3.api.hypertrack.com/trips
Please see code examples below:
- Shell
- JavaScript
- Python
- Java
- PHP
- Ruby
Get views and estimates
Once the trip is created successfully, the Trips API responds with an active trip object that returns the original payload with additional properties. Additional properties include an estimate (route/ETA) to destination, mobile-friend share URL for customers, and desktop-friendly embed URL for ops dashboards.
The destination object in the response will now contain address field which is an address that is reverse geocoded from the destination coordinates submitted in the trip creation request above. You can use this address to show the destination to the user after creating the trip.
important
A device may be track multiple active trips at the same time. For example, pickup and dropoff for the same order may be tracked simultaneously, with one being tracked by the merchant, the other being tracked by the customer, and both being tracked by the ops team.
In the views object:
share_urlprovides a short URL with a mobile-friendly order tracking view for customersembed_urlprovides an embed view with a desktop-friendly order tracking view for ops managers
In the estimate object:
arrive_atshows estimated time of arrival (ETA) as UTC timestamproutecontains the following data:distanceshares estimated route distance (in meters)durationandremaining_durationshare actual and remaining durations (in seconds)start_addressandend_addressdisplay reverse geocoded place names and addresses for trip start, complete and intermediate stops (based on activity)polylinecontains an array of coordinates for the estimated route from the live location to the destination as polyline in GeoJSONLineStringformat. It is an array of Point coordinates with each element linked to the next, thus creating a pathway to the destination.
note
Complete trip
When to complete a trip is an important decision.
Option 1: Rely on the app user to mark the order done, and use that event to trigger trip completion. This way, the trip tracks until the user marks it done.
Option 2: Rely on arrival or exit at destination to trigger trip completion. To avoid the risk of premature completion, especially in case of user going in and out of the location, add a fixed time period after arrival or exit.
Either way, please remember to complete your trips!
important
HyperTrack will complete your trip automatically after 24 hours if it is still active
Please review the complete request in Trips API.
POST
https://v3.api.hypertrack.com/trips/{trip_id}/complete
Once this method is invoked, HyperTrack will proceed to complete your trip thereby stopping tracking your app user if there are no other active trips for the user.
note
Share live views with customers
Trips API returns share_url upon successful creation of the trip. The share_url is build for sharing with customers. While the trip is ongoing, customers will see a mobile-web view of the order's live location with route and ETA to destination. For completed trips, customers will see the trip summary from start to complete.
Share URL has the following structure: https://trck.at/{7_digit_tracking_id}.
This makes it a total of 23 characters, and therefore a friendly URL to share via text or other messengers. Share URLs stay accessible permanently and show trip summary after trip completion.
Customize tracking view
HyperTrack offers you options that allow you to create customizations for share URLs with ETA for your customers.
Customize with url query parameters
The share URL experience can be modified with the following query parameters appended to it:
layerminiicon
Layer query parameter
This parameter offers you options to customize map layer used to render the share URL experience. The layer parameter can have the following values:
base- default choice for the share URLstreet- additional street detail is shown in the mapsatellite- satellite view is used as shown in an example below
For example:
To illustrate, please review corresponding images below for each of the layer option value usage.
Icon query parameter
This parameter offers you options to customize how your tracked device appears on the map. The icon parameter can have the following values:
carbikebus
Mini query parameter
mini- this parameter allows to hide trip details used to show in the map as shown below.
Customize with reserved trip metadata keys
In order to perform such customizations, you may use these reserved trip metadata keys to help define public share URL experience. Use Trips API with these reserved trip metadata keys when creating a trip.
ht_view_text_ongoing- defines a title of an ongoing delivery, for example, "Your order for xyz is on the way!"ht_view_text_completed- defines a title for a delivery that was completed, for example, "Your order for xyz is delivered!”ht_view_href_completed- provides an option to the customer to go back to the link which exposes order details in your delivery appht_view_href_text_completed- once this option is used, your completed trip will have a title defined by the value of this keyht_view_hide_summary_completed- this option allows you to remove completed trip summary from the view which is included by default
For example the payload to create a trip with some of this metadata can be like this:
Embed live views in dashboards
Trips API returns embed_url upon successful creation of the trip. The embed_url is built for embedding in ops dashboards. While the trip is ongoing, dashboard users will see a desktop-web view of the order's timeline, live location, arrival status, estimated route and ETA to destination. For completed trips, dashboard will see the trip summary with a detailed timeline from start to complete.
While shareable views are accessible to everyone with the URL, embed views includes your publishable key. Although the permalink of each URL in the dashboard includes the publishable key, your publishable key is available in the Setup page of your dashboard.
The embed URL format is https://embed.hypertrack.com/trips/{trip_id}?publishable_key={publishable_key}
important
To identify a HyperTrack Trip with your application order, and destination with your order location, please use the metadata object for trip and destination respectively.
Inline frames
Please see how to use inline frames to create embeddable operations dashboards.
Hide trip completion button
This parameter offers you option to hide trip completion button. Trip completion button is shown by default. The icon parameter can have the following value:
false
Track delays and no-shows
Use scheduled_at to track delays and no-show with actionable reasons. For orders with time slot or end time commitments, it is important to proactively manage delays and potential no-shows. Delays might trigger an automatic workflow, notify operations managers or reset customer expectations. Trips API includes the scheduled_at field to specify the time commitment inside the trip creation payload.
POST
https://v3.api.hypertrack.com/trips
- Shell
- JavaScript
- Python
- Java
- PHP
- Ruby
You can also provide a scheduled_at property (in ISO8601 format) to the destination to indicate a scheduled arrival at the trip destination. Use this when the order has a time commitment to the customer. When set, HyperTrack will send trip delay webhooks when the device is highly likely to miss that time commitment.
note
HyperTrack continually adds new features to help improve operational efficiency for business assets on the move. New webhooks and additional fields or objects may be added to webhook payload structures, so please keep in mind as you implement webhook data processing.
With scheduled_at, operations pre-emptively act on delays and catch potential no-shows before they escalate. Here are five examples of delays with actionable reasons.
Driver is delayed on the way to destination
Delay is likely when the estimated route and ETA with live traffic conditions suggests a delay past scheduled time of arrival. Delays are notified over webhooks. Delays are also flagged in ops views for each driver, order, and entire fleet, so ops managers can keep an eye on delays and take corrective action.
Customer support can replay trips to confirm customer and driver claims when escalations happen. Replays enable non-repudiation because these views can be shared as links with either party as needed.
Driver is moving away from destination
This example of a no-show is likely when the estimated route distance and ETA to destination keeps increasing despite movement, and the driver seems to have no intention to get to the destination. In the example above, the green square on the right indicates the destination. The driver is moving, though not toward the destination. ETA becomes irrelevant.
There is the occasional issue with incorrect customer addresses, or a higher priority task that needed to be fulfilled before heading to the destination. In such scenarios, being aware of the driver's intent on the way is useful to proactively address a potential escalation.
Driver is delayed and stationary
HyperTrack uses activity transitions to infer that the driver is stationary, or driving, or walking. No-show is likely when the driver is stationary at a place and the order is running delayed beyond schedule time of arrival. The delay webhook includes activity so you may take corrective action for this specific scenario, such as sending a text message or notification to the driver, or re-assigning the order.
Activity transition data provided by the phone OS is noisy. HyperTrack makes it more accurate with additional processing. This way, you can rely on this data to take action. For instance, benign stops at a traffic light are eliminated while stops at places are retained.
Driver disables location permission
HyperTrack detects changes in user device and app level permissions to infer driver's intent to be tracked while fulfilling an order. No-show is quite likely when the driver denies location permission after order assignment or while on the way.
Drivers often mention excessive battery drain and data usage as reasons to turn off permission. However, for most Android and iOS devices, the additional battery and data usage due to background location tracking is marginal. Custom ROMs and old devices might have higher battery impact. In general, HyperTrack data suggests high correlation between denied permissions and low productivity.
Driver becomes untrackable on the way
Device health and battery status is used to infer driver becoming un-trackable while the driver is on the trip. In this example, the driver's battery went in the red and subsequently, the driver went off the radar.
When the phone is charging again, and the driver opens the app to re-connect with services, HyperTrack captures these events and syncs up the batched locations when available. This helps operations get the extra visibility around what might have happened during the outage.
Get real-time status and summary
In your business workflow, you may need to take actions depending on the status of the trip you created for your app user. HyperTrack provides real-time updates for your app via webhooks that deliver to you important events associated with your trip.
Get status on webhooks
Trip events are posted whenever a trip is started, a specified device enters or exits the destination, a trip with a scheduled arrival is estimated to be delayed, and when a trip is completed. Events provide the device triggering the event, the trip, event type (create, destination enter, destination exit, delay, or completion), and trip metadata defined during start.
Currently, HyperTrack will send notifications triggered by:
- Trip start: For every new trip, start events are posted.
- Destination arrival: Trips destination arrival events are posted when devices enter a specified destination.
- Destination exit: Same as arrival events, but posted when devices exit the specified destination.
- ETA changes: As trip progresses it provides you real-time ETA changes
- Trip delays:Trip delay events are posed for trips with a scheduled arrival time. Delay events are send as soon as the estimated time of arrival is past the scheduled time.
- Trip completion: For every completed trip, completion events are posted.
All trip updates will include the update type, created_at, device_id, trip_id and trip_metadata at the very least.
note
Please review the Webhook guide to understand what webhooks are and how they can be leveraged in addition to the HyperTrack APIs.
It is up to you to decide how to utilize trip updates. To give you an idea, the following can be done:
- complete trips based on custom logic
- update database records of trips
- send mobile device notifications
- update real-time views and maps
- start custom processes (training of AI models, send custom emails, etc)
- get the distance traveled during the trip as soon as it's completed as part of the webhook payload
Trigger notifications based on trip activity
A common use case is to leverage trip events to trigger contextual, location-aware notifications in web or native applications. To make these types of notifications possible, you should maintain a list of devices (users), a list of trips, and notification templates for trips events (start, destination enter/exit, completion) to be used as notification message.
It is suggested to leverage device metadata that can be set either through mobile SDKs or through Devices API in combination with trips metadata to establish all relevant information in order to send highly contextualized notifications.
More context is provided based on the update type. Please take a look at the trip webhooks references for more details.
Trip start
Please see an example for the trip start webhook payload. Once the trip is created, you may be able to get Trips API to receive trip estimate and expected route to the destination.
Destination arrival
The payload below is an example of destination arrival, as denoted by destination_arrival value field inside data object.
important
Please note that once the user arrived at the trip destination, the trip is not considered complete until Trip Complete API call is made. For example, in the case if you want to track the user time at the destination until the user exits the destination, you may want to wait for the destination exit event to get time spent at the destination and then complete the trip.
Destination exit
The payload below is an example of destination exit, as denoted by destination_exit value field inside data object.
The data object has the arrival/exit locations and the duration the user stayed at the destination.
Note exit location may be empty when the marker was closed due to an outage event.
ETA change
In a business operations workflow, you may have more than one trip with destination and ETA scheduled for today for a given app user. For example, your app user may be a service technician visiting multiple sites for the day or grocery delivery driver who has a number of drop off locations to visit.
To help understand which trip is most relevant to your customer as your app user is on the route, HyperTrack provides an ETA change via a new webhook for your ongoing trips.
This webhook payload has eta_change inside its value field. You will get this real-time webhook update for all of your trips with destination each time ETA is updated.
The payload below is an example of a trip ETA change, as denoted by remaining_duration and remaining_distance inside data object.
You may be able to use these values to determine when to start notifying your customers and also share real-time locations of your service workers.
Trip delay
As explained below you may specify when your app user is expected to reach a destination for your scheduled trip. In case if there is a delay, you will get a webhook update with this payload below. Note that value inside data object is delayed and arrive_at shows the new expected arrival time for your app user.
If the trip gets delayed further, you will receive additional updates via this trip delay webhook until the trip is completed.
Trip completion
When the trip is completed, you will receive the trip completion webhook. Key metrics such as distance or duration_at_destination is part of the payload.
Get summary from API
Get Trips API
GET Trips APIs to retrieve active and completed trip data.
For all active and completed trips, a summary object is returned as part of the trip response payload. If trips is still in active state, the summary object will contain the latest from the app user's device.
GET
https://v3.api.hypertrack.com/trips/{trip_id}
Additionally, you can get trip data for multiple actively tracked trips.
GET
https://v3.api.hypertrack.com/trips
You will notice that this GET Trips API endpoint will return only active trips. This is a deliberate design choice to show the most relevant trips, out of potentially thousands of completed trips stored in your HyperTrack account.
You can set the status path parameter to completed to get past trips.
Trip summary payload
Trip summary includes trip & device IDs, start & complete timestamps, share & embed views, and summary object. Summary object includes start & complete addresses, duration, distance, steps, time spent at destination, location timeseries, and markers. Markers include activities, outages and destination arrivals & exits.
A sample trip summary is shared below. To understand the trip response payload data in full, please visit this reference documentation section.
Directly use HyperTrack Live app
If you do not have your own app to add the HyperTrack SDK, you may start tracking your fleet with HyperTrack Live app for iOS and Android listed in the public stores.
From your dashboard Team Page you can add drivers on your fleet via Share invite link. This will allow you to send an invitation a deep link to download the app and get automatically added to your account.
Once your drivers install HyperTrack Live app, you can immediately manage tracking your fleet with HyperTrack Trips API.
Extend and build your own app
HyperTrack Live is available in open source for you to fork or clone and start building your own app.
This approach is best for product development teams who are starting to build an app for their business and want to kickstart with an open sourced app built with HyperTrack. Start with our GitHub repos on Android or iOS.
Questions?
Please do not hesitate to contact us with your questions and feedback.