Pre-requisites

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

Authentication Token (Hive Certification Key) for API calls: Hive Console > App Center > Manage Project > Game Details > Basic Info > Hive 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 (Hive 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"
}'

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 ''

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'

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"
    }
}

{

"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

"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'

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"
    }
}

{

"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'

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"
        }    
}

{

"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'

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;
}

{

"count": 3;

}

Leaderboard API

Pre-requisites

Request URL

Response Codes

Submit Score

Request URL

Path Parameters

Header Parameters

Request Body

Response

Request Sample

Delete Score (Delete User Information)

Request URL

Path Parameters

Header Parameters

Response

Request Sample

Inquire Ranking: Page-wise Inquiry

Request URL

Path Parameters

Header Parameters

Query Parameters

Response

Request Sample

Response Sample

Inquire Ranking: Inquire Specific User Ranking Information

Request URL

Path Parameters

Header Parameters

Query Parameters

Response

Request Sample

Response Sample

Inquire Ranking: Information of Ranking Around a Specific User

Request URL

Path Parameters

Header Parameters

Query Parameters

Response

Request Sample

Response Sample

Inquire the Number of Leaderboard Users

Request URL

Path Parameters

Header Parameters

Query Parameters

Response

Request Sample

Response Sample

Getting Started

Console Guide

Download

API Document

Support