Track devices with the API

The quickest and most popular way to use HyperTrack is to track devices with the API. This guide will show you how to:

Start and stop tracking

HyperTrack Devices APIs give you the power to control tracking on all devices using apps with HyperTrack SDKs pointing to your account. As you perform Device API calls from your servers, you are can remotely start and stop tracking devices with apps running HyperTrack SDK integration.

In order to perform API calls from your server, you need to first obtain AccountId and Secret Key.

Start tracking

For example, if you would like to start tracking when your app at the start of working hours, or work assignment, or app login, you may want to call Devices API call to start tracking for your device. In order to start tracking on your device, you should be able to obtain, store, and reference your users' HyperTrack device_id when calling this API from your server.

To start tracking your device, you may make a Devices API call as shown below.

// Instantiate Node.js helper library instance
const hypertrack = require("hypertrack")(accountId, secretKey);
// Use Node.js helper library method to start tracking
hypertrack.devices
.startTracking(deviceId)
.then(() => {
// Tracking started
})
.catch(error => {
// Error handling
});

Stop tracking

In order to protect the privacy of workers using your app, you are strongly encouraged to stop tracking when the user either logs out, ends working hours, completes all assigned work, etc. To do so, you may make a Devices API stop tracking call. Once you issue this call from the server, HyperTrack Device API will remotely stop tracking for your device with device_id.

// Instantiate Node.js helper library instance
const hypertrack = require("hypertrack")(accountId, secretKey);
// Use Node.js helper library method to stop tracking
hypertrack.devices
.stopTracking(deviceId)
.then(() => {
// Tracking started
})
.catch(error => {
// Error handling
});
note

Team HyperTrack is working on a way to specify private hours when tracking is stopped, and automatically resumes thereafter.

Get the device ID(s) of the user(s) you want to track

The SDK should have added a device name and metadata upon initialization in the user's app: (iOS, Android).

If you have already sent and stored this information to your servers, get the user's device ID from your application database. Else, get the list of registered devices from the Devices API and use the device name or metadata to identify the user(s) you want to track.

HyperTrack views and developer integrations rely on the device names and metadata for filtering, selection, and more. Customizing these device properties makes navigation and identification of users easier. Developers often add unique identifiers, grouping information, or annotations that are frequently accessed for devices.

Device name and custom metadata
{
"name": "Alex’s Phone",
"metadata": {
"customer_id": "ABC123"
}
}

By default, the property name is set to the name of the device as configured in the device settings. With the SDK, you can set and customize this name. Additionally, the Devices API provides you an ability to update device name and metadata via an HTTP PATCH.

note

The Devices API is authoritative when it comes to setting the device name and/or metadata. Once you have updated the device name by invoking the Devices API above, the HyperTrack mobile SDK will not be able to make subsequent changes to the device name. Similarly, if you update the device metadata via the Devices API call, the HyperTrack mobile SDK will not be able to make changes as well.

Stream events via webhooks

Use webhooks to ingest live location, activity, outage and other movement context of your devices from HyperTrack to your server end point. Works best when building live location experiences and applications on your server.

Webhooks setup

The HyperTrack dashboard allows you add your webhook URL on the Setup page.

Just enter your webhook URL and click on Add Webhook. Once entered, it will immediately change to Receiving Events as shown below:

Setup Screen

Troubleshooting webhook integration

Please review common issues below for suggestions on how to resolve them.

Webhooks not sending data to your server

To confirm if your webhook server is working as expected, you may send a test event by clicking on three dots on the webhook setup screen and and then clicking on Send test event option.

Setup Screen

You will receive a webhook test payload that will be like this:

[
{
"recorded_at": "2019-02-27T22:50:24.538000Z",
"data": {
"altitude": 495.2,
"bearing": 90,
"location": {
"coordinates": [
-6.2755,
57.6398983
],
"type": "Point"
},
"location_accuracy": 14.087,
"speed": 0
},
"device_id": "TEST_DEVICE_ID",
"type": "location",
"account_id": "0"
}
]

If you have not received the request, then you may want to verify if your server is reachable by making a POST request with a tool of your choice to your webhook server URL. Otherwise, your server will be receiving webhooks from HyperTrack once devices under your account generate location data.

note

You will likely not receive webhooks right away. We offer the capability to send test events (upon click on the three dots on the screen above). This will allow you to test your implementation.

Webhook payload content

The following Webhooks are posted.

Locations

Location time series data where each location in the stream includes coordinates and the optional fields speed, altitude, bearing, and accuracy when available.

{
"created_at": "2019-07-01T20:00:01.247377Z",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"recorded_at": "2019-07-01T20:00:00.000000Z",
"type": "location",
"data": {
"geometry": {
"type": "Point",
"coordinates": [-6.2755, 57.6398983, 124]
},
"speed": 0.0,
"bearing": 313.94
},
"version": "2.0.0"
}

Location events are sent with a high frequency (~ 100x more than activity events).

  • Data: Current location of the device in GeoJSON format. Altitude, the optional third parameter in the coordinates array, is the current device elevation in meters, relative to the sea level on iOS and relative to the WGS 84 reference ellipsoid on Android.
  • Location Accuracy (Optional): The estimated horizontal accuracy of the location, radial, in meters. When the location identifies the center of a confidence circle, the accuracy defines the radius of the circle (in meters). For Android, there is a 68% probability that the true location is inside the circle.
  • Bearing (Optional): The horizontal direction of travel, measured in degrees and relative to true North. Degrees start at true North and continue clockwise around the compass (north is 0, east is 90, south is 180, west is 270 degrees).
  • Speed (Optional): Speed of travel in meters per second.

Device status

Device status changes. This includes a device becoming active, inactive/disconnected and activity transistions such as start of walk, drive, or stop

{
"created_at": "2019-07-01T20:00:01.247377Z",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"recorded_at": "2019-07-01T20:00:00.000000Z",
"type": "device_status",
"data": {
"value": "active",
"activity": "walk"
},
"location": {
"type": "Point",
"coordinates": [-6.2755, 57.6398983, 124]
},
"version": "2.0.0"
}

Device status provides update about the device. The value can be active, inactive and disconnected. Please read here to understand how HyperTrack tracks device status.

Mobile devices send health data through the Mobile SDKs. The data is showing tracking outages and resumptions. Health data is available for outage events when an outage affects location data. This data is sent with a low frequency (based on device activity).

When the device is active, we include the activity when available. Mobile phones use a variety of sensors combined with location data to intelligently identify phone users’ activity. Activity transitions are sent with a medium frequency (similar to summary events).

HyperTrack supports 3 types of activity transitions: walk, drive, and stop.

For your convenience, we provide you a set of free-to-use SVG icons to display activities in your application.

Battery

Battery status changes. Values include low, normal and charging

{
"created_at": "2019-07-01T20:00:01.247377Z",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"recorded_at": "2019-07-01T20:00:00.000000Z",
"type": "battery",
"data": {
"value": "low"
},
"location": {
"type": "Point",
"coordinates": [-6.2755, 57.6398983 124]
},
"version": "2.0.0"
}

HyperTrack sends battery updates to indicate the battery health. These events include details on charge, discharge and low battery.

info

Battery updates can be combined with outages as a leading indicator for tracking outages.

Get live location from the API

Use the Devices API to get the live location and device status of one or more devices. Works best when building dispatch, assignment and routing applications, and require live location information on demand.

Getting a single device status and location

All tracked devices are available through the Devices API. Each device entity contains the following data:

  • Last known location in location
  • Device status, and activity or outage reason in device_status
  • Share and embed view URLs for the device in views
  • Battery level (one of normal, low, or charging) in battery
  • Device info, including name, brand, model, OS, operator, timezone, and SDK version in device_info
  • Custom metadata sent by the SDK or set by Devices API in metadata
HTTP 200 - Single device payload
{
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"location": {
"speed": 4.20,
"accuracy": 14.09,
"bearing": 193.12,
"geometry": {
"type": "Point",
"coordinates": [
35.1016383,
47.8391314,
65.40
]
},
"recorded_at": "2019-07-18T18:01:59.064000Z",
},
"device_status": {
"data": {
"recorded_at": "2019-07-30T01:38:45.610000Z",
"activity": "stop"
},
"value": "active"
},
"views": {
"share_url":"https://trck.at/abcdef",
"embed_url":"https://embed.hypertrack.com/devices/00112233-4455-6677-8899-AABBCCDDEEFF?publishable_key=abc"
},
"battery": "normal",
"device_info": {
"timezone": "America/Los_Angeles",
"os_name": "iOS",
"device_brand": "Apple",
"sdk_version": "3.3.2",
"device_model": "iPhone X",
"network_operator": "T-Mobile",
"name": "Alex’s Phone",
"os_version": "12.4"
},
"registered_at": "2019-07-10T01:38:45.610000Z",
"metadata": { ... }
}

Understanding device status

The device_status object has properties that are conditional to device_status.value.

It can be one of the following: active, inactive or disconnected. See here for a detailed description.

Active

Active device status includes an activity
"device_status": {
"data": {
"recorded_at": "2019-07-30T01:38:45.610000Z",
"activity": "stop"
},
"value": "active"
}

The device is actively sending updates. In that case, the device_status.data object is provided with an activity property. It can be one of stop, walk, or drive.

note

Run and cycle activities are purposefully removed because fewer businesses cared about it, and inaccurate classification obfuscated walks and drives. We are working on adding public transit detection, including trains, ferries and buses.

Inactive

Inactive device status includes a reason
"device_status": {
"data": {
"recorded_at": "2019-09-03T16:39:35.326000Z",
"reason": "stopped_programmatically"
},
"value": "inactive"
}

The device is not sending location updates and in that case, the device_status.data object is contains reason property`. These reasons can be one of the following below:

  • location_permissions_denied
  • location_services_disabled
  • motion_activity_permissions_denied
  • motion_activity_services_disabled
  • motion_activity_services_unavailable
  • stopped_programmatically
  • tracking_service_terminated
  • unexpected

Disconnected

Disconnected device status does not have any data
"device_status": {
"data": {},
"value": "disconnected"
}

Connection with the device was lost unexpectedly (no data received for over an hour). In that case, the device_status.data object is empty.

tip

If you would like to receive device status updates as they come in, it is recommended to use device status webhooks. This enables reacting to tracking outages and resumptions as they happen.

Battery status property
"battery": "normal"

Device objects contain a battery property to indicate the state of the device battery. The property can take one of the following values: low, normal, or charging

tip

If you would like to receive battery state updates as they come in, it is recommended to use battery updates webhooks. This enables reacting to low battery risks as they happen.

Device location payload
"location": {
"speed": 4.20,
"accuracy": 14.09,
"bearing": 193.12,
"geometry": {
"type": "Point",
"coordinates": [
35.1016383,
47.8391314,
65.40
]
},
"recorded_at": "2019-07-18T18:01:59.064000Z",
}

Use the location object to display the location of a device on a map. It is important to understand the GeoJSON format to handle the data correctly:

  • Type can only be "Point" in this scenario
  • Coordinates is an array of 2-3 values (the last being optional) with the following format: [longitude, latitude, altitude]

The accuracy value is often used to draw a "halo effect" around the location dot with the accuracy (in meters) value being the radius of the surrounding ring. In addition, bearing (in degrees starting at due north) is used to draw a directional indicator at the location dot.

Location Map

View devices on the map

Go to Views on your HyperTrack dashboard to map all devices that you intend to track.

  • Clustered live location of all devices right now
  • Day-wise list of all devices you intend to track, classified as active, inactive or disconnected
  • Location polyline and movement timeline of each device for the selected day
  • Aggregate durations, steps and distances of stops, walks and drives
  • Hierarchical views organized and filtered by metadata

Map view of all devices

  • The default view shows a map with a list of all devices you intended to track today
  • User may select the day and timezone to view devices for
  • Devices are grouped by device status
  • User may search devices by name or metadata
  • Each device shows associated metadata and a status bar with split of stop, walk, drive, inactive and disconnected durations
  • Every device that tracked location(s) that day is classified as active for that day
  • Devices that were inactive all day have an associated reason and the last updated location timestamp
  • Devices that were disconneced all day show the last updated location timestamp
  • Clicking on a device will show the day's movement timeline on the map
  • User may popout the device history in a new browser window if you prefer

Map View

Day and timezone select

Users can select the day and timezone for which they want to view the list of devices on a map, and drill down into individual devices and their histories.

Calendar

Device status and metadata

Devices in the list show a status bar and metadata for each device. For selected day, the status bar indicates the duration of stop, walk, drive, inactive and disconnected for the device. Metadata shows the values set in the device metadata JSON, and shows the corresponding keys on hover.

Device status and metadata

Live location of a device

The view for today shows live location of devices on the map with last known locations. Live locations automatically update in the view as the device moves. Hovering on live location opens a card with the following information:

  • Device status: active, inactive or disconnected. Read more here.
  • Activity: stop, walk or drive
  • Recorded: Timestamp of the location as recorded by the OS
  • Altitude: Altitide of the device at that location
  • Bearing: Bearing of the device at that location
  • Speed: Speed of device at that location
  • Location: Latitude, Longitude
  • Accuracy: Accuracy of the location

Live Location View

There are additional visual elements to make the live location of other devices come alive in a way that is consistent with on-device views of location in popular mapping apps.

  • Live location pulsates if recorded under a minute ago
  • Live location shows bearing when the device is moving
  • The halo around the live location dot indicates accuracy

Device timeline

Clicking a device in the list or clicking the dot on the map shows the device timeline.

  • Location polyline with replay to drill down where the device was at what point in time
  • Movement timeline card organized by activity and outages
  • Addresses for stops, distances for drives, and steps for walks
  • Option to view or hide the device info and metadata
  • If selected day is today and the device is active, ongoing activity, last updated and speed become visible

Device Timeline

note

You can see all HyperTrack mobile SDKs here: Android, iOS, Flutter, and React Native.

Questions?

If you would like to get help with location tracking needs for your app users' devices, questions or comments on any of the topics above, please do not hesitate to contact us.