# 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="/files/osFwnNfAb4AWP4NEZNUc" 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>


---

# 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/challenges/challenge-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.