Player stats and leaderboards

Idem is keeping track of the stats of each player. This can be retrieved directly per player and is also used to create leaderboards for each game mode and season that can be accessed via the API. This page explains how to use each of the two.

Player stats

Player stats can be accessed via the getPlayerStats action. The action has the following parameters:

Parameter	Optional	Description
playerId	No	The id of the player for whom the stats should be returned.
seasons	Yes	An array of seasons for which the stats should be returned. Example: ["S1", "S5", "S6"]. If not provided, the data for the current and previous season will be returned. You can request a maximum of 5 seasons.

info

If your game does not use seasons, everything will be attached to season "S1" and this will be the current season. So you don't need to provide any input for seasons

Below is an example for a simple request for playerA without specifying seasons. So this will return the current and previous (if the current is not S1).

{
  "action": "getPlayerStats",
  "messageId": null,
  "payload": {
    "playerId": "playerA"
  }
}

If the player exists, a response in the following format will be returned:

{
  "action": "getPlayerStatsResponse",
  "payload": {
    "playerId": "playerA",
    "totalMatchesPlayed": 250,
    "totalWins": 160,
    "totalLosses": 90,
    "seasons": [
      {
        "season": "S2",
        "isCurrentSeason": false,
        "seasonMatchesPlayed": 100,
        "seasonWins": 64,
        "seasonLosses": 36,
        "stats": [
          {
            "matchesPlayed": 60,
            "wins": 40,
            "losses": 20,
            "rating": 1560.0,
            "rankingPoints": 117.0,
            "rank": 5,
            "winRatio": 0.6667,
            "mode": "1v1",
            "ratingUncertainty": 110.0
          },
          {
            "matchesPlayed": 40,
            "wins": 24,
            "losses": 16,
            "rating": 1524.0,
            "rankingPoints": 103.0,
            "rank": 10,
            "winRatio": 0.6,
            "mode": "2v2",
            "ratingUncertainty": 130.0
          }
        ]
      },
      {
        "season": "S3",
        "isCurrentSeason": true,
        "seasonMatchesPlayed": 150,
        "seasonWins": 96,
        "seasonLosses": 54,
        "stats": [
          {
            "matchesPlayed": 90,
            "wins": 60,
            "losses": 30,
            "rating": 1590.0,
            "rankingPoints": 155.0,
            "rank": 4,
            "winRatio": 0.6667,
            "mode": "1v1",
            "ratingUncertainty": 90.0
          },
          {
            "matchesPlayed": 60,
            "wins": 36,
            "losses": 24,
            "rating": 1536.0,
            "rankingPoints": 93.0,
            "rank": 9,
            "winRatio": 0.6,
            "mode": "2v2",
            "ratingUncertainty": 110.0
          }
        ]
      }
    ]
  }
}

Note how this includes the following data:

• Overall matches, wins and losses
• Season matches, wins and losses
• Detailed stats for each game mode per season, including the leaderboard rank

Each season entry also has a property isCurrentSeason which is true for the current season and false otherwise.

Leaderboard

A leaderboard is created for each game mode. You can access the leaderboard data via the REST API using the following endpoint:

POST /games/{game_id}/leaderboard

tip

You can find information on autentication for the REST API here.

Parameters

There is different options for requesting the leaderboard. You select which one based on the parameters you pass in the POST request.

• From-top Returns the requested number of entries from the top of the leaderboard. {"count": "int"}
• From-rank Returns the requested number of entries starting at a rank. This can also be used to extract the leaderboard page-wise (e.g. 1-50, 51-100 etc.) {"count": "int", "fromRank": "int"}
• Around-player Returns the requested number players before and after the specified player. Used generally to show a players immediate sourrounding in the ranking table. {"count": "int", "playerId": "str"}

Additionally, you can pass a season paramter to requeset the data for a specific season. If the season parameter is not passed, the data for the current season will be returned.

Retrival limits

The size of the return of each request is limited by default. If you want to retrieve larger chunks of the leaderboard, we recommend From-Rank. That way you can iterate in steps through larger sets of the leaderboard

Method	Limit
Overall limit	500
From-top	500
From-rank	100
Around-player	50

Return shape

The endpoint returns an object of the following shape:

{
  "leaderboard": [
    { "playerId": "playerA", "rank": 1, "ranking_points": 153 },
    { "playerId": "playerB", "rank": 2, "ranking_points": 149 },
    { "playerId": "playerC", "rank": 3, "ranking_points": 137 },
    ...
  ],
  "season": "S<N>"
}