Build Leaderboards

In your app or web page you may need to display the leaderboard for your players. In that case you can make use of the Leaderboard API that can help you build the desired leaderboard UI in a flexible way that handles different cases.

The leaderboard API returns a list of players ordered by their rank for a given period of time. A single element in the leaderboard list represents a player with his status

{
    "displayName": "Player 1",
    "playerUniqueId": "5097238429738",
    "progress": 1748,
    "rank":1,
    "levelName": "Bronze",
    "levelIcon": "https://cdn.gameball.co/uploads/c007/[e-mail]"
}
…
…

Each player element in the list has the player’s name, unique id, progress in the given period, rank among the leaderboard, and info about their level.

Note: Gameball doesn't currently support images for players. In order to map your players and their respective images, it has to be done manually.

The leaderboard API accepts two important filters (from, to) as query strings. These filters control the returned leaderboard time window. Let's consider the following scenarios:

Show today’s leaderboard

This can be done by sending the from query parameter as today’s date. Lets say today is the 24th of Dec 2021, then the request would be as following

https://api.gameball.co/api/v3.0/integrations/leaderboard?
from=2021-12-24 00:00

Show last month leaderboard

This can be done by sending the from and to query filter setting the boundaries of last month. For example if the current month is December, and you are looking for the previous month's (November) leaderboard. Then we would be setting the from and to dates as below

https://api.gameball.co/api/v3.0/integrations/leaderboard?
from=2021-11-01 00:00&to=2021-11-30 00:00

Show the all time leaderboard

From and to filters are omitted from the request.

https://api.gameball.co/api/v3.0/integrations/leaderboard

The leaderboard API can also be used to show a specific player's rank by sending the Player Unique Id as a filter

https://api.gameball.co/api/v3.0/integrations/leaderboard?
from=2021-11-01 00:00&to=2021-11-30 00:00&playerUniqueId=player456

This will return a playerRank object with the leaderboard list within the response that shows the player rank even if he is not listed within the leaderboard.

"playerRank": {
    "rank": 70,
    "playersCount": 100
}