Leaderboards¶
This module uses the scoring generated by the scoring module (to be precise, the profile scores from the scoring module) to rank users in decreasing order of wins.
Since leaderboards are generated automatically, this module DOES NOT expose any APIs that allow modification of data.
API: Overall Leaderboard¶
Get overall leaderboard API
URL: {BASE_URL}/app/<APP_ID>/leaderboards
Request Method: HTTP GET
| Parameter | Mandatory | Type | Description |
|---|---|---|---|
| APP_ID | Yes | Alpha-numeric | The application ID issued by the Playblazer platform when the app was created |
| secret_key | Yes | Alpha-numeric | The secret key issued by the Playblazer platform when the app was created |
| type | No | String | Type of leaderboard required. One of the following:
|
| start | No | Numeric | The start of the pagination |
| limit | No | Numeric | The no. of results to return in output |
| fmt | No | String | One of (json | xml) - the format of output |
In case of error, the output will contain status=error and error details encoded as explained earlier.
If successful, the output will contain the usual status=ok along with a dictionary called leaderboards containing a list all indicating global leaderboard.
Each entry in the all list comprises of the following data:
- rank - the rank of the user in the leaderboard
- user - the data about the user - which internally consists of a list of attributes as key, value pair in a dictionary called attribs
- wins/played/level/ratio/rp - the count of wins/played/level/win-loss ratio/respect points as per the type of leaderboard requested
Example¶
URL Call:
curl "http://api.playblazer.com/v1/app/1/leaderboards?secret_key=cb8d878989b9478e96d1b1574a1bf4ec&start=76640&limit=10&type=wins"
Output:
{
"status": "ok",
"leaderboards": {
"wins": {
"all": [
{
"user": {
"attribs": {}
},
"rank": 76641,
"wins": 78
},
{
"user": {
"attribs": {}
},
"rank": 76642,
"wins": 78
},
{
"user": {
"attribs": {
"twitterid": null,
"fbid": "kunalg",
"last_name": null,
"first_name": null,
"email": null,
"googleid": null,
}
},
"rank": 76643,
"wins": 78
},
{
"user": {
"attribs": {}
},
"rank": 76644,
"wins": 77
},
{
"user": {
"attribs": {}
},
"rank": 76645,
"wins": 77
},
{
"user": {
"attribs": {}
},
"rank": 76646,
"wins": 76
},
{
"user": {
"attribs": {}
},
"rank": 76647,
"wins": 76
},
{
"user": {
"attribs": {}
},
"rank": 76648,
"wins": 76
},
{
"user": {
"attribs": {}
},
"rank": 76649,
"wins": 75
},
{
"user": {
"attribs": {}
},
"rank": 76650,
"wins": 75
}
]
}
}
}
API: User’s Leaderboard¶
Get user’s leaderboard API
URL: {BASE_URL}/app/<APP_ID>/leaderboards/user/<MODE>/<USER_ID>
Request Method: HTTP GET
| Parameter | Mandatory | Type | Description |
|---|---|---|---|
| APP_ID | Yes | Alpha-numeric | The application ID issued by the Playblazer platform when the app was created |
| secret_key | Yes | Alpha-numeric | The secret key issued by the Playblazer platform when the app was created |
| MODE | Yes | String | The mode for user ID interpretation |
| USER_ID | Yes | String | The user ID for whom the pairing needs to be generated. |
| type | No | String | Type of leaderboard required. One of the following:
|
| start | No | Numeric | The start of the pagination |
| limit | No | Numeric | The no. of results to return in output |
| fmt | No | String | One of (json | xml) - the format of output |
In case of error, the output will contain status=error and error details encoded as explained earlier.
If successful, the output will contain the usual status=ok along with a dictionary called leaderboards .
The leaderboards dictionary contains another dictionary based on the type of leaderboard - for example:
- if the leaderboard type is “wins”, then the “leaderboards” dictionary will contain a child dictionary called “wins”
- if the leaderboard type is “played”, then the “leaderboards” dictionary will contain a child dictionary called “played”
- if the leaderboard type is “level”, then the “leaderboards” dictionary will contain a child dictionary called “level”
- if the leaderboard type is “ratio”, then the “leaderboards” dictionary will contain a child dictionary called “ratio”
- if the leaderboard type is “rp”, then the “leaderboards” dictionary will contain a child dictionary called “rp”
The “type-of-leaderboard” dictionary contains following data:
you - a dictionary with attributes
- rank - indicating user’s position in the global leaderboard
- wins/played/level/ratio/rp - the count of wins/played/level/win-loss ratio as per the type of leaderboard requested.
global - this the same as all dictionary from the output of Overall Leaderboard API
friends - the ranks of friends from the friend list pulled from the social network. This is available only for friends who are already part of the application database - i.e. whose profile status is not unregistered (cf. Module User Profile).
Each entry in the “friends” list has following attributes:
- “fbid”/”googleid” etc. - corresponding to the social network from which the friends list was populated.
- “rank” - the rank of the user in the application leaderboards
- “fname” - the first name of the user - for easier display - if available.
- “wins/played/level/ratio/rp” - the count of wins/played/level/win-loss ratio/respect points as per the type of leaderboard requested.
Example¶
URL Call:
curl "http://api.playblazer.com/v1/app/1/leaderboards/user/fb/kunalg?secret_key=cb8d878989b9478e96d1b1574a1bf4ec&start=76640&limit=10&type=wins"
Output:
{
"status": "ok",
"leaderboards": {
"wins": {
"you": {
"rank": 76643,
"wins": 78
},
"global": [
{
"user": {
"attribs": {}
},
"rank": 76641,
"wins": 78
},
{
"user": {
"attribs": {}
},
"rank": 76642,
"wins": 78
},
{
"user": {
"attribs": {
"twitterid": null,
"fbid": "kunalg",
"last_name": null,
"first_name": null,
"email": null,
"googleid": null,
}
},
"rank": 76643,
"wins": 78
},
{
"user": {
"attribs": {}
},
"rank": 76644,
"wins": 77
},
{
"user": {
"attribs": {}
},
"rank": 76645,
"wins": 77
},
{
"user": {
"attribs": {}
},
"rank": 76646,
"wins": 76
},
{
"user": {
"attribs": {}
},
"rank": 76647,
"wins": 76
},
{
"user": {
"attribs": {}
},
"rank": 76648,
"wins": 76
},
{
"user": {
"attribs": {}
},
"rank": 76649,
"wins": 75
},
{
"user": {
"attribs": {}
},
"rank": 76650,
"wins": 75
}
],
"friends": [
{
"fbid": "xxxxxxxxxxxxxxxxxx",
"rank": 84412,
"fname": "Kunal",
"wins": 39
}
]
}
}
}