API

Last updated 11 days ago

Activity segments for a device via an API call

This product feature is still under development and is not available in production. Please reach out to us on Slack if you want an early access.

HyperTrack generates and organizes movement data of your users into activity segments. You can use the Placeline API to fetch these activity segments for a device id. You can also use the Mileage API to get distance traveled by the user, alongwith breakup by activity.

Placeline

API to fetch activity segments for a device between two timestamps

Note

  1. If the from_timestamp / to_timestamp lies between an activity, that segment is included in the output

  2. Maximum allowed time range is of one day; queries that exceed that will given an error

  3. Historical data beyond 7 days is not available

HTTP Request

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

Parameters

Parameter

Type

Description

Required

device_id

UUID string

ID of the device

Required

from_timestamp

ISO datetime string

Time from which you want the data

Required

to_timestamp

ISO datetime string

Time to which you want the data

Optional; defaults to current time

Sample Request

curl
--request GET
--url https://api.hypertrack.com/v3/placeline/
--header 'Authorization: token SECRET_KEY'
--header 'Content-Type: application/json'
--data '{
"device_id": "5d728988-9c23-4bd7-bfc3-048918199d53",
"from_timestamp": "2018-10-20T08:00Z",
"to_timestamp": "2018-10-20T09:00Z"
}

Returns

Property

Type

Comment

device_id

UUID string

Device ID sent in the request

from_timestamp

ISO datetime string

From timestamp sent in the request

to_timestamp

ISO datetime string

To timestamp sent in the request

activity_segments

JSON

An array of activity segments

Each activity segment will have following properties:

Property

Type

Comment

id

UUID string

Unique id of this activity segment

activity

String

Could be: stop, walk, run, cycle, driveor no_data if the activity is unknown

start_place

JSON

Place where the activity started

end_place

JSON

Place where the activity ended. Note that the start_place and end_place for stop will be the same

start_time

ISO datetime string

Start time of this activity

end_time

ISO datetime string

End time of this activity

distance

Integer

Distance, in meters, covered during this activity

steps (coming soon)

Integer

Number of steps covered during this activity; sent if the activity is walk or run

polyline

String

Latitude and longitude encoded into a compressed string

location_time_series

String

Latitude, longitude and timestamp encoded into a compressed string

no_data_reason

String

Reason why the activity is unknown. Could be one of the following:

  1. tracking_paused

  2. sdk_killed

  3. gps_lost

  4. location_disabled

  5. location_permission_denied

  6. activity_permission_denied

  7. airplane_mode_on

  8. device_switched_off

  9. unknown

Sample Response

{
"device_id": "5d728988-9c23-4bd7-bfc3-048918199d53",
"from_timestamp": "2018-10-20T08:00Z",
"to_timestamp": "2018-10-20T09:00Z",
"activity_segments":{
{
"id":"6b051a62-2ff8-4620-b4f6-27ce031c5915",
"activity":"stop",
"start_place":{
"location": {
"coordinates": [
-121.2937327336,
36.6437640917
],
"type": "Point"
},
"name": "WeWork Mission St",
"type": "office"
},
"end_place":{
"location": {
"coordinates": [
-121.2937327336,
36.6437640917
],
"type": "Point"
},
"name": "WeWork Mission St",
"type": "office"
},
"start_time":"2018-10-20T08:00:00.000000+00:00",
"end_time":"2018-10-20T08:05:22.757000+00:00",
"distance":0,
"steps":0,
"polyline":"",
"location_time_series":""
},
{
"id":"6b051a62-2ff8-4620-b4f6-27ce031c5915",
"activity":"drive",
"start_place":{
"id": "2b0bab1f-2892-46ce-846a-528949d10431",
"location": {
"coordinates": [
-121.2937327336,
36.6437640917
],
"type": "Point"
},
"name": "WeWork Mission St",
"type": "office"
},
"end_place":{
"id": "2bbeydgedef-2892-46ce-846a-528949d10431",
"location": {
"coordinates": [
-122.294347336,
36.64334440324
],
"type": "Point"
},
"name": "Dropbox HQ",
"type": "office"
},
"start_time":"2018-10-20T08:05:22.757000+00:00",
"end_time":"2018-10-20T08:25:23.363000+00:00",
"distance":123.94139207233032,
"steps":0,
"polyline":"yvucN}|blDR?`AJ?HH??HaABy@?E?",
"location_time_series":"yvucN}|blD_ezks{vuwGR?_cidP`AJ_qo]?H_kv|PH?_"
},
{
"id":"6b051a62-2ff8-4620-b4f6-27ce031c5915",
"activity":"no_data",
"no_data_reason":"location_disabled",
"start_time":"2018-10-20T08:25:23.363000+00:00",
"end_time":"2018-10-20T08:34:18.475000+00:00"
}
}
}

Mileage

API to fetch mileage for a device between two timestamps

Note

  1. Maximum allowed time range is of one day; queries that exceed that will given an error

  2. Historical data beyond 7 days is not available

HTTP Request

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

Parameters

Parameter

Type

Description

Required

device_id

UUID string

ID of the device

Required

from_timestamp

ISO datetime string

Time from which you want the data

Required

to_timestamp

ISO datetime string

Time to which you want the data

Optional; defaults to current time

Sample Request

curl
--request GET
--url https://api.hypertrack.com/v3/mileage/
--header 'Authorization: token SECRET_KEY'
--header 'Content-Type: application/json'
--data '{
"device_id": "5d728988-9c23-4bd7-bfc3-048918199d53",
"from_timestamp": "2018-10-20T08:00Z",
"to_timestamp": "2018-10-20T09:00Z"
}

Returns

Property

Type

Comment

device_id

UUID string

Device ID sent in the request

from_timestamp

ISO datetime string

From timestamp sent in the request

to_timestamp

ISO datetime string

To timestamp sent in the request

total_distance

Integer

Distance traveled, in meters

total_duration

Integer

Duration traveled, in seconds

Sample Response

{
"device_id": "5d728988-9c23-4bd7-bfc3-048918199d53",
"from_timestamp": "2018-10-20T08:00Z",
"to_timestamp": "2018-10-20T09:00Z",
"total_distance": 12600,
"total_duration": 3600
}