heartbeatAggregates API Endpoint
The heartbeatAggregates API obtains the heartbeat data from user devices, including metrics pertaining to healthy and unhealthy heartbeats.
API Details
Heartbeat Aggregates
GET https://api.zendrive.com/v5/heartbeat_aggregates -H
Request device health data for a user within a defined time period.
Query Parameters
user_id*
string
The unique identifier of the user.
start_date*
string
The first date for which data is requested.
interval_type*
string
Choose from day, week, or month.
Headers
Authorization*
String
API KEY <APIKEY>
{
"aggregates": [
{
"date": "2023-07-17",
"day_level_aggregates": {
"healthy_time": 11370,
"healthy_intervals": [
{
"start_time": 1689552000000,
"end_time": 1689562155822
},
{
"start_time": 1689637184382,
"end_time": 1689638400000
}
],
"unhealthy_time": 0,
"unhealthy_intervals": [],
"unknown_time": 75030,
"device_model": "iPhone 12",
"platform_string": "iOS",
"overall_color_code": "G",
"setup_color_code": "G",
"location_permissions_color_code": "G",
"location_service_color_code": "G",
"activity_permissions_color_code": "G",
"background_restrictions_color_code": "G",
"precise_location_color_code": "G",
"battery_optimization_color_code": null
}
},
{
"date": "2023-07-18",
"day_level_aggregates": {
"healthy_time": 42697,
"healthy_intervals": [
{
"start_time": 1689638400000,
"end_time": 1689658784382
},
{
"start_time": 1689684855202,
"end_time": 1689706455202
},
{
"start_time": 1689724086481,
"end_time": 1689724800000
}
],
"unhealthy_time": 0,
"unhealthy_intervals": [],
"unknown_time": 43703,
"device_model": "iPhone 12",
"platform_string": "iOS",
"overall_color_code": "G",
"setup_color_code": "G",
"location_permissions_color_code": "G",
"location_service_color_code": "G",
"activity_permissions_color_code": "G",
"background_restrictions_color_code": "G",
"precise_location_color_code": "G",
"battery_optimization_color_code": null
}
},
{
"date": "2023-07-19",
"day_level_aggregates": {
"healthy_time": 58359,
"healthy_intervals": [
{
"start_time": 1689724800000,
"end_time": 1689745686481
},
{
"start_time": 1689773726530,
"end_time": 1689811200000
}
],
"unhealthy_time": 0,
"unhealthy_intervals": [],
"unknown_time": 28041,
"device_model": "iPhone 12",
"platform_string": "iOS",
"overall_color_code": "G",
"setup_color_code": "G",
"location_permissions_color_code": "G",
"location_service_color_code": "G",
"activity_permissions_color_code": "G",
"background_restrictions_color_code": "G",
"precise_location_color_code": "G",
"battery_optimization_color_code": null
}
}
],
"trip_count": [
{
"start_date": "2023-07-17",
"trip_count": 0
},
{
"start_date": "2023-07-18",
"trip_count": 1
},
{
"start_date": "2023-07-19",
"trip_count": 0
},
{
"start_date": "2023-07-20",
"trip_count": 0
},
{
"start_date": "2023-07-21",
"trip_count": 0
}
],
"start_date": "2023-07-17",
"end_date": "2023-07-21"
}Sample Curl Script
curl --location --request GET 'https://api.zendrive.com/v5/heartbeat_aggregates?start_date=2023-01-24&interval_type=day&user_id=<user_id>' \
--header 'Authorization: APIKEY <api-key>' \
--header 'Content-Type: application/json'Request Parameters
user_id
The unique identifier of the user whose device health data is requested.
start_date
The start date for which data is requested. Date format is YYYY-MM-DD. Time Zone is in UTC.
Based on the interval_type, you may receive data for the interval associated with the given start date, including data for preceding days.
interval_type
Choose from day, week, or month.
Monthly data is available for the previous 6 months.
Weekly data is available for the previous 12 weeks.
Daily data is available for the previous 30 days.
Note: A week comprises 7 days, from Monday to Sunday.
Response Parameters
This section contains documentation on all the response fields.
aggregates.date
Each date within the requested interval.
aggregates.day_level_aggregates
Various values for the corresponding aggregates.date. See the Day Level Aggregates Fields table below.
start_date
Start date of the dataset for the requested period.
end_date
End date of the dataset for the requested period.
trip_count
This value indicates the number of trips taken by the user for each day within the requested period. The trip count includes the count for all trip types; for example, where the driver is driving, where the driver is a passenger, or is riding a motorcycle, using public transit and so on.
Day Level Aggregates Fields
healthy_time
The duration in seconds during which all of the user's known devices are healthy.
healthy_intervals
Periods during which the health of the user's devices is good.
healthy_intervals.start_time
Unix timestamps for start of healthy intervals.
healthy_intervals.end_time
Unix timestamps for end of healthy intervals.
unhealthy_time
The duration in seconds during which at least 1 of the user's known devices is unhealthy.
unhealthy_intervals
Periods during which the health of the user devices is poor.
unhealthy_intervals.start_time
Unix timestamps for start of unhealthy intervals.
unhealthy_intervals.end_time
Unix timestamps for end of unhealthy intervals.
unknown_time
Time in seconds for which the health of the user's devices is unknown.
device_model
Make of the user's device.
platform_string
OS of the user's device (iOS or Android).
overall_color_code
This value indicates whether the device is healthy. Possible values are as follows:
G: Green for a healthy value.
O: Orange for a partially healthy value.
R: Red for an unhealthy value.
setup_color_code
This value indicates whether zendrive.setup was called successfully. Possible values: G, O, R.
location_permissions_color_code
This value indicates whether the
Location Permission is enabled on the device. Possible values: G, O, R.
precise_location_color_code
This value indicates whether the Precise Location permission is enabled on the device. Possible values: G, O, R.
Note: Healthy and unhealthy intervals and unknown times are calculated on the basis of the overall heartbeat state. Change in these values will occur only in cases where the Precise Location permission is enabled, for Android v12 and above, and iOS v14 and above.
location_service_color_code
This value indicates whether the GPS data was available on the device. Possible values: G, O, R.
activity_permissions_color_code
This value indicates whether the Physical Activity permission is enabled on the device. Possible values: G, O, R.
background_restriction_color_code
This value indicates whether the Background Restriction permission is disabled on the device. Possible values: G, O, R.
battery_optimization_color_code
This value indicates whether the Battery Optimization permission is disabled on the device. Ideally this permission should be disabled (G). Possible values: G, O, R.
The value will be NULL on Android devices where the Zendrive SDK version is below 9.2, and on iOS devices irrespective of their SDK versions.
Sample Response
{
"aggregates": [
{
"date": "2023-07-17",
"day_level_aggregates": {
"healthy_time": 11370,
"healthy_intervals": [
{
"start_time": 1689552000000,
"end_time": 1689562155822
},
{
"start_time": 1689637184382,
"end_time": 1689638400000
}
],
"unhealthy_time": 0,
"unhealthy_intervals": [],
"unknown_time": 75030,
"device_model": "iPhone 12",
"platform_string": "iOS",
"overall_color_code": "G",
"setup_color_code": "G",
"location_permissions_color_code": "G",
"location_service_color_code": "G",
"activity_permissions_color_code": "G",
"background_restrictions_color_code": "G",
"precise_location_color_code": "G",
"battery_optimization_color_code": null
}
},
{
"date": "2023-07-18",
"day_level_aggregates": {
"healthy_time": 42697,
"healthy_intervals": [
{
"start_time": 1689638400000,
"end_time": 1689658784382
},
{
"start_time": 1689684855202,
"end_time": 1689706455202
},
{
"start_time": 1689724086481,
"end_time": 1689724800000
}
],
"unhealthy_time": 0,
"unhealthy_intervals": [],
"unknown_time": 43703,
"device_model": "iPhone 12",
"platform_string": "iOS",
"overall_color_code": "G",
"setup_color_code": "G",
"location_permissions_color_code": "G",
"location_service_color_code": "G",
"activity_permissions_color_code": "G",
"background_restrictions_color_code": "G",
"precise_location_color_code": "G",
"battery_optimization_color_code": null
}
},
{
"date": "2023-07-19",
"day_level_aggregates": {
"healthy_time": 58359,
"healthy_intervals": [
{
"start_time": 1689724800000,
"end_time": 1689745686481
},
{
"start_time": 1689773726530,
"end_time": 1689811200000
}
],
"unhealthy_time": 0,
"unhealthy_intervals": [],
"unknown_time": 28041,
"device_model": "iPhone 12",
"platform_string": "iOS",
"overall_color_code": "G",
"setup_color_code": "G",
"location_permissions_color_code": "G",
"location_service_color_code": "G",
"activity_permissions_color_code": "G",
"background_restrictions_color_code": "G",
"precise_location_color_code": "G",
"battery_optimization_color_code": null
}
}
],
"trip_count": [
{
"start_date": "2023-07-17",
"trip_count": 0
},
{
"start_date": "2023-07-18",
"trip_count": 1
},
{
"start_date": "2023-07-19",
"trip_count": 0
},
{
"start_date": "2023-07-20",
"trip_count": 0
},
{
"start_date": "2023-07-21",
"trip_count": 0
}
],
"start_date": "2023-07-17",
"end_date": "2023-07-21"
}Was this helpful?