Track orders 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.
Create trips with at least one or multiple orders with Trips API. Pickups, deliveries and visits in your system would translate to trips with orders. Each order has a destination and optionally scheduled time.
Create and manage orders with Trips API
You can perform the following operations with Trips API:
- Create a trip with one or 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.
- 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.
- Snooze or re-add an order:
- Use these API calls whenever delivery recipient is not available and thus removing immediate requirement for package delivery until further notice. Snoozing an order disables it while re-adding the order enables it back to be included in the trip. The app user's trip route and ETA are updated accordingly.
- 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.
Create and track trips with one or multiple orders
For each trip, Trips API:
- Requires at least one order with a destination to estimate routes & ETAs with live traffic conditions and re-routes
- Offers optional
scheduled_at
that is required to notify about order delays and generate on-time arrival scores - Generates a share URL for each order for use in the customer experience
- Creates an embed URL where an entire trip with one or more orders can be viewed and embedded for use in ops dashboards
- Automatically starts tracking on the device on trip creation unless the device is already tracking
Live data for trips is available for native tracking experiences through callbacks in iOS and Android SDKs. You can also use GraphQL API to stream live data for trips as well.
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.
important
To automatically start tracking you must integrate silent push notifications for iOS and Android. 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.
Start trip with one or multiple orders
Payload structure
To start a trip with an order or more, you must define an order payload that is structured as follows:
Parameter service_time
specifies time in seconds that driver expects to service an order. 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.
Code examples
Please see code examples below:
POST
https://v3.api.hypertrack.com/trips
- Shell
- JavaScript
- Python
- Java
- PHP
- Ruby
important
Location coordinates in GeoJSON object are called geometry
with a Point
that represents the location coordinates. Location coordinates require longitude before latitude. To change the default radius, you can pass a radius
property (integer in meters) to the destination object.
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 with route and ETA for each order destination, mobile-friendly share_url
for each order customer. Use desktop-friendly embed_url
inside views
object for ops dashboards to view the entire trip status in real-time.
The order destination
object in the response will now contain address
field which is an address that is reverse geocoded from the order destination
coordinates submitted in the trip creation request. You can use this address
to show the order destination to the user after creating the trip.
For each order, estimate
object contains:
arrive_at
shows estimated time of arrival (ETA) as UTC timestamproute
contains the following data:distance
shares estimated route distance (in meters)duration
andremaining_duration
share actual and remaining durations (in seconds)start_place
andend_place
display reverse geocoded place names and addresses for trip start and order desination locationspolyline
contains an array of coordinates for the estimated route from the live location to the destination as polyline in GeoJSONLineString
format. It is an array of Point coordinates with each element linked to the next, thus creating a pathway to the destination.
note
Complete trip
You must complete trip in your business workflow. HyperTrack gives you control to track multiple arrivals and exits into the trip order destination and retain full control when to complete the trip.
For example, you may want to account for these use cases:
- Your driver passes through the order destination while looking for parking and coming back
- When you want to know when the driver exited the destination after visit or delivery is done
- When you want to track multiple arrivals and exits over a work shift
- When you want to track when and where your driver completes tasks while trip is active
- When you may want your driver to be dispatched one or more orders to be added to the same trip via Nearby API
To complete order, use Trip order complete API.
Once all orders in trips are either completed or cancelled, you may complete trip with this Trips API. If you have orders in the trip that have not yet been completed, this API call will automatically complete all outstanding orders for you.
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
Completing orders
In order to complete orders in the trip:
You can 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.
You can rely on arrival or exit at order destination to trigger trip completion. To avoid the risk of premature completion, especially in case of user going in and out of the location, you can add a fixed time period after arrival or exit.
important
Either way, please remember to complete your trips!
Otherwise, HyperTrack will complete your trip automatically after 24 hours if it is still active and send you a notification.
Track order delays and no-shows
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.
Use scheduled_at
property in ISO8601 format to the order destination to indicate a scheduled arrival. Use this when the order has a time commitment to the customer. When set, HyperTrack will send order delay webhooks when the app user is highly likely to miss that time commitment.
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 order 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 order 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
Actions performed by the driver with an order results in a webhook notification to your configured end point. Please refer to this guide section for more information. You can use the order status update notifications to add logic to your business workflows.
important
Whenever you use scheduled_at
for an order in the trip, you will get delay notifications webhooks whenever HyperTrack detects that delivery driver is not able to deliver a given order by scheduled time.
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 orders
- 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
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 views for each order & entire trip embed views, and summary object.
Summary object includes start & complete addresses, duration, distance, steps, time spent at each order destination, location timeseries, and markers. Markers include activities, outages and order 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.
Share live views of orders with customers
Trips API returns share_url
for each customer's order destination upon successful creation of the trip.
The share_url
is built 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 the order destination.
For completed orders, customers will see the trip summary from starting location to the order destination.
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 order trip summary after order 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:
layer
mini
icon
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:
car
bike
bus
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 of trips in operations dashboards for ops managers
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, ops dashboard users will see a desktop-web view of the trip'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
Questions?
Please do not hesitate to contact us with your questions and feedback.