# Challenge ranking

This service returns the list of all the users registered to the challenge, along with their rankings and ranking details (*i.e.*, number of trips and total distance driven during the challenge).

If the challenge has not yet started, the service will return a HTTP 204 (no body) response, along with a `Retry-After` header containing the date at which the response will be available:

```http
Retry-After: Wed, 21 Oct 2022 07:28:00 GMT
```

The `usersRanked` list contains the list of all registered users who have met the requirements for the challenge. These users have a rank, and a score. 

The `usersNotRanked` list contains the list of registered users who have *not yet* met the requirements, but who might already have started accumulating challenge data. The users do not have a score yet, but their number of trips and distance driven are returned in order to evaluate their progress.

If the challenge only concerns a specific group (or groups), then the service also accepts a `group` request parameter to retrieve the rankings for a single group. If no value is provided, then the global ranking is returned.

{% 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/f4ee9d9dfa318-list-all-ranked-users).
{% endhint %}

{% openapi src="<https://2525923625-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LXYIG5U3AO65YYFWJRK%2Fuploads%2FN7KAiaeCZUgSyP3ciH8Y%2Fdrivekit-admin-challenge-v3.yml?alt=media&token=8308057e-25b8-4b42-8b57-aab662abd6b5>" path="/drivekit/admin/challenges/{challengeId}/rankings" method="get" %}
[drivekit-admin-challenge-v3.yml](https://2525923625-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LXYIG5U3AO65YYFWJRK%2Fuploads%2FN7KAiaeCZUgSyP3ciH8Y%2Fdrivekit-admin-challenge-v3.yml?alt=media\&token=8308057e-25b8-4b42-8b57-aab662abd6b5)
{% endopenapi %}

***

## Response

The table below summarizes the elements included in the `ChallengeRankingsResponse` object.

<table><thead><tr><th width="217.66666666666666">Field</th><th width="193">Type</th><th>Description</th></tr></thead><tbody><tr><td>challengeId</td><td><code>string</code></td><td>Unique identifier of the challenge</td></tr><tr><td>group</td><td><code>string</code></td><td>If present, indicates that the rankings are specific for this group label</td></tr><tr><td>conditions</td><td><a href="#challengeconditions"><em>ChallengeConditions</em></a></td><td>Conditions that need to be filled for a user to be ranked</td></tr><tr><td>registeredUsers</td><td><code>int</code></td><td>Total number of users registered to the challenge</td></tr><tr><td>rankedUsers</td><td><code>int</code></td><td>Total number of users ranked in the challenge</td></tr><tr><td>totalDistance</td><td><code>int</code></td><td>Total distance driven by the users for the challenge</td></tr><tr><td>totalNumberTrips</td><td><code>int</code></td><td>Total number of trips made by the users for the challenge</td></tr><tr><td>usersNotRanked</td><td><code>array[object]</code></td><td>List of users not ranked in the challenge <em>(see</em> <a href="#usernotranked"><em>UserNotRanked</em></a><em>)</em></td></tr><tr><td>usersRanked</td><td><code>array[object]</code></td><td>List of users ranked in the challenge <em>(see</em> <a href="#userranked"><em>UserRanked</em></a><em>)</em></td></tr></tbody></table>

### ChallengeConditions

The table below summarizes the elements included in the `ChallengeConditions` object.

<table><thead><tr><th width="113.66666666666666">Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>km</td><td><code>int</code></td><td>Minimum distance required to be ranked (in km)</td></tr><tr><td>nbTrip</td><td><code>int</code></td><td>Minimum number of trips required to be ranked</td></tr></tbody></table>

### UserNotRanked

The table below summarizes the elements included in the `UserNotRanked` object.

<table><thead><tr><th width="217.66666666666666">Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>username</td><td><code>string</code></td><td>Unique identifier of the user</td></tr><tr><td>firstname</td><td><code>string</code></td><td>First name of the user</td></tr><tr><td>lastname</td><td><code>string</code></td><td>Last name of the user</td></tr><tr><td>registerDate</td><td><code>string</code></td><td>Date at which the user entered the challenge<br><em>Date format: <code>YYYY-MM-dd’T’HH:mm:ss.SSSZ</code></em></td></tr><tr><td>numberTrips</td><td><code>int</code></td><td>Number of trips since the user registered to the challenge</td></tr><tr><td>distance</td><td><code>int</code></td><td>Distance since the user registered to the challenge</td></tr></tbody></table>

### UserRanked

The table below summarizes the elements included in the `UserRanked` object.

<table><thead><tr><th width="217.66666666666666">Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>username</td><td><code>string</code></td><td>Unique identifier of the user</td></tr><tr><td>firstname</td><td><code>string</code></td><td>First name of the user</td></tr><tr><td>lastname</td><td><code>string</code></td><td>Last name of the user</td></tr><tr><td>registerDate</td><td><code>string</code></td><td>Date at which the user entered the challenge<br><em>Date format: <code>YYYY-MM-dd’T’HH:mm:ss.SSSZ</code></em></td></tr><tr><td>numberTrips</td><td><code>int</code></td><td>Number of trips since the user registered to the challenge</td></tr><tr><td>distance</td><td><code>int</code></td><td>Distance since the user registered to the challenge</td></tr><tr><td>rank</td><td><code>int</code></td><td>Current rank of the user</td></tr><tr><td>score</td><td><code>double</code></td><td>Score of the user during the challenge</td></tr></tbody></table>