Leaderbaord 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
Path parameters
Field Name | Description | Type | Required |
leaderboardId | Leaderboard ID | string | Y |
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"
}'
Deletes user information registered on the leaderboard.
Request URL
Path parameters
Field Name | Description | Type | Required |
leaderboardId | Leaderboard ID | string | Y |
playerId | Account identifier | string | Y |
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 tanking: Page-wise inquiry
Queries the rankings from the top, page by page.
Request URL
Path parameters
Field Name | Description | Type | Required |
leaderboardId | Leaderboard ID | string | Y |
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:
Queries ranking information for a specific user.
Request URL
Path parameters
Field Name | Description | Type | Required |
leaderboardId | Leaderboard ID | string | Y |
playerId | Account identifier | string | Y |
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"
}
}
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
Path Parameters
Field Name | Description | Type | Required |
leaderboardId | Leaderboard ID | string | Y |
playerId | Account identifier | string | Y |
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
Path parameters
Field Name | Description | Type | Required |
leaderboardId | Leaderboard ID | string | Y |
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