Comment on page

Leaderboard 👑

Motivate your players to engage more on your platform by showing a gamified leaderboard on your website or mobile app
This endpoint allows you to retrieve the players' leaderboard for a given date range. It can also be used to get a specific player's rank among all players.
This endpoint is only available for our GURU customers only. 👑

GET - Leaderboard

https://api.gameball.co/api/v3.0/integrations/leaderboard
This API call is used to retrieve players' leaderboard within a date range or all time, ordered from the highest to the lowest rank.
The request also accepts the playerUniqueId as an optional parameter where if provided, the rank of the player (with the specified ID) in the leaderboard will be returned.
mobile or email should replace playerUniqueId in case (only if) your account supports channel merging.

Request

Attribute
Type
Required
Description
APIKey
string
Yes
Client API key

Query Parameters

Attribute
Type
Required
Description
from
string
No
Leaderboard start datetime in the following format YYYY-MM-DD HH:MM (Example: 2021-02-13 00:00).
to
string
No
Leaderboard end datetime in the following format YYYY-MM-DD HH:MM
(Example: 2021-02-18 00:00).
limit
integer
No
The size of the returned players in the leaderboard.
Default size is 20 players. Max is 50
playerUniqueId
string
No
Unique identifier for a player at Gameball. This parameter is used in case you need to get a specific player's rank
challengeId
string
No
Challenge ID used in case you need to leaderboard of specific challenge
challengeTag
string
No
Challenge Tag, used in case you need to get leaderboard of a challenge linked with a specific tag
playerTag
string
No
Player Tag, used in case you need to get leaderboard of players linked to a specific tag

Response

Parameter
Type
Description
leaderboard
array
A list of players with their overall progress and rank based on the provided input parameters.
The leaderboard object is defined below.
playerRank
object
An object describing the rank of the player with the provided playerUniqueId relative to all your system players.
(This object is returned if the playerUniqueId is provided in the request as a query parameter)

leaderboard object

The leaderboard object defines the player rank and progress in the leaderboard based on the specified query parameters.
Parameter
Type
Description
displayName
string
Player's display name.
playerUniqueId
string
Unique identifier for a player at Gameball.
progress
integer
Player's progress (based on the specified query parameters).
rank
integer
Player's Rank (based on the specified query parameters).
levelName
string
Level Name.
Example: "Bronze"
levelIcon
string
Level's icon URL.

playerRank Object

Parameter
Type
Description
rank
integer
Player's rank in the leaderboard.
playersCount
integer
Total number of players in your system.

Sample Response

{
"leaderboard": [
{
"displayName": "Player 1",
"playerUniqueId": "5097238429738",
"progress": 1748,
"rank":1,
"levelName": "Bronze",
"levelIcon": "https://cdn.gameball.co/uploads/c007/[email protected]"
},
{
"displayName": "Player 2",
"playerUniqueId": "3172250157098",
"progress": 110,
"rank":2,
"levelName": "Basic",
"levelIcon": "https://cdn.gameball.co/uploads/c007/[email protected]"
}
],
"playerRank": {
"rank": 70,
"playersCount": 100
}
}

Usage Example

cURL
Ruby
PHP
Python
.NET
curl -X GET
"https://api.gameball.co/api/v3.0/integrations/leaderboard?from=2021-02-13%2000%3A00&to=2021-02-18%2000%3A00"
-H "accept: application/json"
-H "APIKey: 807b041b7d35425988e354e1f6bce186"
# Example 1
Gameball::Leaderboard.get_leaderboard()
# Example 2
Gameball::Leaderboard.get_leaderboard({from: "2021-02-13%2000%3A00",
to: "2021-02-18%2000%3A00"})
// EXAMPLE #1
$response = $gameball->leaderboard->getLeaderboard();
// EXAMPLE #2 with from date -> to date and limit 5
$response = $gameball->leaderboard->getLeaderboard("2021-02-13%2000%3A00", "2021-02-18%2000%3A00", 5);
# Example 1
leaderboard = gameball.leaderboard()
# Example 2
leaderboard = gameball.leaderboard(from_date="2021-02-13%2000%3A00", to_date="2021-02-18%2000%3A00")
var response = Gameball.Leaderboard(from="2021-02-13%2000%3A00",
to="2021-02-18%2000%3A00")