Track trips with geofences

Workforce automation, logistics and fleet management apps are often built for users to fulfill a list of jobs assigned at the start of the work day. User visits these places and then returns to base. Business wants to track how time was spent, what routes were taken, and map it with enterprise application data to measure productivity scores and improve efficiency. This guide will show you how to:

Start and complete trip

Use the Trips API when you want to track the movement of the device to a list of geofences. Post the geofences as an array to get get arrival, exit, time spent and route to geofences, 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.

POST https://v3.api.hypertrack.com/tripsRun in Postman
const request = require("request");
const payload = {
device_id: "00112233-4455-6677-8899-AABBCCDDEEFF",
geofences: [
{
geometry: {
type: "Point",
coordinates: [-121.3980960195712, 38.7930386903944]
},
metadata: {
stop_id: "12345XYZ",
stop_name: "SF office"
}
}
]
};
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);
});

To start such a trip, the geofences array is required. The array should include objects with a GeoJSON object called geometry. Both Point and Polygon are supported in the GeoJSON object. Point will set a circular geofence area with a radius of 30 meters by default. Polygon will set a polygon geofence through an array of locations where the first and last location must be the same.

Use geofence metadata to identify each geofence in HyperTrack with the place of interest in your application. The metadata is returned through the respective APIs, webhooks, and views.

HTTP 201 - New trip with geofences

{
"completed_at": null,
"status": "active",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"geofences": [
{
"geometry": {
"type": "Point",
"coordinates": [-121.3980960195712, 38.7930386903944]
},
"radius": 30,
"metadata": {
"stop_id": "12345XYZ",
"stop_name": "SF office"
},
"arrived_at": null,
"exited_at": null
}
]
}

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

POST https://v3.api.hypertrack.com/trips/{trip_id}/complete` Run in Postman
const request = require("request");
const options = {
method: "POST",
url: "https://v3.api.hypertrack.com/trips/<Bracketize name="trip_id"/>/complete",
auth: {
user: "{AccountId}",
password: "{SecretKey}"
}
};
request(options, (err, res, body) => {
console.dir(err, res, body);
});

Complete the trip at the end of the work day, e.g. when all jobs are done, end of work hours, assets returns to the station.

HTTP 202 - Trip completion processing payload

{
"message": "pending completion for trip '00112233-4455-6677-8899-AABBCCDDEEFF'"
}

It is important to understand that trip completion cannot be confirmed right away with the API response. This is due to communication required between the HyperTrack platform, the mobile SDK on the phone, and post processing to create a trip summary.

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

It usually takes a few seconds to confirm a pending trip completion. As soon as the trip is completed, HyperTrack will send a trip completion webhook. The payload of the webhooks includes the trip ID and metadata.

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": {
...
}
}

Get arrival and exit

The geofence objects in the trips payload have arrived_at and exited_at properties. These are null initially. As soon as the tracked device enters the geofence, arrival time is updated for that geofence. Similarly, when the device exits the geofence, the exit time is set for that geofence.

Update geofence metadata

Users who want to update geofence metadata after trip creation can PATCH geofence metadata. Use this when new application data has been recieved about that place of interest, and you wish to display them in views and add them to the trip summary object for record.

Get time spent and route to

The geofence markers in trip summary have duration and route_to properties. The route_to object includes distance, duration, start location and array of locations for the route from previous geofence (or from start in case of the first geofence).

time spent and route to

Embed trip view in dashboard

geofences 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 geofence markers, start and complete location, 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 summary data

Trip summary provides powerful data about the device's trip visiting geofences.

  • Start and complete time
  • Aggregate distance, duration, steps
  • Array of locations
  • Array of markers, each marker has a type and associated data
  • Device status markers include stop, walk, drive, inactive and disconnected segments with associated context
  • Geofence markers include arrival/exit time and location, duration and route with array of locations
  • Trip and geofences come with metadata as set at the time of creation or patched later