driverScores API Endpoint

Zendrive assigns scores to drivers based on their driving performance. High scores are assigned to drivers who complete their trips successfully with nil or negligible events such as hard braking, sudden acceleration, phone use, and so on.

About Driver and Vehicle Scores

The driverScores API existed prior to the development of our Vehicle Tagging functionality and may be used with or without it.

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.

If you do take advantage of vehicle tagging, the driverScores API can be used to identify and analyze a driver's overall performance along with their performance for particular identified vehicles. You also receive a separate "unknown vehicle score" which identifies the driver's average score for all untagged vehicles they may drive.

Refer to Zendrive Server APIs to understand how Zendrive server APIs are organized.

API Detail

Driver Scores API

GET https://api.zendrive.com/v1/driver/<user_id>/score-H

Look up the Zendrive score for a specified driver.

Query Parameters

Name

Type

Description

fields

string

Comma separated list of fields to lookup. See below.

start_date

string

Look up driver score in this date range. See Date Range for description

end_date

string

Look up driver score in this date range. See Date Range for description

Headers

Name

Type

Description

Authorization*

String

API KEY <APIKEY>

{
    "driving_behavior": {
        "event_rating": {
            "hard_brake_rating": 4,
            "hard_turn_rating": 5,
            "rapid_acceleration_rating": 5,
            "phone_use_rating": 4,
            "overspeeding_rating": 4
        },
        "score": {
            "zendrive_score": 85,
            "vehicles": {
                "Skoda_Octavia_7577_6f9": 0.7790721083241204
            }
        },
        "event_count": {
            "phone_use": 29,
            "rapid_acceleration": 1,
            "hard_brake": 15,
            "hard_turn": 4,
            "overspeeding": 2
        },
        "event_duration_seconds": {
            "phone_use": 659.914,
            "overspeeding": 160.976
        }
    },
    "daily_driving_behavior": [
        {
            "event_rating": {
                "hard_brake_rating": 4,
                "hard_turn_rating": 5,
                "rapid_acceleration_rating": 5,
                "phone_use_rating": 4,
                "overspeeding_rating": 4
            },
            "score": {
                "zendrive_score": 84,
                "vehicles": {
                    "Skoda_Octavia_7577_6f9": 0.7790721083241204
                }
            },
            "date": "2023-07-28"
        },
        {
            "event_rating": {
                "hard_brake_rating": 5,
                "hard_turn_rating": 5,
                "rapid_acceleration_rating": 5,
                "phone_use_rating": 3,
                "overspeeding_rating": 5
            },
            "score": {
                "zendrive_score": 89
            },
            "date": "2023-07-30"
        },
        {
            "event_rating": {
                "hard_brake_rating": 2,
                "hard_turn_rating": 5,
                "rapid_acceleration_rating": 5,
                "phone_use_rating": 2,
                "overspeeding_rating": 5
            },
            "score": {
                "zendrive_score": 64
            },
            "date": "2023-07-31"
        },
        {
            "event_rating": {
                "hard_brake_rating": 3,
                "hard_turn_rating": 5,
                "rapid_acceleration_rating": 5,
                "phone_use_rating": 2,
                "overspeeding_rating": 5
            },
            "score": {
                "zendrive_score": 73
            },
            "date": "2023-08-01"
        },
        {
            "event_rating": {
                "hard_brake_rating": 4,
                "hard_turn_rating": 4,
                "rapid_acceleration_rating": 5,
                "phone_use_rating": 3,
                "overspeeding_rating": 5
            },
            "score": {
                "zendrive_score": 83
            },
            "date": "2023-08-02"
        },
        {
            "event_rating": {
                "hard_brake_rating": 5,
                "hard_turn_rating": 5,
                "rapid_acceleration_rating": 5,
                "phone_use_rating": 3,
                "overspeeding_rating": 5
            },
            "score": {
                "zendrive_score": 91
            },
            "date": "2023-08-03"
        },
        {
            "event_rating": {
                "hard_brake_rating": 4,
                "hard_turn_rating": 5,
                "rapid_acceleration_rating": 5,
                "phone_use_rating": 4,
                "overspeeding_rating": 4
            },
            "score": {
                "zendrive_score": 88
            },
            "date": "2023-08-04"
        }
    ],
    "info": {
        "duration_seconds": 26340.798000000003,
        "distance_km": 273.753,
        "night_driving_fraction": 0.013211444846887325,
        "highway_ratio": 0.5449949406947139,
        "driver_start_date": "2017-05-10",
        "trip_count": 22,
        "attributes": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "[email protected]",
            "alias": "[email protected]",
            "VehicleType": 0,
            "ApplicationUsed": "iosUnifiedDemo"
        },
        "first_trip_date": "2020-04-01",
        "last_trip_date": "2023-10-08",
        "device_info": [
            {
                "model": "iPhone14,3",
                "version": "16.5.1",
                "missing_data": []
            }
        ],
        "bluetooth_connection_info": {
            "last_bluetooth_connection_date": "2021-10-03",
            "vehicle_id": "gladiator"
        },
        "pause_tracking_duration_seconds": 118.0,
        "shift_name": "default_shift_qa",
        "shift_id": "default_shift_qa_tipbqnlglu"
    },
    "start_date": "2023-07-28",
    "end_date": "2023-08-04"
}

This API uses Set 2 of the Date Range, Pagination, and Sorting parameters:

Date Range fields (start_date and end_date)
Pagination fields (limit and offset)
Sorting fields (order_by and order_type).

To Query Subaccount Use Case

To query subaccount, execute the following link using the subaccount_id:

https://api.zendrive.com/v1/subaccount/<subaccount_id>/driver/<user_id>/score

The `fields` Query Parameter

These 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 driver (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 fields

Description

end_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

Response fields with info.*

Description

info.attributes

Additional attributes of the driver if it was provided during setup of the Zendrive SDK. The attributes are provided as a json string. This is NA if no attributed were provided.

info.device_info

Devices that the driver has used (model name and version number). The missing_data key lists the essential sensors that is missing (like Gyroscope) in the device.

info.distance_km

Total distance in km logged by the driver during the specified date range.

info.driver_start_date

The date at which data was first logged by this driver.

info.duration_seconds

Total drive time of the driver during the specified date range represented in seconds

info.first_trip_date

The first trip taken if any trip is taken in past.

info.highway_ratio

Indicates the fraction of trips recorded on highways (value lies within 0 & 1)

info.last_trip_date

The last trip taken if any trip is taken in past.

info.night_driving_fraction

Indicates the fraction of night (12:00 AM to 4:00 AM local time) driving (value lies within 0 & 1)

info.trip_count

Total number of trips logged by the driver during the specified date range.

info.bluetooth_connection_info

Information on the vehicle connected using bluetooth.

info.pause_tracking_duration_seconds

The total duration when tracking is paused in seconds.

info.shift_name

The shift name as set by the fleet manager.

info.shift_id

The shift id as set by the fleet manager.

`driving_behavior` Fields

Response fields with driving_behavior.*

Description

driving_behavior

Returns driver score and event ratings calculated over the interval specified.

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.

driving_behavior.event_rating.

hard_turn_rating

Average hard turn rating of the user at the end of the given date range.

driving_behavior.event_rating.

overspeeding_rating

Average overspeeding rating of the driver at the end of the given date range.

driving_behavior.event_rating.

phone_use_rating

Average phone use rating of the driver at the end of the given date range.

driving_behavior.event_rating.

rapid_acceleration_rating

Average rapid acceleration rating of the driver at the end of the given date range.