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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.drivequant.com/backend/drivers/ranking.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.