listDrivers API Endpoint

The listDrivers API looks up active drivers and returns information on driving behavior, distance driven, and various other driver and trip-specific metrics considering trips of all types.

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

List Drivers

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

Lookup active drivers in one of the available data ranges. An active driver is one who has at least one recorded trip in the given date range. This endpoint also allows look up of specific drivers using the ids parameter.

Query Parameters

Name

Type

Description

start_date

String

Provide a date as YYYY-MM-DD

interval_type

String

Choose day, week, or month

Headers

Name

Type

Description

Authorization*

String

API KEY <APIKEY>

{
    "drivers": [
        {
            "driver_id": "[email protected]",
            "info": {
                "trip_count": 47,
                "duration_seconds": 119016.985,
                "distance_km": 1313.467,
                "driver_start_date": "2020-05-10",
                "attributes": null,
                "device_info": [
                    {
                        "model": "OnePlus-ONEPLUS A6010",
                        "version": "29"
                    }
                ]
            },
            "driving_behavior": {
                "event_rating": {
                    "hard_brake_rating": 4,
                    "hard_turn_rating": 5,
                    "rapid_acceleration_rating": 5,
                    "phone_use_rating": 4,
                    "overspeeding_rating": 2
                },
                "score": {
                    "zendrive_score": 86
                }
            }
        },
        {
            "driver_id": "[email protected]",
            "info": {
                "trip_count": 55,
                "duration_seconds": 101890.811,
                "distance_km": 1193.089,
                "driver_start_date": "2020-04-01",
                "attributes": {
                    "first_name": "John",
                    "last_name": "Doe",
                    "email": "[email protected]",
                    "alias": "[email protected]",
                    "ApplicationUsed": "iosUnifiedDemo"
                },
                "device_info": [
                    {
                        "model": "iPhone X GSM",
                        "version": "14.2"
                    }
                ]
            },
            "driving_behavior": {
                "event_rating": {
                    "hard_brake_rating": 5,
                    "hard_turn_rating": 5,
                    "rapid_acceleration_rating": 5,
                    "phone_use_rating": 3,
                    "overspeeding_rating": 3
                },
                "score": {
                    "zendrive_score": 85
                }
            }
        }
    ],
    "start_date": "2020-12-01",
    "end_date": "2020-12-31",
    "next_cursor_id": 34
}

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, all data is returned.

info: Returns information about driver (Total kilometers driven, Drive time etc.)
driving_behavior: Returns driver score and event ratings calculated over the interval specified.

ids

Comma separated list of driver ids for which data should be returned. Drivers inactive in the specified date range will be skipped in the response.

group_id

If specified the list of drivers returned will be restricted to drivers that belong to the specified group. If a list of driver ids is explicitly given as query parameter then group_id parameter has no impact on result set.

location

This parameter is used to filter the data for drivers belonging only to the requested location within the fleet (app_id).

Response Fields

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

Date and Sorting 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.

Driver Fields

Response Field

Description

drivers

Array of drivers.

drivers[i].driver_id

Id of the driver. This is the ID specified when initializing the Zendrive SDK in the mobile application.

`drivers[i].info` Fields

Response field

Description

drivers[i].info

Various metrics of the driver.

drivers[i].info.trip_count

Number of trips.

drivers[i].info.distance_km

Distance travelled in kilometers.

drivers[i].info.duration_seconds

Total drive time of the driver across all trips in seconds

drivers[i].info.driver_start_date

The first time we saw data from this driver.

drivers[i].info.attributes

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

drivers[i].info.device_info

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

`drivers[i].driving_behavior` Fields

Response Field

Description

drivers[i].driving_behavior

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