Track Orders 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 proactively handle delays & no shows, reduce customer support cost, improve NPS scores, and power a great customer experience with this feature.Use Trips to track orders with live routes, ETAs, delays, arrivals, deviations and more. Examples of orders are pickups, deliveries, dropoffs, visits, tasks, jobs, or any future work expected to happen at a destination by a scheduled time (optional).
Create Trips with Orders
Each trip:
- Automatically controls tracking on the device upon trip creation and completion
- Generates order completion markers that are used to generate deviations from destination
- Returns a mobile-friendly share URL per order for customers to get a real-time order tracking experience
- Returns a dashboard-friendly embed URL per trip for ops managers to get a real-time view of the trip's progress
Trips containing a fixed sequence of orders are created by passing in the "route":"fixed" flag to the trip creation request.
Fixed route trips additionally provide:
- Estimated routes & ETAs with live traffic conditions and re-routes
- Notifications about order delays and on-time arrival scores when optional
scheduled_atattribute is provided
In this sample of an embed URL for a trip created with "route":"fixed" flag, you can see the estimated route and arrival times.
And here is a screenshot of the corresponding mobile-friendly share url:
For orders that don't need to be fulfilled in a fixed sequence and ETAs are not required, create trips with
"route":"flexible" flag.
Flexible routes give you the same mobile-friendly share URL per order for customers and dashboard-friendly embed URL for ops managers, but don't create ETAs, estimated routes nor delay notifications.
For flexible route trips, the optional "scheduled_at" parameter is not relevant as the orders can be completed in any sequence.
Here is the same trip as above, but created with the "route":"flexible" flag. As you can see, there is no estimated arrival time nor any estimated routes.
And here is a screenshot of the mobile friendly share url for the same trip. There are no ETAs nor estimated routes shared.
Order data within Trips 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.
To create a trip, 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.
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.
Share Order tracking views 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.
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.
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:
layerminiiconmap_onlydestination_iconshow_pickuppickup_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:
carbikebus
Mini query parameter
mini- this parameter allows to hide trip details used to show in the map as shown below.
Map_only query parameter
map_only- this parameter can be used to hide the trip card shown on the map.
Destination_icon query parameter
destination_icon- this parameter can be used to show a custom icon for the destination on the map.
Show_pickup query parameter
show_pickup- this parameter can be used to show the pickup location on the map.
Pickup_icon query parameter
pickup_icon- this parameter can be used to show a custom icon for the pickup location on the map.
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 Trip views in ops 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, 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
Get Order routes, estimates and views
Once the trip is created successfully, the Trips API responds with an active trip object that returns the original payload with additional properties and the trip starts tracking immediately.
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_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_placeandend_placedisplay reverse geocoded place names and addresses for trip start and order desination locationspolylinecontains 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.
important
If the app user on the trip is detected to be more than four hours away from the order destination, the estimate object is returned empty in the response.
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 Order status and Trip 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.
Manage Orders and Trips
You can perform the following operations with Trips API:
Complete or Cancel Order
Complete or Cancel an order inside an ongoing trip. Once the order is canceled, it is permanently removed from the trip route, a new route is planned, and ETAs are updated. Orders are either completed or canceled by app users in the app, or by other users in other business applications. Occassionally, you might complete orders based on arrival or exit at order destination. It is recommended to use this as a fallback mechanism only. Drivers may be driving through order destinations before returning to fulfill the order, or never reach destination
Update or Add Order
- Update existing orders or Add another order to the existing trip. Use the update method whenever you need to modify order attributes such as destination, scheduled_at or metadata. Use the add method to add another order to the sequence of orders in a trip. This will modify the routes and ETAs of pending orders.
Snooze or Re-Add Order
Snooze or Re-add orders when the customer is unavailable and there is a need to change things ad-hoc. 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 Order sequence
Change sequence of orders inside the trip 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.
Complete Trip
Complete trip once all orders in the trip are completed or canceled. If you have orders in the trip that have not yet been completed, this API call will automatically cancel all outstanding orders for you.
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.
If the user's device had automatically started tracking through Trips API, completing the Trip will automatically stop tracking the user's device.
note
While managing Orders and Trips, please account for the following use cases:
- Use arrival and exit notifications with caution. Drivers may be passing through order destination to look for parking or fulfilling another order before returning
- Completing the order upon arrival or at the destination will stop exit notifications for that order destination
- Some visits or gigs might require tracking multiple visits (arrivals and exits) to the destination
- Order completion marker helps compute deviation from destination and can be an important input to driver behavior or address accuracy
- On-demand orders involving pick and delivery might require dispatch to Nearby users already on a trip, followed by adding orders to the trip.
Questions?
Please do not hesitate to contact us with your questions and feedback.