Navbar
cURL Java ObjC Swift

Introduction

Welcome to the HyperTrack documentation!

In here, you can learn how to use our native SDKs (Android, iOS, React Native), the public REST API, webhooks, views, and data exports.

Please select the documentation you are looking for from the left-side navigation.

API: Devices

Devices API lets you retrieve the current location and movement status data for your devices. Developers use it in applications to dispatch jobs or assign work to nearest available users.

Devices API requirements

Using Devices API requires that you:

Devices Authentication

# GET with Authorization header
# Using Base 64 encoding of {AccountId}:{SecretKey}
curl -H "Authorization: Basic `echo -n {AccountId}:{SecretKey} | base64`" https://v3.api.hypertrack.com/devices/

Basic Auth with AccountId and SecretKey

Get all devices

curl -H 'Content-Type: application/json' \
     -u {AccountId}:{SecretKey} \
     'https://v3.api.hypertrack.com/devices/'

GET https://v3.api.hypertrack.com/devices/

Run in Postman

Response - all devices

[{
  "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"
  },
  "metadata": { ... }
}]

HTTP 200 (OK)

Name Type Description
device_id string Unique device identifier, case sensitive
location object (optional)
location.data.speed float (optional) speed in m/s
location.data.accuracy float (optional) accuracy in m
location.data.bearing float (optional) bearing in degrees starting at due north and continuing clockwise around the compass
location.data.geometry object Location in GeoJSON format
location.data.geometry.type string As of right now, only Point is supported
location.data.geometry.coordinates array Array of longitude, latitude and optional altitude
location.recorded_at string ISO 8601 date when the location was recorded
device_status object Device status
device_status.value string Can be one of active, inactive and disconnected. More details
device_status.data object Extra information about device status
device_status.data.recorded_at string ISO 8601 date when the device status was recorded (optional)
device_status.data.activity string Device activity (optional). If available, can be one of stop, walk, run, cycle, or drive
device_status.data.reason string Reason of inactivity (optional). For inactive devices only. Can be one of denied/disabled (user denied/disabled permissions) or stopped (tracking was stopped programmatically from host application)
views object
views.embed_url string Embeddable view URL
views.share_url string Sharable view URL
battery string Battery status, can be one of low, normal, or charging
device_info object Device information
device_info.timezone string The timezone on the device in TZ format
device_info.os_name string The operating system of the device, can be one of iOS or Android
device_info.device_brand string The brand of the device
device_info.sdk_version string The HyperTrack SDK version on the device. Can be reviewed here: Android, iOS, React Native
device_info.device_model string The device model
device_info.network_operator string The network operator for the device
device_info.name string The name of the device
device_info.os_version string The version of the operating system on the device
metadata object Device metadata submitted via Mobile SDKs (Android or iOS)

Get device by ID

curl -H 'Content-Type: application/json' \
     -u {AccountId}:{SecretKey} \
     'https://v3.api.hypertrack.com/devices/{device_id}'

GET https://v3.api.hypertrack.com/devices/{device_id}

Run in Postman

Path Parameters

You should pass a device_id to retrieve a single device. If no device_id is given, all devices associated with your account will be returned by default.

Name Type Description
device_id string (optional) Unique identifier representing a device, case sensitive

Response - single device

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

HTTP 200 (OK)

Remove device

curl -X DELETE \
    https://v3.api.hypertrack.com/devices/{device_id} \
    -u {AccountId}:{SecretKey}

DELETE https://v3.api.hypertrack.com/devices/{device_id}

Run in Postman

Remove a single device from the list of tracked devices associated with the account. If the same devices starts to send location data after the removal, it will be added back to the list.

Response - completion pending

HTTP 204 (No Content)

API: Trips

Trips API lets you create, manage, and view trips of your devices. Developers use it in applications to generate routes and estimates on arrival, to get notified when their devices arrive at or leave the specified destination, and to get trip summaries upon completion.

Trips API requirements

Using Trips API requires that you:

Trips authentication

# GET with Authorization header
# Using Base 64 encoding of {AccountId}:{SecretKey}
curl -H "Authorization: Basic `echo -n {AccountId}:{SecretKey} | base64`" https://v3.api.hypertrack.com/trips/

Basic Auth with AccountId and SecretKey

Create a new trip

curl -X POST \
  https://v3.api.hypertrack.com/trips/ \
  -u {AccountId}:{SecretKey} \
  -H 'Content-Type: application/json' \
  -d '{
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "destination": {
    "geometry": {
      "type": "Point",
      "coordinates": [
        -122.3980960195712,
        37.7930386903944
      ]
    },
    "radius": 30,
    "scheduled_at": "2019-05-03T06:25:51.238000Z"
  },
  "geofences" : [{
    "geometry": {
      "type": "Point",
      "coordinates": [-121.3980960195712, 38.7930386903944]
    },
    "radius": 30,
    "metadata": {
      "stop_id": "12345XYZ",
      "stop_name": "SF office"
    }
  }],
  "metadata": {
    "shift_id": "ABC123"
  }
}'

POST https://v3.api.hypertrack.com/trips

Run in Postman

Request body

{
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "destination": {
    "geometry": {
      "type": "Point",
      "coordinates": [-122.3980960195712, 37.7930386903944]
    },
    "radius": 30,
    "scheduled_at": "2019-05-03T06:25:51.238000Z"
  },
  "geofences": [
    {
      "geometry": {
        "type": "Point",
        "coordinates": [-121.3980960195712, 38.7930386903944]
      },
      "radius": 30,
      "metadata": {
        "stop_id": "12345XYZ",
        "stop_name": "SF office"
      }
    }
  ],
  "metadata": {
    "shift_id": "ABC123"
  }
}

Here is a sample request creating a trip with a destination (routing & ETA enabled) and a scheduled arrival time.

Name Type Description
device_id string Unique identifier representing a device, case sensitive
destination object Definition of a trip destination (optional)
destination.geometry object GeoJSON geometry of type Point
destination.geometry.type string As of right now, only Point is supported
destination.geometry.coordinates array Array of longitude and latitude
destination.radius int Defines the radius (in meters) of a circular trip destination (optional, default is 30)
destination.scheduled_at string Timestamp for scheduled arrival (optional)
geofences array Upcoming feature. Array of geofence objects (optional)
geofences[].geometry object GeoJSON geometry of type Point
geofences[].geometry.type string As of right now, only Point is supported
geofences[].geometry.coordinates array Array of longitude and latitude
geofences[].radius int Defines the radius (in meters) of a circular geofence (optional, default is 30)
geofences[].metadata object Any metadata you want to assign to this geofence (optional)
metadata object Any metadata you want to assign to this trip (optional)

Response - new trip

{
  "trip_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "started_at": "2019-05-03T06:25:51.238000Z",
  "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"
  },
  "estimate": {
    "arrive_at": "2019-05-03T06:25:51.238000Z",
    "route": {
      "distance": 14666,
      "duration": 2884,
      "remaining_duration": 1560,
      "start_address": "Mannat Manzil #48,2nd cross, 3rd Main,Amrita Nagar, 3rd Phase, Choodasandra, Bengaluru, Karnataka 560035, India",
      "end_address": "4, Muniswamy Garden, A - Block, Bengaluru, Karnataka 560025, India",
      "polyline": {
        "type": "LineString",
        "coordinates": [
          [ -122.3980960195712, 37.7930386903944 ]
          , ... ]
      }
    },
    "reroutes_exceeded": false
  }
}

HTTP 201 (Created)

Name Type Description
trip_id string Unique identifier of the newly created trip, case sensitive
device_id string Unique identifier of the device associated with the trip, case sensitive
started_at string Timestamp for trip starting time
completed_at string Timestamp of trip completion time (only set when trip is completed), can be null
status string Trip status, can be active, completed or processing_completion
views.embed_url string Embeddable trip view
views.share_url string Shareable trip view
destination object Defined trip destination
destination.geometry object GeoJSON geometry of type Point for destination point
destination.radius int Radius (in meters) of a circular trip destination
destination.scheduled_at string Timestamp for scheduled arrival
destination.arrived_at string Timestamp first enter to destination
destination.exited_at string Timestamp first exit from destination
estimate object Estimates (route and arrival time)
estimate.arrive_at string Timestamp for estimated arrival
estimate.route objects Planned route segments to destination
estimate.route.distance int Route distance in meters
estimate.route.duration int Route duration in seconds
estimate.route.remaining_duration int Remaining route duration in seconds, can be null
estimate.route.start_address string Street address lookup for segment start
estimate.route.end_address string Street address lookup for segment end
estimate.route.polyline object GeoJSON geometry of type LineString
estimate.reroutes_exceeded boolean Indicates if re-route limit of 10 was exceeded
metadata object Metadata provided at trip creation

Please keep in mind that new trips do not have the summary property (outlining the trip history). The summary is only provided upon completion of a trip.

Get trips

# pagination example

curl -X GET \
  'https://v3.api.hypertrack.com/trips?limit=20&offset=160' \
  -u {AccountId}:{SecretKey}

GET https://v3.api.hypertrack.com/trips?limit=20&offset=160

Run in Postman

Path Parameters

Trips can be naviagted using pagination. You can pass limit and offset as parameters to go through the entire result set.

Name Type Description
limit int (optional) Number of trips to return per request. Default is 20. Maximum allowed is 50
offset int (optional) Number of trips to skip, starting at 0
# filtering example

curl -X GET \
  'https://v3.api.hypertrack.com/trips?status=completed&metadata=trip_1234' \
  -u {AccountId}:{SecretKey}

Trips can also be filtered by status, device_id and metadata to retrieve only relevant trips. By default, without any filter, all active trips will be returned.

Name Type Description
status string (optional) Filter by trip status (active, completed, or all). Default is active
device_id string (optional) Filter by device_id (exact string matching, case sensitive)
metadata string (optional) Filter by metadata (ignores case, matches by contains operator)

Response - all trips

{
  "_links": {
    "prev": "/trips?limit=20&offset=140",
    "next": "/trips?limit=20&offset=180",
    "last": "/trips?limit=17&offset=300"
  },
  "limit": 20,
  "size": 20,
  "total": 317,
  "items": [
    // trip objects as described in single trip response
  ]
}

HTTP 200 (OK)

Name Type Description
_links reference object Object with references to use for pagination
_links.prev URL URL with pointer to the previous page
_links.next URL URL with pointer to the next page
_links.last URL URL with pointer to the last page
limit int Number of trips to return per request
size int Actual number of trips returned. Can be smaller than limit (on the last page)
total int Total number of trips available in the result set
items list of objects List of objects, each representing a trip

Get trip by ID

curl -X GET \
  'https://v3.api.hypertrack.com/trips/00112233-4455-6677-8899-AABBCCDDEEFF' \
  -u {AccountId}:{SecretKey}

GET https://v3.api.hypertrack.com/trips/{trip_id}

Run in Postman

Path Parameters

You should pass a trip_id to retrieve a single trip. If no trip_id is given, all active trips associated with your account will be returned by default.

Name Type Description
trip_id string (optional) Unique identifier representing a trip, case sensitive

Response - single trip

{
  "trip_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "started_at": "2019-05-03T06:25:51.238000Z",
  "status": "active",
  "views": {
    "embed_url": "https://embed.hypertrack.com/dkdkddnd",
    "share_url": "https://trck.at/abcdef"
  },
  "metadata": {
    "customer_id": "ABC123"
  }
}

HTTP 200 (OK)

Complete trip

curl -X POST \
  https://v3.api.hypertrack.com/trips/{trip_id}/complete \
  -H 'Content-Type: application/json' \
  -u {AccountId}:{SecretKey}

POST https://v3.api.hypertrack.com/trips/{trip_id}/complete

Run in Postman

Completing a trip requires a procedure to be initiated. The API request will start the procedure and confirm a pending completion.

Trip will have status processing_completion while it's in procedure of completion.

Response - completion pending

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

HTTP 202 (Accepted)

Response - completed trip

{
  "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"
  },
  "summary": {
    "distance": 821,
    "steps": 36,
    "duration": 300,
    "start_address": "1 Embarcadero Center, San Francisco, CA, 94122",
    "end_address": "353 Sacramento St, San Francisco, CA, 94122",
    "start_datetime": "2019-05-22T04:30:43.137000Z",
    "end_datetime": "2019-05-22T04:35:43.137000Z",
    "segments": [{
      "type": "drive",
      "distance": 645,
      "steps": 36,
      "start_place": "Battery Street",
      "end_place": "Steiner Street",
      "start_datetime": "2019-05-22T04:30:43.137000Z",
      "end_datetime": "2019-05-22T04:34:43.137000Z",
      "polyline": [
        [ 29.00450601873392, 41.041697338527136 ],
        [ 29.00139435450409, 41.04086798406123 ],
        [ 28.999380736837104, 41.040288190483196 ]
        , ... ]
    }, ... ]
  }
}

HTTP 200 (OK)

As soon as the trip was completed on HyperTrack systems, it will be extended with a summary property. Please see the trip references for the JSON object structure.

Completed trips do not have an estimate property because routing was completed.

Webhooks

This guide provides an overview of Webhooks for the following HyperTrack features:

About Webhooks

HyperTrack’s Webhooks allow systems to be notified programmatically about key moments in the movement tracking of their devices, as they happen. To learn the basics of webhook concepts, please read this guide.

Webhooks Features

The following Webhooks are posted.

Location

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

Device Status

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

Battery

Battery status changes. Values include low, normal and charging

Trips

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

Trip creation

For every new trip, creation 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. These include a trip summary.

Trip markers

Trip markers (formerly "custom events") can be added to the movement data stream by your app. The markers are posted in addition to the movement status (location, activity, device health and more)

Webhooks Use Cases

Developers use webhooks to build

Webhooks Architecture

The HyperTrack mobile SDKs send a time-series of events from the device to the HyperTrack server. These events are processed and then posted to your servers on Webhooks. A webhook is an HTTPS POST call from the HyperTrack servers to a configurable destination.

architecture

After receiving a webhook on your own server, you can trigger updates on your mobile or web apps in near real-time and implement your live location features.

Webhooks Setup

Setting up HyperTrack Webhooks requires configurations on your server and the HyperTrack dashboard. Finally, you need to complete a one-time activation process to verify your identity as the subscriber of the endpoint set on the HyperTrack dashboard. Please ensure you follow all three guidelines to start receiving webhooks.

Server setup

The server receiving webhooks needs to be configured appropriately to consume webhooks.

Static Endpoint URL

Your server needs to expose a public HTTPS endpoint capable of receiving external, incoming requests. It is important to have a static endpoint URL that will be accessible at all times.

HTTPS POST Method

Webhooks are realized through HTTPS POST requests to the configured endpoint. Your server needs to support this method and be able to parse the payload provided with the request.

JSON Payload

The payload you will receive with POST requests is formatted in JSON. You need to implement the capability to parse JSON objects in order to leverage the HTTP request body content.

You should use a JSON parser that handles converting the escaped representation of control characters back to their ASCII character values (for example, converting \n to a newline character). This is critical if you want to verify the signature of a webhook.

SSL Verification

By default, we verify the SSL certificate of your website when delivering webhook payloads. SSL verification helps ensure that webhooks are delivered to your endpoint URL securely. We only support HTTPS endpoints to ensure secure server-to-server communication.

Make sure that your endpoint has a server certificate from a trusted Certificate Authority (CA). Amazon SNS will only send messages to HTTPS endpoints that have a server certificate signed by a CA trusted by Amazon SNS.

Dashboard setup

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

setup screen

Just enter your webhook URL and click on "Add Webhook". The screen will ask you to verify your webhook URL to start receiving events. The verification is a one-time activation and described below.

verification pending

One-Time Activation

verification process

{
  "Type": "SubscriptionConfirmation",
  "MessageId": "c0216cf3-8f2e-4aae-b678-ccf18a5cb63c",
  "Token": "2336412f37fb687f5d51e6e241dbca52e99b",
  "TopicArn": "arn:aws:sns:us-west-2:012432584802:location_b29fe",
  "Message": "You have chosen to subscribe to the topic arn:aws:sns:us-west-2:012432584802:location_b29fe.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
  "SubscribeURL": "https://sns.us-west-2.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-west-2:012432584802:location_b29fe",
  "Timestamp": "2019-06-11T13:36:08.195Z",
  "SignatureVersion": "1",
  "Signature": "kWr8Z1vgKrN+uS3sOUYTRHTSP3Jhd5cLLWbW9lkBQHgt7JWtAt",
  "SigningCertURL": "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-69.pem"
}

As soon as your webhook status is set to ‘Pending verification’, you should notice a confirmation message (HTTPS POST) on your server. The message is coming from the AWS SNS Service HyperTrack is using to handle webhook subscription. The message is in JSON and looks like this:

You should implement your server to handle the subscription confirmation request. You can identify the message type by looking at the HTTPS POST request headers. The relevant header is x-amz-sns-message-type. For the confirmation message above it is set to SubscriptionConfirmation.

To complete the verification, you should read the value for SubscribeURL and visit the URL indicated. You can make an HTTP GET request to the URL either programmatically, by using a command-line tool (cURL), or using a web browser. The request will return an XML document that looks like this:

<ConfirmSubscriptionResponse xmlns="http://sns.amazonaws.com/doc/2010-03-31/">
  <ConfirmSubscriptionResult>
    <SubscriptionArn>arn:aws:sns:us-west-2:012432584802:location_b29fe6c9-27ef-4551-b3ee-8bb3ec000a3b:658eb789-eb17-4694-9575-83b1591df841</SubscriptionArn>
  </ConfirmSubscriptionResult>
  <ResponseMetadata>
    <RequestId>68f77c42-6e72-5e0e-a60a-293905d68d9a</RequestId>
  </ResponseMetadata>
</ConfirmSubscriptionResponse>

The document returns the subscription ARN for the endpoint within the ConfirmSubscriptionResult element. Ensure to store the SubscriptionARN as a string for webhook signature verification (next chapter).

Your one-time verification is now complete and you should start receiving webhooks from HyperTrack. Your dashboard will confirm the completion of this process.

complete setup screen

Receive

With webhooks set up, you will start receiving webhooks from HyperTrack. In this chapter, you will learn how to receive appropriately.

Payload and Headers

Webhooks from HyperTrack will be sent with headers and a JSON payload. Please ensure to verify the headers and implement your server to handle these correctly.

Header: Content-Type

The header is set to text/plain for all webhooks. Please ensure to parse every webhook with this content type. The actual content is represented in JSON.

Header: x-amz-sns-message-type

The header is set to Notification for all webhooks.

Header: x-amz-sns-message-id

The header uniquely identified the webhook. It is important to keep track of the webhook ID because under some circumstances like retries, duplicated webhooks with the same ID could be sent to your server. It is suggested to log most recent webhook IDs to ensure you avoid processing the same update multiple times.

Header: x-amz-sns-subscription-arn

The ARN for the subscription to this URL endpoint. You received this with the subscription confirmation response in XML format during the one-time verification.

JSON Payload

[
  {
    "created_at": "2019-07-01T20:00:01.247377Z",
    "recorded_at": "2019-07-01T20:00:00.000000Z",
    "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
    "type": "location",
    "version": "2.0.0",
    "data": {
      // structure based on type of webhook
    }
  }
]

Depending on the type of webhook, the JSON payload will vary. However, the overall structure is fixed.

Currently, the following types are supported:

Feature Type Description
Locations location Location stream
Device Status device_status Device status changes (active, inactive, disconnected and activity changes)
Battery battery Battery changes (low, normal and charging)
Trips trip Trip creation, destination arrival, destination exit, trip delays, and trip completion events

For a complete reference on JSON payload structure, please refer to our Webhook reference.

Responding to webhooks

Make sure to respond to HyperTrack webhooks with the appropriate status code. The connection will time out in 15 seconds. If your endpoint does not respond before the connection times out or if your endpoint returns a status code outside the range of 200–4xx, HyperTrack will consider the delivery of the webhook as a failed attempt and retry as described below.

Retry algorithm

If HyperTrack doesn't receive a successful response from your server, it attempts to deliver the webhook again. By default, if the initial delivery of the webhook fails, HyperTrack attempts up to three retries with a delay between failed attempts set at 20 seconds.

The retries will always refer to the same x-amz-sns-message-id. By comparing the IDs of the webhooks you have processed with incoming webhooks, you can understand whether the message is a retry attempt.

Order of webhooks

HyperTrack will attempt to deliver webhooks in the same order they were received. However, network issues could potentially result in out-of-order webhooks.

Before handling events, you should compare the recorded_at property of the JSON payload and ensure to store events in the order they were recorded as opposed to when they were received.

Process

With a complete setup and webhook receiving in place, you can start processing the actual movement events.

Identifying devices with metadata

In most cases, it is sufficient to use the device_id field to match a device with your own set of records. However, sometimes additional metadata or a readable device name are important.

The mobile SDKs enable you to set a custom device name and attach additional metadata to a device (Android or iOS). If set, you can use the device_id with the Devices API to obtain the metadata. For more details, please read the API reference.

Locations

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

Drawing location streams on a map

Storing past location events will enable you to draw polylines on a map to show the route a device took. Below are code samples for your implementation.

Device status

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

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).

Current, HyperTrack supports 6 types of activity transitions: walk, run, drive, cycle, stop, and moving.

Stop and moving are the most general transitions. If the device can classify the activity, it will use the specific type as opposed to the general moving activity transition.

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

Battery updates

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

Trips Updates

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

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 (creation, 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.

Views

This guide provides an overview of Views for the following HyperTrack features:

About Views

HyperTrack’s Views allow to embed and share responsive UIs showing the device and movement data on a map. Using HyperTrack Views removes the need to build your own server to receive, manage and provision live location data to your front-ends. It further removes the need to develop map views.

Views Features

Views are provided in two variants.

Embed

HyperTrack Views can be embedded to provide the same experience as seen on the HyperTrack Dashboard.

Share

HyperTrack also provides shareable views with limited functionality. Shareable views are intended to be shared with end users to track single trips or single devices of relevance.

Key differences

The key differences between share and embed Views are outlined below.

Feature Share View Embed View
Interaction Responsive views optimized for end users Fully interactive with transitions between views
Available views Single device Devices overview, single device, history overview, single device history
Access control Publically accessible Publishable Key required
Accessibility Short trck.at URL hypertrack.com URL
Sharing Disabled Enabled

Views Use Cases

Developers use views to build

Views Architecture

views arhcitecture

HyperTrack Views are implemented in HTML and require JavaScript to run successfully. All views provided are responsive and can be accessed on desktop, tabled, or mobile devices.

While the shareable Views are simple HTML websites with a short URL, embeddable Views require to be integrated into your application using HTML Iframes.

Authentication for embed views

# access requires a publishable key
# replace {publishable_key} with your own key
https://embed.hypertrack.com/devices?publishable_key={publishable_key}

While shareable Views are accessible to everyone with the URL, embed views require the HyperTrack publishable key to work:

Views Setup

Using HyperTrack Views requires that you:

With access to the HyperTrack dashboard and tracked devices, you can easily obtain sharing URLs and HTML code required to embed Views.

Access shareable views

shareable views can be generated in 3 different ways.

Dashboard share button

# Share button is available on the single device view
https://dashboard.hypertrack.com/devices/{device_id}

share button

The dashboard single device view has a sharing button in the right bottom corner. A click on the button will copy the shareable URL pointing to the live device view.

Devices API

Devices API responses include a views property with a share_url. More details can be found in the Devices API reference.

Trips API

Just like the Devices API, HyperTrack generates live views for active trips. More details can be found in the Trips API reference.

Embed views

Similar to shareable views, there are 3 ways to get URLs for embeddable Views.

Dashboard code button

# Coding view instructions
const baseUrl = "https://embed.hypertrack.com/devices"
const publishableKey = "xyz"

# Embeddable widget for Get Devices Status
<iframe width="400px" height="400px" src=`{baseUrl}?publishable_key={publishableKey}` />

code button

For every view that can be embedded, you will find a <-> Code button on the top right corner of the view. Clicking on that button will unfold a syntax-highlighted coding view with instructions to embed the current view.

The following dashboard views have the code button at this time:

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:

Devices API

Devices API responses include a views property with an embed_url. More details can be found in the Devices API reference.

Trips API

Just like the Devices API, HyperTrack generates embeddable views for active trips. More details can be found in the Trips API reference.

Embed

Devices overview

# Devices Overview URL
https://embed.hypertrack.com/devices

device overview

The devices overview shows a map with a list of all available devices, grouped by device status. For every device that provided a location in the past, a dot will be displayed on the map. A click on the device in the list will zoom into the last known location on the map. It will also open a device status popup (see below). Another click on the dot will open up the single device view.

device status popup

The device status popup provides the following details:

Review device status

In the list view, devices are grouped by active, inactive, and disconnected. Below is a description of the classification.

devices list

Active: The device is actively sending movement data to HyperTrack systems. Active devices are represented with a green dot on the live map.

Inactive: The device cannot send movement data to HyperTrack systems for known reasons (also referred to as outage). Inactive devices are represented with a gray dot on the live map and the inactive icon icon in the device overview.

Disconnected: The device is expected to send data to HyperTrack systems but it hasn’t been for over an hour. HyperTrack systems are usually able to understand and report the reason for the disconnect when the device reconnects. Disconnected devices are represented with a gray dot on the live map and the disconnected icon icon in the device overview.

Live device view

# Live Device View URL
https://embed.hypertrack.com/devices/{device_id}

live device view

The live device view shows a map with the last known locations of the selected device. For every location update since the opening of the view, a new dot will be placed on the map to show the route of the device.

For the most recent location update, the green dot (with a white outline) can have different styles to convey additional information:

Review device details

device details

The device details popup shows a summary of all known device and movement attributes:

A click on the information icon next to the device name/ID will display further device details, including:

Device history view

# Device History View URL
https://embed.hypertrack.com/devices/history{device_id}

device history view

The single device history view shows a map of the location and activity data for the past 12 hours. The map shows a green dot for every location update and an activity icon for every activity update. You can click on every dot to see further details on the update.

To access the single device history view from within the HyperTrack dashboard, you can navigate to the single device view. You should see a history button in the bottom right corner:

history button

Identify activity changes

A click on the location or activity update will open up a popup with further details:

activity button

The following details are listed in the popup:

For your convenience, the popup provides a feature to copy the details of the update. A click on <-> Copy Data will store one of the following JSON in your clipboard (depending on the update type).

Activity update data

{
  "device_id": "704C6AE3-C298-4608-B330-A18ADA20B34F",
  "recorded_at": "2019-07-01T15:01:02.690000Z",
  "type": "activity",
  "pedometer": {
    "time_delta": 5106,
    "number_of_steps": 56
  },
  "value": "cycle",
  "index": 103,
  "timezone": "America/Los_Angeles"
}
Field Type Description
device_id string Unique identifier representing a device, case sensitive
recorded_at string Timestamp for the location of activity update
type string Defines the structure of the JSON object. Can be one of location or activity.
pedometer object Step tracking data. Only available for activities other than stop.
pedometer.time_delta int Time of activity in seconds
pedometer.number_of_steps int Number of steps in this activity
value string Activity type. Can be one of stop, walk, run, drive, or cycle (more details).
index int Counter of activity updates since initialization of the device?
timezone string The timezone on the device in TZ format

Location update data

{
  "device_id": "704C6AE3-C298-4608-B330-A18ADA20B34F",
  "recorded_at": "2019-07-01T14:59:00.997000Z",
  "type": "location",
  "speed": 12.280691501233681,
  "location": {
    "type": "Point",
    "coordinates": [37.868282261644616, -122.28401381798933]
  },
  "accuracy": 14.97022062435497,
  "bearing": 1.5546167296350293,
  "altitude": 24.362770905499346,
  "timezone": "America/Los_Angeles"
}
Field Type Description
device_id string Unique identifier representing a device, case sensitive
recorded_at string Timestamp for the location of activity update
type string Defines the structure of the JSON object. Can be one of location or activity.
speed float Speed of travel in meters per second
location object GeoJSON with Point type
accuracy float Accuracy in meters
bearing float The horizontal direction of travel in degrees (more details)
altitude float Device elevation in meters
timezone string The timezone on the device in TZ format

Share

Live device view

# Tracking URL
https://trck.at/{tracking_id}

live device view share

As described in the setup chapter, you can obtain a tracking URL in various ways. Once opened, the shared view will display the live device view with limited functionality (no interaction to other screens like history and no sharing capability).

Exports

History data exports give you access to all tracked location, movement, trip markers, and summary data on AWS S3. Data engineers use this to power upstream applications and data models.

Data Export requirements

Using History Exports requires that you:

File Format

gzipped json line

Schedule

Daily data exports will be available by 06:00 AM UTC.

JSON format

The exported data is in JSON format and contains the individual data points of all your devices. The export JSON object structure is always the same and event_type defines the structure of event_data.

{
  "event_id": "2D8A5658-7ADC-47A7-A108-09DDD387E088",
  "device_id": "123E4567-E89B-12D3-A456-426655440000",
  "client_creation_time": "2019-04-30T14:25:01Z",
  "server_received_time": "2019-04-30T14:25:04.635880",
  "event_type": "",
  "event_data": ""
}
name type description
event_id string Unique event identifier, case sensitive
device_id string Unique device identifier, case sensitive
client_creation_time string ISO 8601 date string when event was created on device
server_received_time string ISO 8601 date string when event was processed on HyperTrack’s servers
event_type string Type of the event. Indicates if the row is a location, activity, health, or summary event
event_data string Event data as serialized JSON string (with new lines as \n), structure based on event_type as described below

Location data

{
  "accuracy": 32.0,
  "altitude": 154.0,
  "location": {
    "type": "Point",
    "coordinates": [-122.50365362344037, 37.761003414611174]
  },
  "speed": 1.2,
  "bearing": 217.03
}
Name Type Description
location object Location in GeoJSON format
location.type string As of right now, only Point is supported
location.coordinates array Array of longitude and latitude
speed float (optional) speed in m/s
altitude float (optional) altitude in m
accuracy float (optional) accuracy in m
bearing float (optional) bearing in degrees starting at due north and continuing clockwise around the compass

Activity data

{
  "value": "stop"
}
Name Type Description
value string Activity type. Could be one of walk, run, drive, cycle, stop, moving

Health data

Device health data showing tracking outages and resumptions. Health data is available for outage events when an outage effects location data.

{
  "value": "outage.stopped",
  "hint": ""
}
Name Type Description
value string Health event type. Possible values listed here
hint string (optional) details about the reason for the outage provided by the OS. Subject to change

Summary Data

{
  "distance": 821,
  "steps": 36,
  "duration": 300,
  "start_datetime": "2019-05-22T04:30:43.137000Z",
  "end_datetime": "2019-05-22T04:35:43.137000Z",
  "start_address": "1 Embarcadero Center, San Francisco, CA, 94122",
  "end_address": "353 Sacramento St, San Francisco, CA, 94122",
  "segments": [
    {
      "type": "drive",
      "distance": 640,
      "steps": 36,
      "start_place": "Franklin Street",
      "end_place": "Fillmore Street",
      "start_datetime": "2019-05-22T04:30:43.137000Z",
      "end_datetime": "2019-05-22T04:34:43.137000Z",
      "polyline": [
        [29.00450601873392, 41.041697338527136],
        [29.00139435450409, 41.04086798406123],
        [28.999380736837104, 41.040288190483196]
      ]
    }
  ]
}
Name Type Description
distance int Distance of all segments in meters
steps int Number of steps of all segments
duration int Duration of all segments in seconds
start_address string Start address for the trip summary
end_address string End address for the trip summary
duration int Duration of all segments in seconds
segments array Array of segments
segments.type string Type of segment. Possible values are: run, drive, cycle, stop, moving, outage.denied, outage.software, outage.stopped, outage.hardware, outage.disabled
segments.distance int Segment distance in meters
segments.steps int Steps added during segment
segments.start_datetime string ISO 8601 date when segment started
segments.end_datetime string ISO 8601 date when segment ended
segments.polyline array Array of GPS coordinates in historical order(longitude first, latitude second)
segments.start_place string Place where segment started
segments.end_place string Place where segment ended

Trip markers

This data contains the individual data points of all your devices.

{
  "event_id": "11112233-4455-6677-8899-aabbccddeeff",
  "device_id": "123E4567-E89B-12D3-A456-426655440000",
  "client_creation_time": "2019-04-17T08:37:18.979Z",
  "server_received_time": "2019-04-17T08:37:20.528118",
  "custom_event_data": "{\"amount\": 1.0, \"item\": \"Foobar\"}",
  "location_event_id": "ac43e815-af20-4e27-9770-794c339151ee",
  "location_data": "{\"altitude\": 815.2000122070312, \"location\": {\"coordinates\": [77.6328431, 12.9289112], \"type\": \"Point\"}, \"accuracy\": 27.252, \"bearing\": 0.0, \"speed\": 0.0}",
  "location_client_creation_time": "2019-04-17T08:37:12.827000Z",
  "activity_event_id": "4223bc0b-610f-4aad-af9d-e181e40b5293",
  "activity_data": "{\"value\": \"stop\"}",
  "activity_client_creation_time": "2019-04-17T08:36:53.747000Z",
  "health_event_id": null,
  "health_data": null,
  "health_client_creation_time": null
}
name type description
event_id string Unique event identifier, case sensitive
device_id string Unique device identifier, case sensitive
client_creation_time string ISO 8601 date string when event was created on device
server_received_time string ISO 8601 date string when event was processed on HyperTrack’s servers
custom_event_data string Data submitted as part of the trip marker
location_event_id string Unique event identifier of location event (see movement data), case sensitive
location_data string Location data (see movement data)
location_client_creation_time string Client timestamp of location event (see movement data)
activity_event_id string Unique event identifier of activity event (see movement data), case sensitive
activity_data string Activity data (see movement data)
activity_client_creation_time string Client timestamp of activity event (see movement data)
health_event_id string Unique event identifier of outage event (see movement data), case sensitive
health_data string Health data (see movement data)
health_client_creation_time string Client timestamp of health event (see movement data)

References

Webhook

Webhooks let you subscribe to a real-time stream of location, and trip status data generated by HyperTrack. Rather than making an API call, HyperTrack can send an HTTPS request to an endpoint that you specify. Events are published for all devices associated with the account.

Webhook Payload

The overall POST payload has a static structure. The type of the webhook indicates the structure of the data object.

[{
  "created_at": "2019-02-27T22:50:29.000000Z",
  "data": { ... },
  "location": { ... },
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "recorded_at": "2019-02-27T22:50:24.000000Z",
  "type": "",
  "version": "2.0.0"
}]
Name Type Description
device_id string Unique device identifier, case sensitive
created_at string ISO 8601 date and time when webhook was sent (server timestamp)
recorded_at string ISO 8601 date and time when event was recorded (client timestamp). Not available for trip webhooks for creaiton of completion.
type string Type of webhook data. Could be either location, device_status, battery or trip
data object Either location, device_status, battery or trip data, see details below.
location object GeoJSON object with type and coordinates. Provided as context to trip delay webhooks only
version string Version string of the webhook. Current version is "2.0.0"

Location Payload

{
    "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": {
        "accuracy": 9.64,
        "geometry": {
            "type": "Point",
            "coordinates": [
                -6.2755,
                57.6398983
                124
            ]
        },
        "speed": 0.0,
        "bearing": 313.94
    },
    "version": "2.0.0"
}
Name Type Description
data.geometry object Location in GeoJSON format
data.geometry.type string As of right now, only Point is supported
data.geometry.coordinates array Array of longitude, latitude and (optional) altitude (in m)
data.accuracy float (optional) accuracy in m
data.bearing float (optional) bearing in degrees starting at due north and continuing clockwise around the compass
data.speed float (optional) speed in m/s

Device Status Payload

{
    "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"
}
Name Type Description
data.value string Device status. One of active, inactive or disconnected
data.activity string For active devices only, can be one walk, run, drive, cycle, stop, moving
data.reason string For inactive devices only. Can be one of denied/disabled (user denied/disabled permissions) or stopped (tracking was stopped programmatically from host application)
location object Location in GeoJSON format
location.type string As of right now, only Point is supported
location.coordinates array Array of longitude latitude and (optional) altitude (in m)

Battery Payload

{
    "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"
}
Name Type Description
data.value string Battery status. Values include low, normal and charging
location object Location in GeoJSON format
location.type string As of right now, only Point is supported
location.coordinates array Array of longitude latitude and (optional) altitude (in m)

Trip 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"
}

If you create trips, you will receive trip events whenever ...

Name Type Description
data.value string One of: created, destination_arrival, destination_exit, delayed or completed
data.trip_id string Unique identifier of the trip, case sensitive
data.trip_metadata Object Metadata that you have assigned to this trip (optional)
data.summary Array Trip Summary object (see below), only available if value is completed
data.arrive_at string Timestamp with new arrived date, only available if value is delayed

Trip Summary

{
  "summary": {
    "distance": 821,
    "steps": 1032,
    "duration": 9887,
    "start_datetime": "2019-08-08T18:04:20.467000Z",
    "end_datetime": "2019-08-08T20:49:08.226000Z",
    "start_address": "California St & Battery St, San Francisco, CA 94111, USA",
    "end_address": "3356 Steiner St, San Francisco, CA 94123, USA",
    "segments": [
      {
        "type": "drive",
        "distance": 642,
        "duration": 664,
        "steps": 862,
        "start_place": "Battery Street",
        "end_place": "Steiner Street",
        "start_datetime": "2019-08-08T18:27:35.793000Z",
        "end_datetime": "2019-08-08T18:38:40.548000Z",
        "polyline": [
          [ -122.39961422286062, 37.79396136184457 ],
          [ -122.39982803643629, 37.79423869055751 ],
          ...
        ]
      },
       ...
    ]
  }
}

For every completed trip, a trip summary is provided.

Name Type Description
summary.distance int Distance for entire trip, in meters
summary.steps int Number of steps for entire trip
summary.duration int Duration for entire trip, in seconds
summary.start_datetime string ISO 8601 date of first segment start
summary.end_datetime string ISO 8601 date of last segment end
summary.start_address string Address of trip origin
summary.end_address string Address of trip destination
summary.segments array Array of segments, could be empty
summary.segments[].type string Type of segment, values associated either with status or activity (see below)

Trip Summary: Activity Segments

For segments associated with activity (run, drive, cycle, stop, moving), the following structure is privded.

{
  "type": "drive",
  "distance": 120,
  "steps": 36,
  "duration": 320,
  "start_place": "Franklin Street",
  "end_place": "Fillmore Street",
  "start_datetime": "2019-05-22T04:30:43.137000Z",
  "end_datetime": "2019-05-22T04:34:43.137000Z",
  "polyline": [
    [29.00450601873392, 41.041697338527136],
    [29.00139435450409, 41.04086798406123],
    [28.999380736837104, 41.040288190483196]
  ]
}
Name Type Description
data.segments.type string Type of segment. Possible values are: run, drive, cycle, stop, moving
data.segments.distance int Segment distance in meters
data.segments.duration int Duration of the activity segment in secods
data.segments.steps int Steps during the activity segment
data.segments.start_datetime string ISO 8601 date when segment started
data.segments.end_datetime string ISO 8601 date when segment ended
data.segments.polyline array GPS coordinates in historical order (longitude first, latitude second)
segments.start_place string Place where segment started, only for drive segments
segments.end_place string Place where segment ended, only for drive segments

Trip Summary: Status Segments

For segments associated with status updates (outage.denied, outage.software, outage.stopped, outage.hardware, outage.disabled), the following structure is privded.

{
  "type": "outage.software",
  "start_datetime": "2019-07-19T02:43:03.684000Z",
  "end_datetime": "2019-07-19T02:48:24.472000Z",
  "hint": "sdk.killed",
  "duration": 320
}
Name Type Description
data.segments.type string Type of segment
data.segments.hint string Status hint. Additional information about the status event
data.segments.duration int Duration of the status segment in secods
data.segments.start_datetime string ISO 8601 date when segment started
data.segments.end_datetime string ISO 8601 date when segment ended

Android SDK

This reference shows methods available in the Android SDK. You can also review the generated JavaDoc files.

Initialize (Android)

Initialize the SDK with your activity and publishable key only.

If you don't want SDK to start tracking and/or request data access permissions immediately, you can use one of overloaded initialize variants and set startTracking or stopTracking to control the tracking status.

HyperTrack.initialize(MyActivity.this, 'your-publishable-key-here');
Parameter Type Description
activity Activity Will be used to add permission request fragment (if required) and to access application's Context
publishableKey String Your publishable key from the dashboard

Initialize with handler (Android)

Initialize the SDK with your activity, publishable key, and a handler.

If you don't want SDK to start tracking and/or request data access permissions immediately, you can use one of overloaded initialize variants and then use pair startTracking(boolean, TrackingInitDelegate) stopTracking() to control tracking status.

class myInitDelegate implements TrackingInitDelegate {
    public void onSuccess() {
        // invoked on successful result
    }

    public void onError(TrackingInitError error) {
        // invoked only in case of failure
    }
}

...

HyperTrack.initialize(MyActivity.this, "your-publishable-key-here", myInitDelegate);
Parameter Type Description
activity Activity Will be used to add permission request fragment (if required) and to access application's Context
publishableKey String Your publishable key from the dashboard
trackingInitDelegate TrackingInitDelegate Handler for initialization result

Initialize with handler and config (Android)

Initialize the SDK with your activity, publishable key, custom configuration, and a handler.

// define the handler
class myInitDelegate implements TrackingInitDelegate {
    public void onSuccess() {
        // invoked on successful result
    }

    public void onError(TrackingInitError error) {
        // invoked only in case of failure
    }
}

...

// initialize the SDK without a handler and disable tracking.
HyperTrack.initialize(MyActivity.this, "your-publishable-key-here", false, false, null);

...

// enable tracking later and pass in new handler.
HyperTrack.startTracking(true, myInitDelegate);
Parameter Type Description
activity Activity Will be used to add permission request fragment (if required) and to access application's Context
publishableKey String Your publishable key from the dashboard
shouldStartTracking boolean Start tracking automatically after initialization
shouldRequestPermissionIfMissing boolean Present permission request dialog if permissions are missing
trackingInitDelegate TrackingInitDelegate Handler for initialization result

Start tracking (Android)

Start tracking. Only required if SDK was initialized without tracking or tracking was stopped before.

class myInitDelegate implements TrackingInitDelegate {
    public void onSuccess() {
        // invoked on successful result
    }

    public void onError(TrackingInitError error) {
        // invoked only in case of failure
    }
}

HyperTrack.startTracking(true, myInitDelegate);
Parameter Type Description
shouldRequestPermissionIfMissing boolean Present permission request dialog (if needed)
delegate TrackingInitDelegate Handler for initialization result (optional)

Stop tracking (Android)

Stop tracking.

HyperTrack.stopTracking();

Check tracking status (Android)

Check tracking status.

HyperTrack.isTracking();

Get device ID (Android)

Obtain device identifier. Returns an empty string if SDK was not yet initialized.

String deviceID = HyperTrack.getDeviceId();

Set name and metadata (Android)

Set name and metadata for device tracking data.

// create new metadata map
Map<String,Object> myMetadata = new HashMap<>();

// add external id to metadata
myMetadata.put('external-id', 'your-external-id');

HyperTrack.setNameAndMetadataForDevice('your-custom-device-name', myMetadata);
Parameter Type Description
name String Custom device name (optional)
metaData Map Custom metadata as key-value pair (optional)

Create trip marker (Android)

Create a trip marker with configurable payload. Please, bear in mind that this will be serialized as JSON.

// create new marker payload
Map<String,Object> payload = new HashMap<>();

// add event details
payload.put("item", "Martin D-18");
payload.put("previousOwners", Collections.emptyList());
payload.put("price", 7.75);

HyperTrack.tripMarker(payload);
Parameter Type Description
payload Map Trip marker data as key-value pair

Customize notification (Android)

HyperTrack tracking runs as a separate foreground service. When tracking is activated, users will see a persistent notification. By default, it displays the app icon with text {app name} is running. You can customize the notification appearance.

HyperTrack.addNotificationIconsAndTitle(
    R.drawable.ic_small,
    R.drawable.ic_large,
    notificationTitleText,
    notificationBodyText
);
Parameter Type Description
smallIconId int Small icon ID
largeIconId int Large icon ID
title String Title (optional). Set to null to keep the default title
body String Body (optional). Set to null to keep the default body

Android Views

Android Views are implemented using GraphQL subscriptions and enable server-to-client communication without the need to integrate Webhooks on the backend.

The module handles websockets and provides easy-to-consume methods to retrieve device status and subscribe to programmatic notifications about key moments in the movement tracking of devices and trips, as they happen.

Get device status

// Get SDK instance with Context reference
// replace <PUBLISHABLE_KEY> with your own key
HyperTrackViews hypertrackView = HyperTrackViews.getInstance(this, <PUBLISHABLE_KEY>);

// replace <DEVICE_ID> with your device ID
hypertrackView.getDeviceMovementStatus(<DEVICE_ID>,
    new Consumer<MovementStatus>() {
        @Override
        public void accept(MovementStatus movementStatus) {
            Log.d(TAG, "Got movement status data " + movementStatus);
        }
    });
val hyperTrackView = HyperTrackViews.getInstance(this, PUBLISHABLE_KEY)
        hyperTrackView.getDeviceMovementStatus(DEVICE_ID)
        {Log.d(TAG, "Got movement status $it")}

Get device information by device ID. The callback receives a MovementStatus object describing the device.

Movement Status

The device movement status object encapsulates all data associated with a device, similar to the Device API. It provides the latest snapshot of the device state, including ...

Location Object
Location location = movementStatus.location;
if (location != null) {
  Log.d(TAG, "Got device location " + location +
  " with latitude " + location.getLatitude() +
  " and longitude " + location.getLongitude());
}
val location = movementStatus?.location
location?.let {
  Log.d(TAG, "Got device location $location " +
          "with latitude ${location.latitude}" +
          "and longitude ${location.longitude}")
Accessor method Type Description
getLatitude() double Latitude in degrees. Negatives are for southern hemisphere.
getLongitude() double Longitude in degrees. Negatives are for western hemisphere.
getAltitude() Double Altitude in m. Could be null, if value is not available.
getSpeed() Double Speed in m/s. Could be null, if device is stationary
getBearing() Double Bearing in degrees starting at due north and continuing clockwise around the compass
getAccuracy() Double Horizontal accuracy in m
getRecordedAt() String ISO 8601 date when the location was recorded
Device Status Object
DeviceStatus status = movementStatus.deviceStatus;
if (status != null) {
  Log.d(TAG, "Device is " + (status.isDisconnected() ? "disconnected" : "connected"));
}
val status = movementStatus?.deviceStatus
status?.let {
    Log.d(TAG, "Device is ${(if (status.isDisconnected) "disconnected"  else "connected")}")
}
Member Type Description
createdAt String ISO 8601 date when the device status was created
isActive() boolean Returns true if device is active (it's current location is known and updated) and false otherwise
isDisconnected() boolean Returns true if device is disconnected (it's location wasn't updated for a while) and false otherwise
isInactive() boolean Returns true if tracking data is unavailable because of lack of permissions or tracking was stopped intentionally and false otherwise
status int Property provides more extended description of current state, e.g. whether it it is driving, if active, etc. See JavaDoc for the list of possible values and their meaning.
Device Info Properties
DeviceInfo deviceInfo = movementStatus.deviceInfo;
if (deviceInfo != null) {
    Log.d(TAG, "Got status for device " + deviceInfo.name);
}
val deviceInfo = movementStatus?.deviceInfo
deviceInfo?.let {
    Log.d(TAG, "Status from device ${deviceInfo.name}")
}
Parameter Type Description
appName String Name of the hosting app
appVersionNumber String Version of the hosting app
appVersionString String Version of the hosting app
deviceBrand String The device brand
deviceModel String The device model
name String The name of the device
osName String The operating system of the device, can be one of iOS or Android
osVersion String The version of the operating system on the device
sdkVersion String The HyperTrack SDK version on the device. Can be reviewed here: Android, iOS, React Native
DeviceViewUrls Properties

This object incapsulates resources that could be used to open WebView Widget (embedded view) or for sharing location via link. java String shareUrl = movementStatus.deviceViewUrls.embedUrl; Uri uri = Uri.parse(shareUrl + PUBLISHABLE_KEY); Intent intent = new Intent(Intent.ACTION_VIEW, uri); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } kotlin val shareUrl = movementStatus.deviceViewUrls.embedUrl val uri = Uri.parse(shareUrl!! + PUBLISHABLE_KEY) val intent = Intent(Intent.ACTION_VIEW, uri) if (intent.resolveActivity(packageManager) != null) { startActivity(intent) }

Parameter Type Description
embedUrl String Embeddable view URL
shareUrl String Sharable view URL
Trip Properties
Trip{
    tripId="3737e382-b251-11e9-a7f6-f6b591671d93",
    startedAt="2019-07-29T22:35:49.963554Z",
    completedAt="",
    status="active",
    destination=Destination{
        geometry=Geometry{
            coordinates=[-122.437941, 37.800563]
        },
        radius=30,
        scheduledAt=""
    },
    estimate=Estimate{ ... },
    metadata="",
    summary=""
}
Method Type Description
getTripId() String Unique identifier of the newly created trip, case sensitive
getStatus() String Trip status, can be either active or completed
getStartedAt() String Timestamp for trip starting time
getMetadata() String Metadata provided at trip creation
getSummary() String Trip summary, only provided upon completion of a trip
getDestination() Trip.Destination Destination of the trip, or null if trip has no destination
getEstimate() Trip.Estimate Trip summary, only provided for trips with status active
getCompletedAt() String ISO 8601 date when the trips was completed or null if it haven't been completed
Trip Estimate Properties
Estimate{
    arriveAt="",
    reroutesExceeded=false,
    route=Route{ ... }
}
Method Type Description
getArriveAt() String Timestamp for estimated arrival
isRerouteExceeded() Boolean Indicates if re-route limit of 10 was exceeded
getRoute() Trip.Route Planned route segments to destination
Trip Route Properties
Route{
    distance=210,
    duration=1720,
    startAddress="1 Embarcadero Center, San Francisco, CA, 94122",
    endAddress="353 Sacramento St, San Francisco, CA, 94122",
    polyline=Polyline{ ... }
}
Method Type Description
getDistance() Integer Timestamp for estimated arrival
getDuration() Integer Indicates if re-route limit of 10 was exceeded
getStartAddress() String Street address lookup for segment start
getEndAddress() String Street address lookup for segment end
getPoints() List of List of Double Planned route segments to destination, as array of longitude, latitude and altitude (optional) tuples
Trip Destination Properties
Destination{
    geometry=Geometry{ ... },
    radius=30,
    scheduledAt="2019-07-29T22:35:49.963554Z"
}
Method Type Description
getLatitude() Double Latitude coordinate of destination center point in degrees. Negatives are for southern hemisphere
getLongitude() Double Longitude coordinate of destination center point in degrees. Negatives are for western hemisphere
getRadius() Integer Radius (in meters) of a circular trip destination
getScheduledAt() String Timestamp for scheduled arrival

Subscribe to updates

// Get SDK instance with Context reference
// replace <PUBLISHABLE_KEY> with your own key
HyperTrackViews hypertrackView = HyperTrackViews.getInstance(this, <PUBLISHABLE_KEY>);

// replace <DEVICE_ID> with your device ID
hypertrackView.subscribeToDeviceUpdates(<DEVICE_ID>,
   new DeviceUpdatesHandler() {
       @Override
       public void onLocationUpdateReceived(@NonNull Location location) {
           Log.d(TAG, "onLocationUpdateReceived: " + location);
       }

       @Override
       public void onBatteryStateUpdateReceived(@BatteryState int i) {
           Log.d(TAG, "onBatteryStateUpdateReceived: " + i);
       }

       @Override
       public void onStatusUpdateReceived(@NonNull StatusUpdate statusUpdate) {
           Log.d(TAG, "onStatusUpdateReceived: " + statusUpdate);
       }

       @Override
       public void onTripUpdateReceived(@NonNull Trip trip) {
           Log.d(TAG, "onTripUpdateReceived: " + trip);
       }

       @Override
       public void onError(Exception e, String deviceId) {
           Log.w(TAG, "onError: ", e);
       }

       @Override
       public void onCompleted(String deviceId) {
           Log.d(TAG, "onCompleted: " + deviceId);
       }
   }
);

You can subscribe to receive device state changes as they come in. The DeviceUpdatesHandler should implement and override the following interface methods:

Method Parameter Description
onLocationUpdateReceived Location Location update
onBatteryStateUpdateReceived BatteryState Battery update, can be one of BATTERY_CHARGING, BATTERY_LOW, and BATTERY_NORMAL
onStatusUpdateReceived StatusUpdate Status update
onTripUpdateReceived Trip Trip update
onError Exception, Device ID (String) Error with exception details and device ID
onCompleted Device ID (String) Completion with Device ID

StatusUpdate Properties

StatusUpdate{
    value="WALK",
    hint="",
    recordedAt="2019-07-29T22:35:49.963554Z"
}
Parameter Type Description
value String Health event type, can be one of CYCLE, DRIVE, MOVING, RUN, STOP, or WALK
hint String Health hint. Additional information about the health event
recordedAt String ISO 8601 date when the device status was recorded

Unsubscribe from updates

hypertrackView.stopAllUpdates();

You can stop receiving updates you are subscribed to.

iOS SDK

This reference shows methods available in the iOS SDK. This reference is split into Swift and Objective C. Please select the appropriate language in the top right panel.

Initialize (iOS)

Initialize the SDK with your publishable key only.

If you don't want SDK to start tracking and/or request data access permissions immediately, you can use one of overloaded initialize variants and set startTracking or stopTracking to control the tracking status.

HyperTrack.initialize(publishableKey: "<#Paste your Publishable Key here#>")
[HTSDK initializeWithPublishableKey: @"<#Paste your Publishable Key here#>"];
Parameter Type Description
publishableKey String Your publishable key from the dashboard

Initialize with handler and config (iOS)

Initialize the SDK with your publishable key, custom configuration, and a handler.

// define an error handler
extension AppDelegate: HyperTrackDelegate {
  func hyperTrack(_ hyperTrack: AnyClass, didEncounterCriticalError criticalError: HyperTrackCriticalError) {
    /// Handle errors here
  }
}

...

// initialize the SDK and disable tracking
HyperTrack.initialize(
    publishableKey: "<#Paste your Publishable Key here#>",
    delegate: self,
    startsTracking: false,
    requestsPermissions: false)

...

// enable tracking later
HyperTrack.startTracking(requestsPermissions: true)
// define an error handler
@interface AppDelegate () <HTSDKDelegate>
@end

@implementation AppDelegate

- (void)hyperTrack:(Class)hyperTrack didEncounterCriticalError:(HTSDKCriticalError *)criticalError {
    /// Handle errors here
}

@end

...

// initialize the SDK and disable tracking
[HTSDK initializeWithPublishableKey:@"<#Paste your Publishable Key here#>"
                           delegate:self
                     startsTracking:false
                requestsPermissions:false];

...

// enable tracking later
[HTSDK startTrackingWithRequestsPermissions:true];
Parameter Type Description
publishableKey String Your publishable key from the dashboard
startsTracking boolean Start tracking automatically after initialization (optional in Swift, true by default)
requestsPermissions boolean Request Location and Motion permissions on your behalf (optional in Swift, true by default)
delegate Handler Error handler for initialization (optional in Swift, nil by default)

The delegate method is called if the SDK encounters a critical error that prevents it from running. This includes:

Start tracking (iOS)

Start tracking. Only required if SDK was initialized without tracking or tracking was stopped before.

HyperTrack.startTracking(requestsPermissions: true)
[HTSDK startTrackingAndRequestPermissions:YES];
Parameter Type Description
requestsPermissions boolean Request Location and Motion permissions on your behalf (optional in Swift, true by default)

Stop tracking (iOS)

Stop tracking.

HyperTrack.stopTracking()
[HTSDK stopTracking];

Check tracking status (iOS)

Check tracking status.

HyperTrack.isTracking
[HTSDK isTracking]

Get device ID (iOS)

Obtain SDK-generated device identifier.

HyperTrack.deviceID
[HTSDK deviceID]

Set name and metadata (iOS)

Set name and metadata for device tracking data.

HyperTrack.setDevice(name: "Device name", andMetadata: nil) { (error) in
    /// Handle errors here
}
[HTSDK setDeviceWithName:@"Device name"
        metadata:nil
        completionHandler:^(HTSDKDeviceNameError * _Nullable error) {
            /// Handle errors here
       }];
Parameter Type Description
name String Custom device name (optional)
metadata Dictionary (String) Custom metadata as string dictionary (optional)
completionHandler Handler Error handler (optional)

Create trip marker (iOS)

Create a trip marker with configurable payload. Please, bear in mind that this will be converted to JSON from a Dictionary type.

HyperTrack.setTripMarker(["custom keys": "custom values"]) { (error) in
    /// Handle errors here
}
[HTSDK setTripMarker:@{ @"custom keys": @"custom values" }
   completionHandler:^(HTSDKCustomEventError * _Nullable error) {
       /// Handle errors here
   }];
Parameter Type Description
metadata Dictionary (String) Trip marker data as a dictionary
completionHandler Handler Error handler (optional)

GeoJSON

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [125.6, 10.1, 123]
  },
  "properties": {
    "name": "Dinagat Islands"
  }
}

The GeoJSON format adopted by HyperTrack is based on the RFC 7946 specification. It is used as a generalized construct to encode geographic data structures using a JSON format. It supports a variety of types, with Point being the most commonly used.

Device status and activity

HyperTrack currently supports the following status and activity types:

Icon Type Description Device connected Movement tracked Activity identified
disconnected icon Disconnected We lost connection with the device unexpectedly (no data received for over an hour)
inactive icon Inactive The device is not trackable for known reasons Yes
unknown icon Unknown The device is moving, activity is unknown Yes Yes
stop icon Stop The device is stationary Yes Yes Yes
walk icon Walk The device is on a walking person Yes Yes Yes
run icon Run The device is on a running person Yes Yes Yes
ride icon Cycle The device is in a bicycle Yes Yes Yes
drive icon Drive The device is in a car Yes Yes Yes

Activity types are provided by the mobile OS using a combination of sensory data on the device combined with machine learning to accurately predict the activity in real-time. For more details, please see the OS references (iOS and Android).

HTTP Errors

We are adopting the RFC 7807 standard for our error messages.

{
    "status": 404,
    "code": "trip_not_found",
    "title": "Trip could not be found",
    "type": "https://docs.hypertrack.com/#trips-api-trip-not-found",
    "detail": "Trip with the id '00112233-4455-6677-8899-AABBCCDDEEFF' does not exist"
}

The standard requires at least the type property. Everything else is optional. For HyperTrack, we always send title, detail, status, and code in addition. To detail out some errors (for instance multiple invalid fields), the append additional properties as documented in the respective error section.

Parameter Type Description
status Number HTTP status code
code String Error class code
title String Brief summary of the error class
type URL URL to the respective error page (about:blank if none is provided)
detail String Detailed description of the error instance
invalid_params Object A list of invalid parameters to review (options)

Trips API Errors

The Trips API can return one of the following errors. Please review the reference carefully to understand the error reasons and potential steps to overcome the issues faced.

Trips API - Unauthorized

{
    "message": "Unauthorized"
}

HTTP 401 (Unauthorized)

Potential reason: The Authorization header in the request is invalid or missing.

Potential actions:

Trips API - Wrong content-type

{
    "status": 400,
    "code": "wrong_content_format",
    "title": "Wrong content format",
    "type": "https://docs.hypertrack.com/#trips-api-wrong-content-type",
    "detail": "The content submitted in the request body is not in valid JSON format"
}

Potential reasons:

Potential actions: Please double check that the body you generate for the request is in valid JSON format. You can use this small tool to ensure your JSON is valid.

Trips API - Trip not found

{
    "status": 404,
    "code": "trip_not_found",
    "title": "Trip could not be found",
    "type": "https://docs.hypertrack.com/#trips-api-trip-not-found",
    "detail": "Trip with the id '00112233-4455-6677-8899-AABBCCDDEEFF' does not exist"
}

Potential reasons:

Potential actions: Ensure that the right ID is used - with uppercase letters and no changes to the format(e.g. don't escape the -).

Trips API - Device not found

{
    "status": 400,
    "code": "device_not_found",
    "title": "Device could not be found",
    "type": "https://docs.hypertrack.com/#trips-api-device-not-found",
    "detail": "Device with the id '00112233-4455-6677-8899-AABBCCDDEEFF' does not exist"
}

Potential reasons:

Potential actions:

Trips API - Route not found

{
    "status": 400,
    "code": "route_not_found",
    "title": "Route could not be found",
    "type": "https://docs.hypertrack.com/#trips-api-route-not-found",
    "detail": "Could not generate a route from the device location to the set destination"
}

Potential reasons:

Potential actions:

Trips API - Validation error

{
    "status": 400,
    "code": "validation_error",
    "title": "Trip request is malformed",
    "type": "https://docs.hypertrack.com/#trips-api-validation-error",
    "detail": "The request format does not have the correct format. Please review the invalid parameters",
    "invalid_params": [
        {
            "name": "destination.geometry.type",
            "reason": "Only supported type is 'Point'. Received 'Polygon' instead"
        }
    ]
}

Potential reasons:

Potential actions: Please review and fix the invalid parameters in invalid_params. You can also use this small tool to ensure your request body complies with our JSON schema for the API call.

Trips API - Completion not possible

{
    "status": 400,
    "code": "completion_not_possible",
    "title": "Trip cannot be completed",
    "type": "https://docs.hypertrack.com/#trips-api-completion-not-possible",
    "detail": "Trip with the id '00112233-4455-6677-8899-AABBCCDDEEFF' cannot be completed"
}

Potential reasons:

Potential actions:

Trips API - Unauthorized

// HTTP Status: 401
{
    "message": "Unauthorized"
}

Potential reasons:

Potential actions:

Trips API - Route creation failed

{
    "status": 500,
    "code": "route_error",
    "title": "Failed to generate the route",
    "type": "https://docs.hypertrack.com/#trips-api-route-creation-failed",
    "detail": "Server could not complete the route generation"
}

Potential reasons:

Potential actions:

Devices API Errors

The Devices API can return one of the following errors. Please review the reference carefully to understand the error reasons and potential steps to overcome the issues faced.

Devices API - Unauthorized

{
    "message": "Unauthorized"
}

HTTP 401 (Unauthorized)

Potential reason: The Authorization header in the request is invalid or missing.

Potential actions:

Devices API - Device not found

{
    "status": 404,
    "code": "device_not_found",
    "title": "Device could not be found",
    "type": "https://docs.hypertrack.com/#devices-api-trip-not-found",
    "detail": "Device with the id '00112233-4455-6677-8899-AABBCCDDEEFF' does not exist"
}

HTTP 404 (Not Found)

Potential reasons:

Potential actions:

Devices API - Method Not Allowed

{
    "status": 405,
    "code": "method_not_allowed",
    "title": "Method Not Allowed",
    "type": "https://docs.hypertrack.com/#devices-api-method-not-allowed",
}

HTTP 405 (Method Not Allowed)

Potential reasons:

Potential actions:

FAQ

We compiled a list of frequently asked technical questions below. If you these do not answer your questions, please send us an email and we will get back to you as soon as possible.

We currently support Android (API version 19+, starting with Android 4.4 Kit Kat) and iOS (version 10+) devices through native SDKs. All devices need to have GPS modules to be supported.

The Quickstart app is completely open sourced with the MIT License. It is there for you to reduce the time it takes to build your own app. We are actively adding more open sourced apps built with HyperTrack that you can fork and re-purpose for your own needs.

We’re planning to release hybrid SDKs to support these apps. Please cast your vote on our feature request board to help us prioritize effectively.

Live location tracking is a background process that uses sensor signals. Therefore, consuming the energy of the phone. However, we are constantly improving the energy efficiency of our SDKs. Current tests show that we drain less than Uber’s rider app kept in the pocket (without screen time). The caveat with most tests like that is that phones, user behaviors, and tracking environments differ significantly.

In tens of MBs per month on the device that is generating; lower single digit MBs per month on the device that is consuming.

Yes, you can configure webhooks to stream all movement, activity, and trip markers to your server in real-time.

You can access and query your data up to 30 days into the past. In case you need more, we suggest to collect daily data exports we can provide you through the export feature.

The HyperTrack service runs as a separate component and it is still running when the app that started it is terminated.

Yes, HyperTrack currently provides an Android Views module to subscribe to device and trip notifications programatically. You can use the module to render your own mapping view with the mapping solution of your choice.