aggregateScores API Endpoint

The aggregateScores API allows Zendrive customers to look up the Zendrive score for their drivers.

Refer to Zendrive Server APIs for an understanding of how Zendrive server APIs are organized.

Aggregate Scores

GET https://api.zendrive.com/v4/score -H

This API looks up the Zendrive score for your full population of drivers.

Query Parameters

Name	Type	Description
interval_type	String	Choose day, week, or month.
start_date	String	Provide a date as YYYY-MM-DD.

Headers

Name	Type	Description
Authorization*	String	API KEY <APIKEY>

200

{
    "info": {
        "duration_seconds": 131147.551,
        "distance_km": 998.535,
        "last_trip_date": "2020-12-13",
        "driver_count": 22,
        "missing_data_driver_count": 0
    },
    "driving_behavior": {
        "event_rating": {
            "hard_brake_rating": 5,
            "hard_turn_rating": 4,
            "rapid_acceleration_rating": 5,
            "phone_use_rating": 5,
            "overspeeding_rating": 5
        },
        "score": {
            "zendrive_score": 91
        }
    },
    "daily_driving_behavior": [
        {
            "event_rating": {
                "hard_brake_rating": 4,
                "hard_turn_rating": 5,
                "rapid_acceleration_rating": 5,
                "phone_use_rating": 5,
                "overspeeding_rating": 5
            },
            "score": {
                "zendrive_score": 96
            },
            "date": "2020-12-07"
        },
        {
            "event_rating": {
                "hard_brake_rating": 4,
                "hard_turn_rating": 5,
                "rapid_acceleration_rating": 4,
                "phone_use_rating": 5,
                "overspeeding_rating": 5
            },
            "score": {
                "zendrive_score": 92
            },
            "date": "2020-12-08"
        },
        {
            "event_rating": {
                "hard_brake_rating": 5,
                "hard_turn_rating": 5,
                "rapid_acceleration_rating": 5,
                "phone_use_rating": 5,
                "overspeeding_rating": 5
            },
            "score": {
                "zendrive_score": 98
            },
            "date": "2020-12-09"
        },
        {
            "event_rating": {
                "hard_brake_rating": 4,
                "hard_turn_rating": 5,
                "rapid_acceleration_rating": 4,
                "phone_use_rating": 5,
                "overspeeding_rating": 5
            },
            "score": {
                "zendrive_score": 92
            },
            "date": "2020-12-10"
        },
        {
            "event_rating": {
                "hard_brake_rating": 4,
                "hard_turn_rating": 3,
                "rapid_acceleration_rating": 4,
                "phone_use_rating": 5,
                "overspeeding_rating": 5
            },
            "score": {
                "zendrive_score": 84
            },
            "date": "2020-12-11"
        },
        {
            "event_rating": {
                "hard_brake_rating": 5,
                "hard_turn_rating": 3,
                "rapid_acceleration_rating": 5,
                "phone_use_rating": 4,
                "overspeeding_rating": 5
            },
            "score": {
                "zendrive_score": 86
            },
            "date": "2020-12-12"
        },
        {
            "event_rating": {
                "hard_brake_rating": 5,
                "hard_turn_rating": 5,
                "rapid_acceleration_rating": 5,
                "phone_use_rating": 5,
                "overspeeding_rating": 5
            },
            "score": {
                "zendrive_score": 94
            },
            "date": "2020-12-13"
        }
    ],
    "installs": [],
    "active_drivers": [
        {
            "date": "2020-12-07",
            "count": 7
        },
        {
            "date": "2020-12-08",
            "count": 6
        },
        {
            "date": "2020-12-09",
            "count": 5
        },
        {
            "date": "2020-12-10",
            "count": 8
        },
        {
            "date": "2020-12-11",
            "count": 7
        },
        {
            "date": "2020-12-12",
            "count": 8
        },
        {
            "date": "2020-12-13",
            "count": 15
        }
    ],
    "start_date": "2020-12-07",
    "end_date": "2020-12-13"
}

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

• (Mandatory) Date Range fields (start_date and interval_type)

• Pagination fields (limit and cursor_id)

• Sorting fields (order_by and order_type).

Request Parameters

Request Parameter	Description
fields	Comma separated list of fields to lookup. If nothing is specified, the following are returned. info : Returns aggregate information about drivers (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. installs: Returns the number of users per day who installed the app active_drivers: Returns the number of users per day who recorded at least 1 trip on the day.
group_id	The aggregate score is computed based on data from the specified group_id within the driver population.

Response Parameters

This section contains documentation on all the response fields. Fields are in alphabetical order.

Date and Pagination Fields

Response Field	Description
start_date	Start date of the request.
end_date	End date of the request.
next_cursor_id	ID for the next page of results.

info Fields

Response fields with info.*	Description
info.distance_km	Total distance in km logged by all drivers in the driver population or group.
info.duration_seconds	Total drive time over all drivers in the driver population or group represented in seconds
info.driver_count	Number of drivers in dataset or group active during the given date range.
info.last_trip_date	Date since the last recorded trip.
info.missing_data_driver_count	Number of drivers missing one or more data types (usually missing Gyroscope).
info.highway_ratio	Indicates the ratio of the kilometers driven on highways to non-highway driving (value lies within 0 & 1).
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.trip_count	The total number of trips taken during the specified date range.
info.breached_trip_count	The total number of trips that have breached the operating geofence.

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 across all drivers in the dataset in the given date range.
driving_behavior.event_rating. hard_turn_rating	Average hard turn rating across all drivers in the dataset in the given date range.
driving_behavior.event_rating. overspeeding_rating	Average overspeeding rating across all drivers in the dataset in the given date range.
driving_behavior.event_rating. phone_use_rating	Average phone use rating across all drivers in the dataset in the given date range
driving_behavior.event_rating. rapid_acceleration_rating	Average acceleration rating across all drivers in the dataset in the given date range.
driving_behavior.score. zendrive_score	Average Zendrive score across all drivers in the dataset in the given date range.

daily_driving_behavior[i] Fields

Response field with daily_driving_behavior[i].*	Description
daily_driving_behavior[i]	Scores and Event Ratings for each day in the date range requested.
daily_driving_behavior[i].date	Date for which scores are provided in this tuple. Date format is YYYY-MM-DD.
daily_driving_behavior[i].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.
daily_driving_behavior[i]. event_rating.hard_brake_rating	Average hard brake rating across all drivers in the dataset on this particular date.
daily_driving_behavior[i]. event_rating.hard_turn_rating	Average hard turn rating across all drivers in the dataset on this particular date.
daily_driving_behavior[i]. event_rating.overspeeding_rating	Average overspeeding rating across all drivers in the dataset on this particular date.
daily_driving_behavior[i]. event_rating.phone_use_rating	Average phone use rating across all drivers in the dataset on this particular date.
daily_driving_behavior[i]. event_rating.rapid_acceleration_rating	Average rapid acceleration rating across all drivers in the dataset on this particular date.
daily_driving_behavior[i].score	A collection of various scores for the driver during the interval specified. Note that each score here is an average of daily scores for the driver over the given interval.
daily_driving_behavior[i].score. zendrive_score	Average Zendrive score across all drivers in the dataset on this particular date.

installs and active_drivers Fields

Response Field	Description
installs.date	Each date in the requested range.
installs.count	The count of people who installed the app on the corresponding installs.date.
active_drivers.date	Each date in the requested range.
active_drivers.count	The count of drivers who recorded at least 1 trip on the corresponding active_drivers.date.

Response Body

{
    "info": {
        "duration_seconds": 43353.933999999994,
        "distance_km": 479.957,
        "highway_ratio": 0.38484697587492217,
        "night_driving_fraction": 0,
        "last_trip_date": "2023-09-10",
        "driver_count": 13,
        "missing_data_driver_count": 0,
        "trip_count": 38,
        "breached_trip_count": 0
    },
    "driving_behavior": {
        "event_rating": {
            "hard_brake_rating": 4,
            "hard_turn_rating": 4,
            "rapid_acceleration_rating": 5,
            "phone_use_rating": 5,
            "overspeeding_rating": 1
        },
        "score": {
            "zendrive_score": 93
        }
    },
    "daily_driving_behavior": [
        {
            "event_rating": {
                "hard_brake_rating": 4,
                "hard_turn_rating": 4,
                "rapid_acceleration_rating": 5,
                "phone_use_rating": 5,
                "overspeeding_rating": 1
            },
            "score": {
                "zendrive_score": 93
            },
            "date": "2023-09-10"
        }
    ],
    "installs": [
        {
            "date": "2023-09-10",
            "count": 5
        }
    ],
    "active_drivers": [
        {
            "date": "2023-09-10",
            "count": 17,
            "count_7_days": 55,
            "count_30_days": 88
        }
    ],
    "start_date": "2023-09-10",
    "end_date": "2023-09-10"
}