Track trips with destination

One of the more popular use cases of HyperTrack is live location sharing of an order with customers. From Uber-for-X startups to enterprises delivering products and services to customers, "where's my order?" is a moment of anxiety that businesses want to handle better. Businesses can improve NPS scores and save money by providing visibility to customers and ops teams about the live location of the order, with ETA and delay notifications. HyperTrack has open sourced popular sample apps for Live Location Sharing and Ridesharing, with detailed tutorials to integrate trips with destination for your application. This guide will show you how to:

Start and complete trips


HTTP 200 - Completed trip payload
{
"trip_id": "aabb2233-8899-4455-3210-aabbccddeeff",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"started_at": "2019-05-03T06:25:51.238000Z",
"completed_at": "2019-05-03T06:25:51.238000Z",
"status": "completed",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"metadata": {
"customer_id": "ABC123"
},
"device_info": {
"sdk_version": "3.3.2",
"os_version": "12.4"
},
"destination": {
"geometry": {
"type": "Point",
"coordinates": [
-122.3980960195712,
37.7930386903944
]
},
"radius": 30,
"scheduled_at": "2019-05-03T06:25:51.238000Z",
"arrived_at": "2019-05-03T06:25:51.238000Z"
},
"summary": {
...
}
}

Use the Trips API when you want to track the movement of the device to an expected destination. Post the destination for the device, and get estimates (route/ETA) to destination, shareable URL for customers, embed URL for ops dashboards, and markers for activity and outages as the device moves. Completed trips include a summary with total duration, distance and steps.

note

A device may be track multiple active trips at the same time. For example, pickup and dropoff for the same on-demand 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.

Starting and completing trips would automatically control the start and stop of tracking on the device. This way, you manage tracking through just one API.

The device would 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 for the device.

note

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.

Get route and ETA

POST https://v3.api.hypertrack.com/trips/Run in Postman
const request = require("request");
const payload = {
device_id: "00112233-4455-6677-8899-AABBCCDDEEFF",
destination: {
geometry: {
type: "Point",
coordinates: [-122.3980960195712, 37.7930386903944]
}
}
};
const options = {
method: "POST",
url: "https://v3.api.hypertrack.com/trips/",
auth: {
user: "{AccountId}",
password: "{SecretKey}"
},
body: payload
};
request(options, (err, res, body) => {
console.dir(err, res, body);
});

Trip with destination returns an estimated route polyline and estimated time of arrival (ETA).

To start such a trip, the destination object is required. The object should include a GeoJSON object called geometry. As of right now, only Point is supported in the GeoJSON object, which will set a circular destination point with a radius of 30 meters by default.

note

To change the default radius, you can pass a radius property (interger in meters) to the destination object.

Share URL with customer

Tracking Experience

Trips API generates a share_URL for each trip with destination. More details can be found in the Trips API reference.

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.

HTTP 201 - New trip with destination
{
"completed_at": null,
"status": "active",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"destination": {
"geometry": {
"type": "Point",
"coordinates": [
-122.3980960195712,
37.7930386903944
]
},
"radius": 30,
"scheduled_at": null,
"arrived_at": null,
"exited_at": null
},
"estimate": {
"arrive_at": "2019-05-03T06:25:51.238000Z",
"route": {
"distance": 14666,
"duration": 2884,
"remaining_duration": 1560,
"start_place": "Mannat Manzil #48,2nd cross, 3rd Main,Amrita Nagar, 3rd Phase, Choodasandra, Bengaluru, Karnataka 560035, India",
"end_place": "4, Muniswamy Garden, A - Block, Bengaluru, Karnataka 560025, India",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
}

Route and estimate objects

The Trips API responds with an active trip object that returns the original payload with additional properties.

note

Upon start of a new trip, HyperTrack will send a trip start webhook to confirm the new trip. The payload of the webhook includes the trip ID and metadata.

A new estimate object is included in the trips payload. HyperTrack provides estimates for every trip with a destination. The object includes information about:

  • Estimated time of arrival (ETA)
  • Actual and estimated route distance (in meters)
  • Actual and remaining duration (in seconds)
  • Reverse geocoded place names and addresses for trip start, complete and intermediate stops (based on activity)
  • 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).

Track delays for scheduled trip

POST https://v3.api.hypertrack.com/trips/Run in Postman
const request = require("request");
const payload = {
device_id: "00112233-4455-6677-8899-AABBCCDDEEFF",
destination: {
geometry: {
type: "Point",
coordinates: [-122.3980960195712, 37.7930386903944]
},
scheduled_at: "2022-05-03T06:25:51.238000Z"
}
};
const options = {
method: "POST",
url: "https://v3.api.hypertrack.com/trips/",
auth: {
user: "{AccountId}",
password: "{SecretKey}"
},
body: payload
};
request(options, (err, res, body) => {
console.dir(err, res, body);
});

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.

HTTP 201 - New trip payload scheduled arrival
{
"completed_at": null,
"status": "active",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"metadata": {
"customer_id": "ABC123"
},
"destination": {
"geometry": {
"type": "Point",
"coordinates": [
-122.3980960195712,
37.7930386903944
]
},
"radius": 30,
"scheduled_at": "2019-05-03T06:25:51.238000Z",
"arrived_at": null,
"exited_at": null
},
"estimate": {
"arrive_at": "2019-05-03T06:25:51.238000Z",
"route": {
"distance": 14666,
"duration": 2884,
"remaining_duration": 1560,
"start_place": "Mannat Manzil #48,2nd cross, 3rd Main,Amrita Nagar, 3rd Phase, Choodasandra, Bengaluru, Karnataka 560035, India",
"end_place": "4, Muniswamy Garden, A - Block, Bengaluru, Karnataka 560025, India",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
}

The trips payload has arrived_at and exited_at properties in the destination object. These are null initially. As soon as the tracked device arrives at the destination, the arrival time gets updated. When the device leaves the the destination, the exit time gets set. You can use these properties to identify time spent at a destination.

note

HyperTrack sends arrival and exit events in the trip destination webhooks. The payload of the webhook includes the trip ID and metadata.

Embed trip view in dashboard

trip embed view

The Trip payload includes the views object. Every trip gets assigned unique URLs to share and embed views of the trip. The URLs will remain active after trip completion. In that case, the views will show a summary of the trip, along with destination marker, start and complete locations, distance, duration, arrival time, device info, trip metadata, and the actual route taken to the destination.

While shareable views are accessible to everyone with the URL, embed views include the HyperTrack publishable key. The embed_URL includes the publishable key and is available to use as-is. That said, your publishable key is available in the Setup page of your HyperTrack dashboard.

The embed URL format is https://embed.hypertrack.com/trips/{trip_id}?publishable_key={publishable_key}

Inline Frames

Embeddable views are implemented with HTML inline frames and require JavaScript to be executed successfully.

Iframes have important properties to be considered during implementation. Please read the following instructions carefully to ensure a seamless integration:

  • Iframe size: By default, Iframes are sized with 200 pixels height and 300 pixels width. It is recommended to implement responsiveness using CSS. Here is a sample implementation
  • Responsive views: All embeddable views are responsive and the mobile views will be displayed when the Iframe size is below 500 pixels
  • Security: When you activate the sandbox property for this Iframe, please include allow-scripts allow-same-origin to ensure successful execution of the JavaScript present in the Views
  • Compatibility: Please review browser compatibility of IFrame properties you want to use
  • Loading times: In order to improve speed, it's recommended to set the iframe's src attribute with JavaScript after the main content is done with loading

Trips API generates embed_URL for all trips. More details can be found in the Trips API reference.

Get trip updates on webhooks


Webhook: Trip created payload
{
"created_at": "2019-07-01T14:00:00.000000Z",
"data": {
"value": "created",
"trip_id": "123E4567-E89B-12D3-A456-426655440000",
"trip_metadata": { "customer": "1234" }
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "trip",
"version": "2.0.0"
}

One of the benefits of trips is the support of webhooks for trip-related activities. Currently, HyperTrack will send notifications triggered by ...

  • Trip start
  • Geofence enter and exit
  • Destination arrival and exit
  • Delays for scheduled trips
  • Trip completion
Webhook: Trip destination arrival payload
{
"created_at": "2019-07-01T14:00:00.000000Z",
"data": {
"value": "destination_arrival",
"trip_id": "123E4567-E89B-12D3-A456-426655440000",
"trip_metadata": { "customer": "1234" }
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "trip",
"version": "2.0.0",
"location": {
"type": "Point",
"coordinates": [-122.39970134375172, 37.7942272665877, -1]
}
}
note

Please review the Webhook guide to understand what webhooks are and how they can be leveraged in addition to the HyperTrack APIs.

All trip updates will include the update type, device_id, trip_id and trip_metadata at the very least. More context is provided based on the update type. Please take a look at the trip webhooks references for more details.

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)

Trip webhooks always include a start timestamps (server processed data), a recoding timestamp (device recorded data), device ID, trip ID, and trip details.

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.

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.

{
"created_at": "2019-07-01T14:00:00.000000Z",
"data": {
"value": "created",
"trip_id": "123E4567-E89B-12D3-A456-426655440000",
"trip_metadata": { "customer": "1234" }
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "trip",
"version": "2.0.0"
}

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. Summaries are sent with a medium/low frequency.

note

Trips can be managed through the Trips API.

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 (set through mobile SDKs - Android and iOS) in combination with trips metadata to establish all relevant information in order to send highly contextualized notifications.

Stream trip data to native apps

tip

If you want to implement native views on Android, please look at the Android Views references. The module provides methods to subscribe to movement notifications programatically.

Apart from ready-to-use views for web usage, native libraries are available to consume HyperTrack data directly in your iOS and Android app.

HyperTrack Views libraries are used for getting live location and movement data for devices and trips directly to your native app. These libraries subscribe to HyperTrack GraphQL interfaces to get data streams and exposes them through useful callbacks. This helps developers create custom live location views and go serverless. Their app users can directly get data securely and privately from the HyperTrack servers.

Follow the iOS or Android Quickstarts to implement your custom views powered by HyperTrack data.

Get trip summary

GET https://v3.api.hypertrack.com/trips/?status=completed`Run in Postman
const request = require("request");
const options = {
url: "https://v3.api.hypertrack.com/trips/?status=completed",
auth: {
user: "{AccountId}",
password: "{SecretKey}"
}
};
request(options, (err, res, body) => {
console.dir(err, res, body);
});

You will notice that the GET /trips endpoint will return only active trips. This is a deliberate design choise to show the most relevant trips, out of potentially thousands of completed trips.

You can set the status path parameter to completed to get past trips.

HTTP 200 - Filter by completed trips
[
{
"trip_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"started_at": "2019-05-03T06:25:51.238000Z",
"completed_at": "2019-05-03T06:25:51.238000Z",
"status": "completed",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"metadata": {
"customer_id": "ABC123"
},
"destination": {
"geometry": {
"type": "Point",
"coordinates": [
-122.3980960195712,
37.7930386903944]
},
"radius": 30,
"scheduled_at": "2019-05-03T06:25:51.238000Z",
"arrived_at": "2019-05-03T06:25:51.238000Z"
},
"summary": {
...
}
}, ...
]

Review trip summaries

Trips API: Summary available for completed trips
{
"summary": {
"locations": {
"type": "LineString",
"coordinates": [
[-122.3996, 37.79396136184457, 123, "2019-09-13T18:21:51.002000Z"],
[
-122.39982803643629,
37.79423869055751,
null,
"2019-09-13T18:21:51.802000Z"
]
]
},
"distance": 1234,
"duration": 9887,
"started_at": "2019-09-13T18:04:20.467000Z",
"completed_at": "2019-09-13T20:49:08.226000Z",
"device_id": "FC772B07-2F27-4EB9-8A3B-F21D7F63A436",
"markers": [
{
"type": "geofence",
"data": {
"arrival": {
"location": {
"geometry": {
"type": "Point",
"coordinates": [-122.3996, 37.7939]
},
"recorded_at": "2019-09-13T19:35:51.002000Z"
}
},
"geofence": {
"geometry": {
"type": "Point",
"coordinates": [-122.3996, 37.7939]
},
"geofence_id": "7159040c-ad03-4a49-9c1f-11f9763cdf9b",
"radius": 30,
"metadata": {
"stop_id": 2937
}
},
"route_to": {
"duration": 120,
"distance": 600,
"start_location": {
"geometry": {
"type": "Point",
"coordinates": [-122.3996, 37.7939]
},
"recorded_at": "2019-09-13T19:33:51.002000Z"
}
},
"exit": {
"location": {
"geometry": {
"type": "Point",
"coordinates": [-122.3996, 37.7939]
},
"recorded_at": "2019-09-13T19:36:51.002000Z"
}
},
"duration": 60
}
},
{
"type": "device_status",
"data": {
"value": "inactive",
"start": {
"recorded_at": "2019-09-13T19:40:51.002000Z",
"location": {
"geometry": {
"type": "Point",
"coordinates": [-122.3996, 37.7939]
},
"recorded_at": "2019-09-13T19:39:51.002000Z"
}
},
"end": {
"recorded_at": "2019-09-13T20:40:51.002000Z",
"location": {
"geometry": {
"type": "Point",
"coordinates": [-122.3996, 37.7939]
},
"recorded_at": "2019-09-13T20:40:52.002000Z"
}
},
"reason": "stopped_programmatically"
}
},
{
"type": "trip_marker",
"data": {
"recorded_at": "2019-09-13T20:40:52.002000Z",
"location": {
"coordinates": [-122.3996, 37.7939],
"type": "Point"
},
"metadata": {
"id": "1235"
},
"route_to": {
"duration": 2654,
"distance": 377,
"start_location": {
"geometry": {
"type": "Point",
"coordinates": [-122.3996, 37.7939]
},
"recorded_at": "2019-09-13T19:33:51.002000Z"
}
}
}
}
]
}
}

For all completed trips, a summary object is provided. Additionally, when executing a Trips GET API call on a single trip_id a summary object is returned with the latest data for the trip.