Users' progress

This service returns the list of the users registered to the challenge, who were ranked and had enough data before the challenge started (i.e., has made at least 10 trips during the pre-challenge period).

The service returns their progress (i.e. score comparison before and during the challenge) and all the ranking details (number of trips, distance, score). The list is sorted from best to worst progression.

If the challenge has not yet finished, 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

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

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

List all users' progress

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

Path parameters

challengeId*string

Unique identifier of the challenge

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

registeredUsersinteger

Total number of users registered to the challenge

rankedUsersinteger

Total number of users ranked in the challenge

usersWithDataBeforeinteger

Total number of users who have enough data before the challenge started

totalDistanceinteger

Total distance driven by the challenge's user

totalNumberTripsinteger

Total number of trips made by the challenge's user

usersarray of UserRankedWithProgress

List of ranked users

Request

JavaScriptCurlPython

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

Response

200400401404

{
  "challengeId": "text",
  "group": "text",
  "users": [
    {
      "username": "text",
      "firstname": "text",
      "lastname": "text",
      "registerDate": "2024-09-14T10:03:00.581Z",
      "score": 0,
      "scoreBefore": 0,
      "scoreEvolution": 0
    }
  ]
}

---

Response

The table below summarizes the elements included in the ChallengeProgressResponse 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
registeredUsers	int	Total number of users registered to the challenge
rankedUsers	int	Total number of users ranked in the challenge
usersWithDataBefore	int	Total number of users who have enough data before the challenge started
totalDistance	int	Total distance driven by the users for the challenge
totalNumberTrips	int	Total number of trips made by the users for the challenge
users	array[object]	List of users ranked in the challenge with enough data before the challenge (see UserNotRanked)

UserRankedWithProgress

The table below summarizes the elements included in the UserRankedWithProgress 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
scoreBefore	double	Score of the user during the pre-challenge period
scoreEvolution	double	Evolution of the score of the user (i.e., effect of the challenge on the user's score)