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. 👑
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.Attribute | Type | Required | Description |
APIKey | string | Yes | Client API key |
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 |
Parameter | Type | Description |
leaderboard | array | A list of players with their overall progress and rank based on the provided input parameters. |
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) |
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. |
Parameter | Type | Description |
rank | integer | Player's rank in the leaderboard. |
playersCount | integer | Total number of players in your system. |
{
"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
}
}
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")
Last modified 1yr ago