Visits Geofencing

Last updated 18 days ago

API to fetch activity segments, visits, trips and checkins for a device between two timestamps

Note

  1. Gives activity segments by default; use parameters to get other data

  2. If the from_timestamp / to_timestamp lies between an activity, trip or visit segment, that segment is included in the output

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

  4. Historical data beyond 7 days is not available

HTTP Request

GET https://api.hypertrack.com/v1/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

activity_segments

Boolean

Set it to true if you want activity_segments, false otherwise

Optional; defaults to TRUE

visits

Boolean

Set it to true if you want visits, false otherwise

Optional; defaults to FALSE

trips

Boolean

Set it to true if you want trips, false otherwise

Optional; defaults to FALSE

checkins

Boolean

Set it to true if you want checkins, false otherwise

Optional; defaults to FALSE

Sample Request

curl
--request GET
--url https://api.hypertrack.com/v1/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

visits

JSON

An array of visits

trips

JSON

An array of trips

checkins

JSON

An array of checkins

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

place

JSON

Sent if the activity is stop

start_place

JSON

Sent if the activity is walk, run, cycle, drive

end_place

JSON

Sent if the activity is walk, run, cycle, drive

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

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

Each visit segment will have following properties:

Property

Type

Comment

id

UUID string

Unique id of this visit

expected_visit_id

UUID string

Id of the expected_visit that created this visit

expected_visit_metadata

JSON

Metadata of the expected_visit that created this visit

place

JSON

Place where the visit happened; included name and location of the place

start_time

ISO datetime string

Start time of the visit (when the device entered the geofence)

end_time

ISO datetime string

End time of the visit (when the device exited the geofence)

distance

Integer

Distance covered within this visit

steps

Integer

Steps covered within this visit

polyline

String

Latitude and longitude encoded into a compressed string

location_time_series

String

Latitude, longitude and timestamp encoded into a compressed string

Each trip segment will have following properties:

Property

Type

Comment

id

UUID string

start_place

JSON

end_place

JSON

start_time

ISO datetime string

end_time

ISO datetime string

distance

Integer

steps

Integer

polyline

String

location_time_series

String

Each checkin will have following properties:

Property

Type

Comment

id

UUID string

recorded_at

ISO datetime string

name

String

metadata

JSON

activity

String

Activity of the device when checkin event was sent. Could be: stop, walk, run, cycle, driveor no_data if the activity is unknown

location

JSON

no_data_reason

String

Reason why the activity and/or location is unknown when the checkin event was sent. 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

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",
"place":{
"type": "point",
"coordinates": [
-122.3985203814826,
37.7869638230917
]
},
"start_time":"2018-10-20T08:00:00.000000+00:00",
"end_time":"2018-10-20T08:05:22.757000+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":"drive",
"start_place":{
"type": "point",
"coordinates": [
-122.3985203814826,
37.7869638230917
]
},
"end_place":{
"type": "point",
"coordinates": [
-121.2937327336,
36.6437640917
]
},
"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"
}
},
"visits":{
{
"id":"6b051a62-2ff8-4620-b4f6-27ce031c5915",
"expected_visit_id":"6bx37475-45d5-d5fe-d76d-27ce031c4634",
"expected_visit_metadata":{
...
},
"place":{
"type": "point",
"coordinates": [
-122.3985203814826,
37.7869638230917
]
},
"start_time":"2018-10-20T08:00:00.000000+00:00",
"end_time":"2018-10-20T08:05:22.757000+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?_"
},
...
},
"trips":{
{
"id":"6b051a62-2ff8-4620-b4f6-27ce031c5915",
"expected_visit_id":"6bx37475-45d5-d5fe-d76d-27ce031c4634",
"expected_visit_metadata":{
...
},
"start_place":{
"type": "point",
"coordinates": [
-122.3985203814826,
37.7869638230917
]
},
"end_place":{
"type": "point",
"coordinates": [
-121.2937327336,
36.6437640917
]
},
"start_time":"2018-10-20T08:00:00.000000+00:00",
"end_time":"2018-10-20T08:05:22.757000+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?_"
},
...
},
"checkins":{
{
"id": "5e07df7e-cf01-4571-b516-e76e366efb90",
"recorded_at": "2018-07-20T04:09:33.945000+00:00",
"name": "payment",
"metadata": {
"order_id" : 505054,
"customer_name" : "Alex"
},
"activity": "walk",
"location": {
"coordinates": [
77.6342144,
12.929061
],
"type": "point"
}
},
...
}
}