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

Response

If 200 OK, the response body is empty.

Request Sample

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

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
rankingList List of ranking data
rankingList[].rank Rank
rankingList[].playerId Account identifier
rankingList[].score Score
rankingList[].achievementTimeUtc Time when the score was registered (based on UTC+0). Format: yyyy-MM-dd'T'HH:mm:ss.SSS
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)
playerRank.rank Rank
playerRank.playerId Account identifier
playerRank.score Score
playerRank.achievementTimeUtc Time when the score was registered (based on UTC+0), format: yyyy-MM-dd'T'HH:mm:ss.SSS

Request Sample

Response Sample

 

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:

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

Request Sample

Response Sample

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

Request Sample

Response Sample

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

Response Sample