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:

{
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "orders": [
    {
      "order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
      "destination": {
        "geometry": {
          "type": "Point",
          "coordinates": [-122.398096, 37.793038]
        },
        "address": "420 Montgomery Street, San Francisco, CA 94108, United States",
        "radius": 50
      },
      "scheduled_at": "2021-02-18T14:30:00.000Z",
      "service_time": 300
    },
    ...
  ]
}

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

// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);

let tripData = {
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "orders": [
    {
      "order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
      "destination": {
        "geometry": {
          "type": "Point",
          "coordinates": [-122.398096, 37.793038]
        },
        "address": "420 Montgomery Street, San Francisco, CA 94108, United States",
        "radius": 50
      },
      "scheduled_at": "2021-02-18T14:30:00.000Z",
      "service_time": 300
    },
    {
      "order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
      "destination": {
        "geometry": {
          "type": "Point",
          "coordinates": [-122.404514, 37.793738]
        },
        "address": "600 Kearny St, San Francisco, CA 94108, United States",
        "radius": 50
      },
      "scheduled_at": "2021-02-18T15:10:00.000Z",
      "service_time": 500
    },
    {
      "order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
      "destination": {
        "geometry": {
          "type": "Point",
          "coordinates": [-122.406215, 37.794271]
        },
        "address": "756 Grant Ave, San Francisco, CA 94108, United States",
        "radius": 50
      },
      "scheduled_at": "2021-02-18T15:25:00.000Z",
      "service_time": 200
    }
  ]
};

hypertrack.trips.create(tripData).then(trip => {
  // Trip created
}).catch(error => {
  // Error handling
})

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.

HTTP 201 - New trip with orders

{
  "trip_id": "4359cc65-90dd-4b2b-875b-26e6d2eba11d",
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "completed_at": null,
  "started_at": "2021-02-18T14:00:00.000Z",
  "status": "active",
  "views": {
    "embed_url": "https://embed.hypertrack.com/dkdkddnd"
  },
  "orders": [
    {
      "order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
      "destination": {
        "geometry": {
          "type": "Point",
          "coordinates": [-122.398096, 37.793038]
        },
        "address": "420 Montgomery Street, San Francisco, CA 94108, United States",
        "radius": 50
      },
      "scheduled_at": "2021-02-18T14:30:00.000Z",
      "service_time": 300,
      "started_at": "2021-02-18T14:00:00.000Z",
      "completed_at": null,
      "status": "ongoing",
      "share_url": "https://trck.at/abcd53",
      "delayed": False,
      "arrived_at": null,
      "exited_at": null,
      "estimate": {
        "arrive_at": "2021-02-18T14:20:00.000Z",
        "route": {
          "distance": 14666,
          "duration": 2884,
          "remaining_duration": 1560,
          "start_place": "333 Post St, San Francisco, CA 94108, United States",
          "end_place": "420 Montgomery Street, San Francisco, CA 94108, United States",
          "polyline": {
            "type": "LineString",
            "coordinates": [
              [ -122.3980960195712, 37.7930386903944 ]
              , ... ]
          }
        }
      }
    },
    {
      "order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
      "destination": {
        "geometry": {
          "type": "Point",
          "coordinates": [-122.404514, 37.793738]
        },
        "address": "600 Kearny St, San Francisco, CA 94108, United States",
        "radius": 50
      },
      "scheduled_at": "2021-02-18T15:10:00.000Z",
      "started_at": "2021-02-18T14:00:00.000Z",
      "completed_at": null,
      "status": "ongoing",
      "service_time": 500,
      "share_url": "https://trck.at/abcd53",
      "delayed": False,
      "arrived_at": null,
      "exited_at": null,
      "estimate": {
        "arrive_at": "2021-02-18T14:50:00.000Z",
        "route": {
          "distance": 16366,
          "duration": 3284,
          "remaining_duration": 2360,
          "start_place": "333 Post St, San Francisco, CA 94108, United States",
          "end_place": "600 Kearny St, San Francisco, CA 94108, United States",
          "polyline": {
            "type": "LineString",
            "coordinates": [
              [ -122.3980960195712, 37.7930386903944 ]
              , ... ]
          }
        }
      }
    },
    {
      "order_id": "65fd526e-415e-497c-aa5c-4ffed9968262"
      "destination": {
        "geometry": {
          "type": "Point",
          "coordinates": [-122.406215, 37.794271]
        },
        "address": "756 Grant Ave, San Francisco, CA 94108, United States",
        "radius": 50
      },
      "scheduled_at": "2021-02-18T15:25:00.000Z",
      "started_at": "2021-02-18T14:00:00.000Z",
      "completed_at": null,
      "status": "ongoing",
      "service_time": 200,
      "arrived_at": null,
      "exited_at": null,
      "share_url": "https://trck.at/abcd234",
      "delayed": True,
      "estimate": {
        "arrive_at": "2021-02-18T15:30:00.000Z",
        "route": {
          "distance": 31366,
          "duration": 5284,
          "remaining_duration": 3860,
          "start_place": "333 Post St, San Francisco, CA 94108, United States",
          "end_place": "756 Grant Ave, San Francisco, CA 94108, United States",
          "polyline": {
            "type": "LineString",
            "coordinates": [
              [ -122.3980960195712, 37.7930386903944 ]
              , ... ]
          }
        }
      }
    }
  ]
}

For each order, estimate object contains:

arrive_at shows estimated time of arrival (ETA) as UTC timestamp
route contains the following data:
- distance shares estimated route distance (in meters)
- duration and remaining_duration share actual and remaining durations (in seconds)
- start_place and end_place display reverse geocoded place names and addresses for trip start and order desination locations
- polyline contains an array of coordinates for the estimated route from the live location to the destination as polyline in GeoJSON LineString format. It is an array of Point coordinates with each element linked to the next, thus creating a pathway to the destination.

note

To help you understand how to draw polylines on a map, we prepared code samples for Google Maps (JS, Android, iOS) and for Mapbox (JS, Android, iOS).

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

Automatically stopping tracking on the device requires you to integrate silent push notifications on iOS and Android.

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.

Tracking Experience

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.

Tracking Experience

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.

Tracking Experience

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.

Tracking Experience

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.

Tracking Experience

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.

Trips API: Summary available for completed trips with orders

{
  "trip_id": "4359cc65-90dd-4b2b-875b-26e6d2eba11d",
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "completed_at": null,
  "started_at": "2021-02-18T14:00:00.000Z",
  "status": "active",
  "views": {
    "embed_url": "https://embed.hypertrack.com/dkdkddnd",
    "share_url": "https://trck.at/abcdef"
  },
  "orders": [
    {
      "order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
      "destination": {
        "geometry": {
          "type": "Point",
          "coordinates": [-122.398096, 37.793038]
        },
        "address": "420 Montgomery Street, San Francisco, CA 94108, United States",
        "radius": 50
      },
      "scheduled_at": "2021-02-18T14:30:00.000Z",
      "service_time": 300,
      "started_at": "2021-02-18T14:00:00.000Z",
      "completed_at": "2021-02-18T15:00:00.000Z",
      "status": "completed",
      "share_url": "https://trck.at/abcd53",
      "delayed": True,
      "arrived_at": null,
      "exited_at": null,
    },
    {
      "order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
      "destination": {
        "geometry": {
          "type": "Point",
          "coordinates": [-122.404514, 37.793738]
        },
        "address": "600 Kearny St, San Francisco, CA 94108, United States",
        "radius": 50
      },
      "scheduled_at": "2021-02-18T15:10:00.000Z",
      "started_at": "2021-02-18T14:00:00.000Z",
      "completed_at": "2021-02-18T15:00:00.000Z",
      "service_time": 500,
      "status": "completed",
      "share_url": "https://trck.at/abcd53",
      "delayed": False,
      "arrived_at": null,
      "exited_at": null,
    },
    {
      "order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
      "destination": {
        "geometry": {
          "type": "Point",
          "coordinates": [-122.406215, 37.794271]
        },
        "address": "756 Grant Ave, San Francisco, CA 94108, United States",
        "radius": 50
      },
      "scheduled_at": "2021-02-18T15:25:00.000Z",
      "started_at": "2021-02-18T14:00:00.000Z",
      "completed_at": "2021-02-18T15:00:00.000Z",
      "status": "completed",
      "service_time": 200,
      "arrived_at": null,
      "exited_at": null,
      "share_url": "https://trck.at/abcd234",
      "delayed": False,
    }
  ],
  "summary": {
     ...
  }
}

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.

Tracking Experience

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 URL
street - additional street detail is shown in the map
satellite - satellite view is used as shown in an example below

For example:

https://trck.at/abcdexyz?layer=street

To illustrate, please review corresponding images below for each of the layer option value usage.

Location Map

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

https://trck.at/abcdexyz?icon=car

Location Map

Mini query parameter

mini - this parameter allows to hide trip details used to show in the map as shown below.

https://trck.at/abcdexyz?mini=true

Location Map

https://trck.at/abcdexyz?mini=all

Location 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 app
ht_view_href_text_completed - once this option is used, your completed trip will have a title defined by the value of this key
ht_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:

{
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "orders": [
    {
      "order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
      "destination": {
        "geometry": {
          "type": "Point",
          "coordinates": [-122.398096, 37.793038]
        },
        "address": "420 Montgomery Street, San Francisco, CA 94108, United States",
        "radius": 50
      },
      "scheduled_at": "2021-02-18T14:30:00.000Z",
      "service_time": 300
    },
    ...
  ]
  "metadata": {
    "store_id": "STORE_A",
    "delivery_id": "pkg_1AC",
    "route_id": "rt_B12",
    "transport_type": "scooter",
    "ht_view_text_ongoing": "Your order for Philarmonic coffe cup is on the way!",
    "ht_view_text_completed": "Your Philarmonic coffee cup order is delivered. Enjoy!",
    "ht_view_href_completed": "yourphilarmoniccoffee.com/rate_order",
    "ht_view_href_text_completed": "Enjoyed your Coffee!. Rate your order!",
    "ht_view_hide_summary_completed": true
  }
}'

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.

trip embed view

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

https://embed.hypertrack.com/trips/{trip_id}?publishable_key={publishable_key}&trip_complete=false

Questions?

Please do not hesitate to contact us with your questions and feedback.

Introduction#

Create and manage orders with Trips API#

Create and track trips with one or multiple orders#

important

Start trip with one or multiple orders#

Payload structure#

Code examples#

important

Get views and estimates#

note

Complete trip#

note

Completing orders#

important

Track order delays and no-shows#

Driver is delayed on the way to order destination#

Driver is moving away from destination#

Driver is delayed and stationary#

Driver disables location permission#

Driver becomes untrackable on the way#

Get real-time status and summary#

Get status on webhooks#

important

Get summary from API#

Get Trips API#

Trip summary payload#

Share live views of orders with customers#

Customize tracking view#

Customize with url query parameters#

Layer query parameter#

Icon query parameter#

Mini query parameter#

Customize with reserved trip metadata keys#

Embed live views of trips in operations dashboards for ops managers#

important

Inline frames#

Hide trip completion button#

Questions?#

Introduction

Create and manage orders with Trips API

Create and track trips with one or multiple orders

Start trip with one or multiple orders

Payload structure

Code examples

Get views and estimates

Complete trip

Completing orders

Track order delays and no-shows

Driver is delayed on the way to order destination

Driver is moving away from destination

Driver is delayed and stationary

Driver disables location permission

Driver becomes untrackable on the way

Get real-time status and summary

Get status on webhooks

Get summary from API

Get Trips API

Trip summary payload

Share live views of orders with customers

Customize tracking view

Customize with url query parameters

Layer query parameter

Icon query parameter

Mini query parameter

Customize with reserved trip metadata keys

Embed live views of trips in operations dashboards for ops managers

Inline frames

Hide trip completion button

Questions?