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:

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.

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

List all ranked users

GEThttps://service.drivequant.com/v3/drivekit/admin/challenges/{challengeId}/rankings

Path parameters

challengeId*string

Unique identifier of the challenge

Query parameters

Header parameters

Response

200204400401404

OK

Body

application/json

challengeIdstring

Unique identifier of the challenge

groupstring

If present, indicates that the rankings are specific for this group label

conditionsChallengeConditions

Conditions that need to be filled for a user to be ranked

registeredUsersinteger

Total number of users registered to the challenge

rankedUsersinteger

Total number of users ranked in the challenge

totalDistanceinteger

Total distance driven by the users for the challenge

totalNumberTripsinteger

Total number of trips made by the users for the challenge

usersRankedarray of UserRanked

List of ranked users

usersNotRankedarray of UserNotRanked

List of users not ranked

Request

JavaScriptCurlPython

const response = await fetch('https://service.drivequant.com/v3/drivekit/admin/challenges/{challengeId}/rankings', {
    method: 'GET',
    headers: {
      "DriveKit-Admin-API-Key": "text"
    },
});
const data = await response.json();

Response

200400401404

{
  "challengeId": "text",
  "group": "text",
  "conditions": {
    "km": 0,
    "nbTrip": 0
  },
  "registeredUsers": 0,
  "rankedUsers": 0,
  "totalDistance": 0,
  "totalNumberTrips": 0,
  "usersRanked": [
    {
      "username": "text",
      "firstname": "text",
      "lastname": "text",
      "registerDate": "2024-12-21T11:55:35.642Z",
      "numberTrips": 0,
      "distance": 0,
      "rank": 0,
      "score": 0
    }
  ],
  "usersNotRanked": [
    {
      "username": "text",
      "firstname": "text",
      "lastname": "text",
      "registerDate": "2024-12-21T11:55:35.642Z",
      "numberTrips": 0,
      "distance": 0
    }
  ]
}

---

Response

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

Field	Type	Description
challengeId	string	Unique identifier of the challenge
group	string	If present, indicates that the rankings are specific for this group label
conditions	ChallengeConditions	Conditions that need to be filled for a user to be ranked
registeredUsers	int	Total number of users registered to the challenge
rankedUsers	int	Total number of users ranked in the challenge
totalDistance	int	Total distance driven by the users for the challenge
totalNumberTrips	int	Total number of trips made by the users for the challenge
usersNotRanked	array[object]	List of users not ranked in the challenge (see UserNotRanked)
usersRanked	array[object]	List of users ranked in the challenge (see UserRanked)

ChallengeConditions

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

Field	Type	Description
km	int	Minimum distance required to be ranked (in km)
nbTrip	int	Minimum number of trips required to be ranked

UserNotRanked

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

Field	Type	Description
username	string	Unique identifier of the user
firstname	string	First name of the user
lastname	string	Last name of the user
registerDate	string	Date at which the user entered the challenge Date format: YYYY-MM-dd’T’HH:mm:ss.SSSZ
numberTrips	int	Number of trips since the user registered to the challenge
distance	int	Distance since the user registered to the challenge

UserRanked

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

Field	Type	Description
username	string	Unique identifier of the user
firstname	string	First name of the user
lastname	string	Last name of the user
registerDate	string	Date at which the user entered the challenge Date format: YYYY-MM-dd’T’HH:mm:ss.SSSZ
numberTrips	int	Number of trips since the user registered to the challenge
distance	int	Distance since the user registered to the challenge
rank	int	Current rank of the user
score	double	Score of the user during the challenge