Ranking

The ranking service is used to retrieve the ranking of all drivers belonging to a group. This service returns the ranking of the current month and the previous month.

To be ranked, a driver must have completed at least 5 trips and travelled 20 km in a month.

The ranking of the current month is updated every 10 minutes.

The ranking of the previous month is frozen on the 1st day of the current month.

If you have your admin API key, you can try the API via this link.

Get driver's ranking

GET https://service.drivequant.com/v3/drivekit/admin/drivers/ranking

Return drivers ranking for current and previous month

Query Parameters

Name	Type	Description
type*	String	Ranking type, can be safety, eco-driving, distraction, speeding
groupLabel	String	Group of drivers whose ranking is required. If not set, you get all drivers of your team.

Headers

Name	Type	Description
DriveKit-Admin-API-Key*	String	Admin API Key

200: OK OK

{
  "type": "safety",
  "currentMonth": {
    "monthNumber": 11,
    "driverRankedNumber": 2,
    "driverRanked": [
      {
        "userId": "[email protected]",
        "firstname": "Driver-1-firstname",
        "lastname": "Driver-1-lastname",
        "pseudo": "Driver-1",
        "rank": 1,
        "score": 10,
        "distance": 12
      },
      {
        "userId": "[email protected]",
        "firstname": "Driver-2-firstname",
        "lastname": "Driver-2-lastname ",
        "pseudo": "Driver-2 ",
        "rank": 2,
        "score": 9.18,
        "distance": 67
      }
    ],
    "driverNotRanked": [
      {
        "userId": "[email protected]",
        "firstname": "Driver-3-firstname",
        "lastname": "Driver-3-lastname",
        "pseudo": "Driver-3",
        "distance": 0
      }
    ]
  },
  "previousMonth": {
    "monthNumber": 10,
    "driverRankedNumber": 8,
    "driverRanked": [
      {
        "userId": "[email protected]",
        "firstname": "Driver-1-firstname",
        "lastname": "Driver-1-lastname",
        "pseudo": "Driver-1",
        "rank": 1,
        "score": 9.76,
        "distance": 38
      },
      {
        "userId": "[email protected]",
        "firstname": "Driver-2-firstname",
        "lastname": "Driver-2-lastname ",
        "pseudo": "Driver-2 ",
        "rank": 2,
        "score": 9.01,
        "distance": 67
      },
      {
        "userId": "[email protected]",
        "firstname": "Driver-3-firstname",
        "lastname": "Driver-3-lastname",
        "pseudo": "Driver-3",
        "rank": 3,
        "score": 8.03,
        "distance": 71
      }
    ],
    "driverNotRanked": [
      {
        "userId": "[email protected]",
        "firstname": "Driver-4-firstname",
        "lastname": "Driver-4-lastname",
        "pseudo": "Driver-4",
        "distance": 0
      }
    ]
  }
}

400: Bad Request Invalid ranking type

{
  "message": "Invalid rank type",
  "code": 3,
  "messageKey": "invalid_rank_type"
}

400: Bad Request Invalid group label

{
  "message": "Invalid group label",
  "code": 4,
  "messageKey": "invalid_group_label"
}

401: Unauthorized Bad credentials

{
  "message": "Invalid API key",
  "code": 1,
  "messageKey": "dk_invalid_api_key"
}

403: Forbidden

{
  "message": "Ranking feature is disabled for your account",
  "code": 2,
  "messageKey": "ranking_feature_disabled"
}

423: Locked

{
  "message": "Ranking is not yet available, please retry later",
  "code": 5,
  "messageKey": "ranking_not_available"
}

You may not have access to all the types. Please ask your DriveQuant contact if you need more information.

Response

The table below summarizes the list of ranking data.

Field	Type	Description
currentMonth	array[object]	Drivers with their rank in the group in the current month (see MonthRanking)
previousMonth	array[object]	Drivers with their rank in the group in the previous month (see MonthRanking)
type	string	Ranking type set in the service call. Can be safety, eco-driving, distraction, speeding

MonthRanking

MonthRanking contains the list of drivers in a group with their rank.

Field	Type	Description
monthNumber	int	Month number of the ranking period (1 -> january, 2 -> february, ...)
driverRankedNumber	int	Number of ranked drivers
driverRanked	array[object]	List of ranked drivers (see UserRanked)
driverNotRanked	array[object]	List of unranked drivers (i.e. who have not driven the minimum distance and completed the minimum number of trips) (see UserNotRanked)

UserRanked

Field	Type	Description
userId	string	Driver's unique identifier
firstname	string	Driver's firstname
lastname	string	Driver's lastname
pseudo	string	Driver's pseudo
rank	int	Driver's rank
score	double	Driver's score
distance	double	Monthly driving distance (in km)
tripNumber	double	Monthly number of trips

UserNotRanked

Field	Type	Description
userId	string	Driver's unique identifier
firstname	string	Driver's firstname
lastname	string	Driver's lastname
pseudo	string	Driver's pseudo
distance	double	Monthly driving distance (in km)
tripNumber	double	Monthly number of trips