vehicleScores API Endpoint v2
The vehicleScores v2 API returns information on each driver associated with a particular vehicle, including driver behavior, distracted driving events, and so on.
Vehicle Scores API
GET https://api.zendrive.com/v2/vehicle/{vehicle_id}/score -H
Query Parameters
start_date
string
Look up vehicle score in this date range. See Date Range for description.
end_date
string
Look up vehicle score in this date range. See Date Range for description.
Headers
Authorization*
String
API KEY <APIKEY>
{
"info": {
"trip_count": 4,
"device_info": [],
"distance_km": 35.389,
"duration_seconds": 9468.40,
},
"driving_behavior": {
"score": {
"vehicle_score": 79,
"drivers": {
"driver_id_1" : 65,
"driver_id_2" : 87
}
}
},
"daily_driving_behavior": [{
"date": "2017-09-12",
"score": {
"vehicle_score": 79,
"drivers": {
"driver_id_1" : 65,
"driver_id_2" : 87
}
}
}],
"end_date": "2017-09-06",
"start_date": "2017-09-01"
}The fields Query Parameter
fields Query ParameterThese fields can be queried and returned in the response. If you don't specify particular fields, all of them will be returned.
info: Returns information about vehicle (Total kilometres driven, Drive time etc.)driving_behavior: Returns driver score and event ratings calculated over the interval specified.daily_driving_behavior: Returns driver score and event ratings calculated for each day during the interval specified.
Response Fields
This section contains documentation on all the response fields. Fields are in alphabetical order.
date Fields
date Fieldsend_date
End date for driver score returned in response. Same as request parameter if specified, else the start date considered by the API by default.
start_date
Starting date for driver score returned in response. Same as request parameter if specified, else the start date considered by the API by default.
info Fields
info Fieldsinfo.trip_count
The total number of trips taken during the specified date range.
info.duration_seconds
The total drive time in seconds during the specified date range.
info.distance_km
The total distance traveled in kilometers during the specified date range.
info.night_driving
The total distance traveled during the nights within the specified date range, in kilometers.
info.highway_distance
The total distance traveled on highways within the specified date range, in kilometers.
info.night_driving_fraction
The portion of night between 12:00 AM to 4:00 AM local time during which the user was driving (value lies within 0 & 1).
info.highway_ratio
Indicates the ratio of the kilometers driven on highways to non-highway driving (value lies within 0 & 1).
info.first_trip_date
The date of the first trip recorded for the vehicle being driven.
info.last_trip_date
The date of the last trip recorded for the vehicle being driven.
info.attributes
Additional attributes of the vehicle (if provided during setup), which are provided in the form of a JSON string. The value is NA is no additional attribute was provided during setup
info.night_driving_duration
The total duration traveled during the nights within the specified date range, in seconds.
driving_behavior Fields
driving_behavior Fieldsdriving_behavior
Returns driver score and event ratings calculated over the interval specified.
driving_behavior.score
A collection of scores for the vehicle and its drivers.
driving_behavior.score.
vehicle_score
Average score of this vehicle at the end of the given date range.
driving_behavior.score.
drivers
A list of all drivers with assigned IDs for this vehicle.
driving_behavior.score.
drivers.driver_id_x
Average Zendrive score of all vehicles not denoted with a vehicle ID.
driving_behavior.event_rating
A collection of various events for the driver during the interval specified. Note that each event here is an average of daily event ratings for the driver over the given interval.
driving_behavior.event_rating_hard_brake_rating
Average hard brake rating of the driver at the end of the given date range. Numerical value; for example 5.
driving_behavior.event_rating_hard_turn_rating
Average hard turn rating of the user at the end of the given date range. Numerical value; for example 4.
driving_behavior.event_rating_rapid_acceleration_rating
Average rapid acceleration rating of the driver at the end of the given date range. Numerical value; for example 5.
driving_behavior.event_rating_phone_use_rating
Average phone use rating of the driver at the end of the given date range. Numerical value; for example 6.
driving_behavior.event_rating_overspeeding_rating
The number of times the driver drove too fast. Numerical value; for example 2.
driving_behavior.event_score_vehicle
The overall zendrive_score assigned to the vehicle; for example, 84.
driving_behavior.event_score_drivers
The overall event score assigned to drivers depending on their driving behavior, in the following format:
D1_endrive_score: 82
full_name: D1 nameD2": {
D2_zendrive_score: 86,
full_name: D2 name
driving_behavior.event_coun.pu
The amount of time in seconds for which the driver used their phone while driving the vehicle. The value is numerical; for example, 14.
driving_behavior.event_count.ra
The number of times the driver accelerated rapidly while driving the vehicle. The value is numerical; for example, 1.
driving_behavior.event_count.hb
The number of times the driver did hard braking while driving the vehicle. The value is numerical; for example, 6.
driving_behavior.event_count.ht
The number of times the driver took a hard turn while driving the vehicle. The value is numerical; for example 2.
driving_behavior.event_count.os
The number of times the driver exceeded the speed limits while driving the vehicle. The value is numerical; for example 2.
driving_behavior.event_duration_seconds.pu
The total duration, in seconds, for which the driver was on the phone while driving the vehicle. The value is represented in seconds, for example, 158.259.
driving_behavior.event_duration_seconds.ra
The total duration, in seconds, for which the driver was rapidly accelerating the vehicle.The value is represented in seconds, for example, 0.0.
driving_behavior.event_duration_seconds.hb
The total duration, in seconds, for which the driver was hard braking while driving the vehicle. The value is represented in seconds, for example, 158.259.
driving_behavior.event_duration_seconds.ht
The total duration, in seconds, for which the driver was applying hard brake while driving the vehicle. The value is represented in seconds, for example, 0.0.
driving_behavior.event_duration_seconds.os
The total duration, in seconds, for which the driver was over-speeding. The value is represented in seconds, for example, 745.147.
daily_driving_behavior Fields
daily_driving_behavior Fieldsdaily_driving_behavior.date
Date for which scores are provided for the given date. Date format is YYYY-MM-DD.
daily_driving_behavior.event_rating
The rating assigned to each driving behavior for a specific user on a given day, as follows:
hard_brake_rating: 4
hard_turn_rating: 2
rapid_acceleration_rating: 4
phone_use_rating: 2
overspeeding_rating: 3
daily_driving_behavior[i].score.vehicle_score
Zendrive_score: 84
The score assigned to each driver who has driven the vehicle on a given day.
About Driver and Vehicle Scores
The vehicleScores API was created to support our Vehicle Tagging functionality, and compliment our driverScores API.
Driver scores represent performance and safety information for specific drivers across all their trips in any vehicles they may use. If you do not use our vehicle tagging features, the driver score API is still useful to look up and analyze individual driver performance.
Vehicle scores are only usable if users have tagged their vehicles using their car bluetooth stereos, enabling the SDK to recognize when a vehicle is being used.
In such a scenario, you can use the Vehicle Scores API to identify and analyze the overall performance and safety scores for a vehicle, and also for each driver of that vehicle.
Response Body
{
"driving_behavior": {
"event_rating": {
"hard_break_rating": 3,
"hard_turn_rating": 5,
"rapid_acceleration_rating": 5,
"phone_use_rating": 5,
"overspeeding_rating": 5
},
"score": {
"vehicle": {
"zendrive_score": 78
},
"drivers": {
"[email protected]": {
"zendrive_score": 78,
"full_name": null
}
}
},
"event_count": {
"pu": 0,
"ra": 0,
"hb": 6,
"ht": 0,
"os": 0
},
"event_duration_seconds": {
"pu": 0.0,
"ra": 0.0,
"hb": 0.0,
"ht": 0.0,
"os": 0.0
}
},
"daily_driving_behavior": [
{
"date": "2023-07-28",
"event_rating": {
"hard_break_rating": 3,
"hard_turn_rating": 5,
"rapid_acceleration_rating": 5,
"phone_use_rating": 5,
"overspeeding_rating": 5
},
"score": {
"vehicle_score": {
"zendrive_score": 78
}
}
}
],
"info": {
"trip_count": 5,
"duration_seconds": 1253.3190000000002,
"distance_km": 5.953,
"night_driving_duration": 0.0,
"highway_distance": 0.0,
"night_driving_fraction": 0.0,
"highway_ratio": 0.0,
"first_trip_date": "2022-07-01",
"last_trip_date": "2023-10-09",
"attributes": {
"model": "A4",
"make": "Audi",
"model_year": "2020",
"color": "white",
"vin": "vin1",
"nickname": "MyAudi",
"pairing": "bluetooth"
}
},
"start_date": "2023-07-28",
"end_date": "2023-08-04"
}Was this helpful?