# 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.

{% hint style="info" %}
If you have your **admin API key**, you can try the API via this [**link**](https://drivequant.stoplight.io/docs/drivequant-public/b3A6Mjg1Mjc4MjM-get-driver-s-ranking).
{% endhint %}

## Get driver's ranking

<mark style="color:blue;">`GET`</mark> `https://service.drivequant.com/v3/drivekit/admin/drivers/ranking`

Return drivers ranking for current and previous month

#### Query Parameters

| Name                                   | Type   | Description                                                                               |
| -------------------------------------- | ------ | ----------------------------------------------------------------------------------------- |
| type<mark style="color:red;">\*</mark> | 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<mark style="color:red;">\*</mark> | String | Admin API Key |

{% tabs %}
{% tab title="200: OK OK" %}

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

{% endtab %}

{% tab title="400: Bad Request Invalid ranking type" %}

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

{% endtab %}

{% tab title="400: Bad Request Invalid group label" %}

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

{% endtab %}

{% tab title="401: Unauthorized Bad credentials" %}

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

{% endtab %}

{% tab title="403: Forbidden " %}

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

{% endtab %}

{% tab title="423: Locked " %}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
You may not have access to all the types. Please ask your DriveQuant contact if you need more information.
{% endhint %}

## Response

The table below summarizes the list of ranking data.

<table><thead><tr><th width="164.7088607594937">Field</th><th width="248.19777842288806">Type</th><th>Description</th></tr></thead><tbody><tr><td>currentMonth</td><td><code>array[object]</code></td><td>Drivers with their rank in the group in the current month <em>(see</em> <a href="#monthranking"><em>MonthRanking</em></a><em>)</em></td></tr><tr><td>previousMonth</td><td><code>array[object]</code></td><td>Drivers with their rank in the group in the previous month <em>(see</em> <a href="#monthranking"><em>MonthRanking</em></a><em>)</em></td></tr><tr><td>type</td><td><code>string</code></td><td>Ranking type set in the service call. Can be safety, eco-driving, distraction, speeding</td></tr></tbody></table>

### **MonthRanking**

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

<table><thead><tr><th width="215">Field</th><th width="175.66666666666663">Type</th><th>Description</th></tr></thead><tbody><tr><td>monthNumber</td><td><code>int</code></td><td>Month number of the ranking period (1 -> january, 2 -> february, ...)</td></tr><tr><td>driverRankedNumber</td><td><code>int</code></td><td>Number of ranked drivers</td></tr><tr><td>driverRanked</td><td><code>array[object]</code></td><td>List of ranked drivers <em>(see</em> <a href="#userranked"><em>UserRanked</em></a><em>)</em></td></tr><tr><td>driverNotRanked</td><td><code>array[object]</code></td><td>List of unranked drivers (i.e. who have not driven the minimum distance and completed the minimum number of trips) <em>(see</em> <a href="#usernotranked"><em>UserNotRanked</em></a><em>)</em></td></tr></tbody></table>

### **UserRanked**

<table><thead><tr><th width="152">Field</th><th width="102.66666666666666">Type</th><th>Description</th></tr></thead><tbody><tr><td>userId</td><td><code>string</code></td><td>Driver's unique identifier</td></tr><tr><td>firstname</td><td><code>string</code></td><td>Driver's firstname</td></tr><tr><td>lastname</td><td><code>string</code></td><td>Driver's lastname</td></tr><tr><td>pseudo</td><td><code>string</code></td><td>Driver's pseudo</td></tr><tr><td>rank</td><td><code>int</code></td><td>Driver's rank</td></tr><tr><td>score</td><td><code>double</code></td><td>Driver's score</td></tr><tr><td>distance</td><td><code>double</code></td><td>Monthly driving distance (in km)</td></tr><tr><td>tripNumber</td><td><code>double</code></td><td>Monthly number of trips</td></tr></tbody></table>

### UserNotRanked

<table><thead><tr><th width="144">Field</th><th width="132.66666666666666">Type</th><th>Description</th></tr></thead><tbody><tr><td>userId</td><td><code>string</code></td><td>Driver's unique identifier</td></tr><tr><td>firstname</td><td><code>string</code></td><td>Driver's firstname</td></tr><tr><td>lastname</td><td><code>string</code></td><td>Driver's lastname</td></tr><tr><td>pseudo</td><td><code>string</code></td><td>Driver's pseudo</td></tr><tr><td>distance</td><td><code>double</code></td><td>Monthly driving distance (in km)</td></tr><tr><td>tripNumber</td><td><code>double</code></td><td>Monthly number of trips</td></tr></tbody></table>