Leaderboard endpoints

Leaderboard

Returns a leaderboard page for provided game. Can be configured using additional fields.

Endpoint specs

• Path: https://api.elympics.cc/v2/leaderboardservice/leaderboard
• Method: GET
• Query params:
  • GameId - ID of the game for which leaderboard should be returned
  • GameVersion - (optional) the version name of the game for which leaderboard should be returned
  • TournamentId - (optional) ID of the tournament
  • PageNumber - (optional) number of the page (counting from 1); default: 1
  • PageSize - (optional) number of entries on each page; default: 10
  • TimeScope - (optional) time scope of the leaderboard: AllTime, Month, Day, or Custom (which requires providing additional params: DateFrom and DateTo containing timestamps in ISO 8601 format); default: AllTime
• Headers:
  • Authorization: Bearer PLAYER_JWT_TOKEN
  • Elympics-Publisher-API-Key: YOUR_API_KEY

Example 200 response

{
    "data": [
        {
            "userId": "23f47922-043b-4427-9642-42e3077519bd",  // Elympics user id
            "nickname": "d4ftslay3r",                          // nickname of the player assigned in Elympics system
            "telegramId": "1234567890",                        // user's telegram ID
            "position": 1,                                     // position in leaderboard
            "points": 123.45                                   // score points earned
        }
    ],
    "pageNumber": 1,    // current page number
    "pageSize": 1,      // current page size
    "totalPages": 11,   // total number of pages
    "totalRecords": 11  // total number of records
}

User-centered leaderboard

Returns the page from game's leaderboard where player currently is. Can be configured using additional fields.

Endpoint specs

• Path: https://api.elympics.cc/v2/leaderboardservice/leaderboard/user-centred
• Method: GET
• Query params:
  • GameId - ID of the game for which leaderboard should be returned
  • GameVersion - (optional) the version name of the game for which leaderboard should be returned
  • TournamentId - (optional) ID of the tournament
  • PageSize - (optional) number of entries on each page; default: 10
  • TimeScope - (optional) time scope of the leaderboard: AllTime, Month, Day, or Custom (which requires providing additional params: DateFrom and DateTo containing timestamps in ISO 8601 format); default: AllTime
• Headers:
  • Authorization: Bearer PLAYER_JWT_TOKEN
  • Elympics-Publisher-API-Key: YOUR_API_KEY

Example 200 response

caution

If player is not on the leaderboard, this endpoint will return an empty response.

{
    "data": [
        {
            "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  // Elympics user id
            "nickname": "d4ftslay3r",                          // nickname of the player assigned in Elympics system
            "telegramId": "1234561337",                        // user's telegram ID
            "position": 6,                                     // position in leaderboard
            "points": 51.5                                     // score points earned
        }
    ],
    "pageNumber": 6,    // current page number
    "pageSize": 1,      // current page size
    "totalPages": 11,   // total number of pages
    "totalRecords": 11  // total number of records
}

User's high score

Returns user's high score. Game version, tournament and time scope can be restricted using query parameters.

Endpoint specs

• Path: https://api.elympics.cc/v2/leaderboardservice/leaderboard/user-centred
• Method: GET
• Query params:
  • GameId - ID of the game for which leaderboard should be returned
  • GameVersion - (optional) the version name of the game for which leaderboard should be returned
  • TournamentId - (optional) ID of the tournament
  • TimeScope - (optional) time scope of the leaderboard: AllTime, Month, Day, or Custom (which requires providing additional params: DateFrom and DateTo containing timestamps in ISO 8601 format); default: AllTime
• Headers:
  • Authorization: Bearer PLAYER_JWT_TOKEN
  • Elympics-Publisher-API-Key: YOUR_API_KEY

Example 200 response

caution

If player has no high score, this endpoint will return an empty response.

{
    "points": 51.5,                        // max points earned
    "endedAt": "2024-12-21T12:21:12.212Z"  // ISO 8601 timestamp when the high score was earned
}