Leaderboard 👑

Motivate your customers to engage more on your platform by showing a gamified leaderboard on your website or mobile app

This endpoint allows you to retrieve the customers' leaderboard for a given date range. It can also be used to get a specific customer's rank among all customers.

This endpoint is only available for our GURU clients only. 👑

GET - Leaderboard

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

This API call is used to retrieve customers' 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 customer (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 customers in the leaderboard. Default size is 20 customers. Max is 50
playerUniqueId	string	No	Unique identifier for a customer at Gameball. This parameter is used in case you need to get a specific customer's rank.
challengeId	string	No	Rewards Campaign ID used in case you need to leaderboard of specific rewards campaign.
challengeTag	string	No	Rewards Campaign Tag, used in case you need to get leaderboard of a rewards campaign linked with a specific tag
playerTag	string	No	Customer Tag, used in case you need to get leaderboard of customers linked to a specific tag

Response

Parameter	Type	Description
leaderboard	array	A list of customers 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 customer with the provided playerUniqueId relative to all your system customers . (This object is returned if the playerUniqueId is provided in the request as a query parameter)

leaderboard object

The leaderboard object defines the customer rank and progress in the leaderboard based on the specified query parameters.

Parameter	Type	Description
displayName	string	Customer's display name.
playerUniqueId	string	Unique identifier for a customer at Gameball.
progress	integer	Customer's progress (based on the specified query parameters).
rank	integer	Customer's Rank (based on the specified query parameters).
levelName	string	VIP tier Name. Example: "Bronze"
levelIcon	string	VIP tier's icon URL.

playerRank Object

Parameter	Type	Description
rank	integer	Customer's rank in the leaderboard.
playersCount	integer	Total number of customers 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")