Leaderboard API

Pre-requisites¶

To use the Leaderboard API, the following items must be prepared:

Authentication Token (Certification Key) for API calls: Hive Console >App Center > Manage Project > Game Details > Basic Info > Certification Key
Leaderboard ID to use: Hive Console > Leaderboard > Manage Ranking

Request URL¶

Server	URL
LIVE	api-leaderboard.withhive.com
SANDBOX	sandbox-api-leaderboard.withhive.com

Response codes¶

Common response codes for the API.

Code	Value	Description
200	Success	-
400	Bad Request	Invalid `leaderboardId` or Param input
401	Unauthorized	The Authorization header of the request message is missing or its value is invalid
403	Forbidden	Authentication Token (Certification Key) for API calls is invalid
500	Internal Server Error	An internal problem in the server

Submit score¶

Stores a score on the leaderboard.

Request URL¶

LIVE URL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/score
SANDBOX URL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/score
HTTP METHOD	POST
CONTENT-TYPE	application/json

Path parameters¶

Field Name	Description	Type	Required
leaderboardId	Leaderboard ID	string	Y

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for calling API (Bearer)	string	Y

Request body¶

Field Name	Description	Type	Required
playerId	the Account identifier	long	Y
score	This is the score to register in the ranking. Up to 15 digits (999,999,999,999,999) can be entered.	integer	Y
achievementTimeUtc	The time the score recorded (based on UTC+0). The format is `yyyy-MM-dd'T'HH:mm:ss.SSS`.	string	Y
extraData	This is the additional information of the playerid account (nickname, level, country, etc.). Up to 256 characters can be entered.	string	N

Response¶

If 200 OK, the response body is empty.

Request sample¶

curl --location 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/score'
 --header 'Content-Type: application/json'
 --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'
 --data '{
"playerId": 1000,
"score": 87,
"achievementTimeUtc": "2023-12-19T15:01:01.004",
"extraData": "Lv.14|User1|KR"
}'

Delete score (Delete user information)¶

Deletes user information registered on the leaderboard.

Request URL¶

LIVE URL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}
SANDBOX URL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}
HTTP METHOD	DELETE
CONTENT-TYPE	application/json

Path parameters¶

Field Name	Description	Type	Required
leaderboardId	Leaderboard ID	string	Y
playerId	Account identifier	string	Y

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for calling API (Bearer)	string	Y

Response¶

If 200 OK, the response body is empty.

Request sample¶

curl --location
--request DELETE 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/players/1004'
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'
--data ''

Inquire ranking: Page-wise inquiry¶

Queries the rankings from the top, page by page.

Request URL¶

LIVE URL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/ranks
SANDBOX URL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/ranks
HTTP METHOD	GET
CONTENT-TYPE	application/json

Path parameters¶

Field Name	Description	Type	Required
leaderboardId	Leaderboard ID	string	Y

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token required for API call (Bearer)	string	Y

Query parameters¶

Field Name	Description	Type	Required
page	Requested page number. Starts from 1, default is 1. If value is 5, only the content of page 5 is queried.	integer	N
rowcount	Number of ranking information to display per page. Maximum 100, default is 100.	integer	N
requesttimeutc	Base time for inquiry (based on UTC+0). Default is the current time. Format is `yyyy-MM-dd'T'HH:mm:ss.SSS`.	string	N
playerid	If ranking information for the playerid account exists, it queries that player's ranking information as well.	long	N

Response¶

Field Name	Description	Type
rankingList	List of ranking data	json array
rankingList[].rank	Rank	integer
rankingList[].playerId	Account identifier	long
rankingList[].score	Score	long
rankingList[].achievementTimeUtc	Time when the score was registered (based on UTC+0). Format: `yyyy-MM-dd'T'HH:mm:ss.SSS`	string
rankingList[].extraData	additional information of the playerid account (nickname, level, country, etc.)	string
playerRank	Ranking information of the user with the `playerid` provided in the Query Parameter (Returned only if `playerid` information is present in the Query Parameter)	json
playerRank.rank	Rank	integer
playerRank.playerId	Account identifier	long
playerRank.score	Score	long
playerRank.achievementTimeUtc	Time when the score was registered (based on UTC+0), format: `yyyy-MM-dd'T'HH:mm:ss.SSS`	string
playerRank.extraData	additional information of the playerid account (nickname, level, country, etc.)	string

Request sample¶

curl --location 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/ranks?page=1&rowcount=100&playerid=1000&requesttimeutc=2023-12-19T15%3A01%3A01.004'
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

Response sample¶

{
    "rankingList": [
        {
            "rank": 1,
            "playerId": 1001,
            "score": 89,
            "achievementTimeUtc": "2023-12-19T15:02:02.004",
            "extraData": "Lv.50|User1|KR"
        }, {
            "rank": 2,
            "playerId": 1000,
            "score": 87,
            "achievementTimeUtc": "2023-12-19T15:01:01.004",
            "extraData": "Lv.50|User14|KR"
        }
    ],
    "playerRank": {
        "rank": 2,
        "playerId": 1000,
        "score": 87,
        "achievementTimeUtc": "2023-12-19T15:01:01.004",
        "extraData": "Lv.50|User14|KR"
    }
}

If the playerid is not provided in the Query Parameter, the result will not include playerRank. If provided, but there's no ranking information for the account, playerRank will return in the following format:

"playerRank": null

Inquire ranking: Inquire specific user ranking information¶

Queries ranking information for a specific user.

Request URL¶

LIVE URL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks
SANDBOX URL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks
HTTP METHOD	GET
CONTENT-TYPE	application/json

Path parameters¶

Field Name	Description	Type	Required
leaderboardId	Leaderboard ID	string	Y
playerId	Account identifier	string	Y

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token required for API call (Bearer)	string	Y

Query parameters¶

Field Name	Description	Type	Required
requesttimeutc	Base time for inquiry (based on UTC+0), format: `yyyy-MM-dd'T'HH:mm:ss.SSS`	string	N

Response¶

Field Name	Description	Type
playerRank.rank	Rank	integer
playerRank.playerId	Account identifier	long
playerRank.score	Score	long
playerRank.achievementTimeUtc	Time when the score was registered (based on UTC+0), format: `yyyy-MM-dd'T'HH:mm:ss.SSS`	string
playerRank.extraData	additional information of the playerid account (nickname, level, country, etc.)	string

Request sample¶

curl --location 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/players/1000/ranks?requesttimeutc=2023-12-19T15%3A01%3A01.004'
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

Response sample¶

{
    "playerRank": {
        "rank": 2,
        "playerId": 1000,
        "score": 87,
        "achievementTimeUtc": "2023-12-19T15:01:01.004",
        "extraData": "Lv.50|User14|KR"
    }
}

Inquire ranking: Information of ranking around a specific user¶

Queries the ranking information around a specific user. You can obtain ranking information for the top 50 or bottom 50 users around a specific user.

Request URL¶

Live URL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks
Sandbox URL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks
HTTP Method	GET
Content-Type	application/json

Path Parameters¶

Field Name	Description	Type	Required
leaderboardId	Leaderboard ID	string	Y
playerId	Account identifier	string	Y

Header Parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token required for API call (Bearer)	string	Y

Query Parameters¶

Field Name	Description	Type	Required
nearby	The number of rankings around the `playerId`. Maximum of 100.	integer	Y
requesttimeutc	Base time for inquiry (UTC+0), format: `yyyy-MM-dd'T'HH:mm:ss.SSS`	string	N

Response¶

Field Name	Description	Type
rankingList	List of ranking data	json array
rankingList[].rank	Rank	integer
rankingList[].playerId	Account identifier	long
rankingList[].score	Score	long
rankingList[].achievementTimeUtc	Time when the score was registered (UTC+0), format: `yyyy-MM-dd'T'HH:mm:ss.SSS`	string
rankingList[].extraData	additional information of the playerid account (nickname, level, country, etc.)	string
playerRank	User ranking information for the `playerid` entered in the Path Parameter	json
playerRank.rank	Rank	integer
playerRank.playerId	The account identifier	long
playerRank.score	Score	long
playerRank.achievementTimeUtc	The time when the score was recorded (in UTC+0), in the `yyyy-MM-dd'T'HH:mm:ss.SSS` format	string
playerRank.extraData	additional information of the playerid account (nickname, level, country, etc.)	string

Request sample¶

curl --location 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/players/1000/ranks?nearby=100&requesttimeutc=2023-12-19T15%3A01%3A01.004'
 --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

Response sample¶

{
    "rankingList": [
        {
            "rank": 1,
            "playerId": 1001,
            "score": 89,
            "achievementTimeUtc": "2023-12-19T15:02:02.004",
            "extraData": "Lv.50|User1|KR"
        }, {
            "rank": 2,
            "playerId": 1000,
            "score": 87,
            "achievementTimeUtc": "2023-12-19T15:01:01.004",
            "extraData": "Lv.50|User2|KR"
        }, {
            "rank": 3,
            "playerId": 1002,
            "score": 70,
            "achievementTimeUtc": "2023-12-19T15:02:02.004",
            "extraData": "Lv.50|User3|KR"
        }
    ],
        "playerRank": {
            "rank": 2,
            "playerId": 1000,
            "score": 87,
            "achievementTimeUtc": "2023-12-19T15:01:01.004",
            "extraData": "Lv.50|User2|KR"
        }    
}

Inquire the number of leaderboard users¶

Queries the total number of users registered on the leaderboard.

Request URL¶

Live URL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/count
Sandbox URL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/count
HTTP Method	GET
Content-Type	application/json

Path parameters¶

Field Name	Description	Type	Required
leaderboardId	Leaderboard ID	string	Y

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token required for API call (Bearer)	string	Y

Query parameters¶

Field Name	Description	Type	Required
requesttimeutc	Base time for inquiry (UTC+0), if not entered, the current time is the basis, format: `yyyy-MM-dd'T'HH:mm:ss.SSS`	string	N

Response¶

Field Name	Description	Type
count	Number of registered users	integer

Request sample¶

curl --location 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/players/count?requesttimeutc=2023-12-19T15%3A01%3A01.004'
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

Response sample¶

{
    "count": 3;
}