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/[e-mail]"
        },
        {
            "displayName": "Player 2",
            "playerUniqueId": "3172250157098",
            "progress": 110,
            "rank":2,
            "levelName": "Basic",
            "levelIcon": "https://cdn.gameball.co/uploads/c007/[e-mail]"
        }
    ],
    "playerRank": {
        "rank": 70,
        "playersCount": 100
    }
}

Usage Example

cURL

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"

Ruby

# Example 1
Gameball::Leaderboard.get_leaderboard()

# Example 2
Gameball::Leaderboard.get_leaderboard({from: "2021-02-13%2000%3A00",
    to: "2021-02-18%2000%3A00"})

PHP

// 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);

Python

# Example 1
leaderboard = gameball.leaderboard()

# Example 2
leaderboard = gameball.leaderboard(from_date="2021-02-13%2000%3A00", to_date="2021-02-18%2000%3A00")

.NET

var response = Gameball.Leaderboard(from="2021-02-13%2000%3A00",
        to="2021-02-18%2000%3A00")