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
Header
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")

Order

Notifications 👑

Last modified 1yr ago

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. 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)

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.

Leaderboard 👑

GET - Leaderboard

Request

Header

Query Parameters

Response

`leaderboard` object

`playerRank` Object

Sample Response

Usage Example