Leaderboard API

사전 준비¶

리더보드 API를 사용하려면 다음 항목이 준비되어야 합니다.

API 호출을 위한 인증 토큰(Hive Certification Key): Hive 콘솔 > 앱센터 > 프로젝트 관리 > 게임 상세 > 기본 정보 > Hive 인증키
사용할 리더보드 ID : Hive 콘솔 > 리더보드 > 랭킹 관리

Request URL¶

서버	URL
LIVE	api-leaderboard.withhive.com
SANDBOX	sandbox-api-leaderboard.withhive.com

Response codes¶

API 공통 응답코드입니다.

코드	값	설명
200	성공	-
400	Bad Request	잘못된 `leaderboardId` 혹은 Param 입력
401	Unauthorized	요청 메시지의 Authorization 헤더가 누락되었거나 그 값이 유효하지 않음
403	Forbidden	API 호출을 위한 인증 토큰(Hive Certification Key)이 유효하지 않음
500	Internal Server Error	서버 내부적으로 문제가 발생함

점수 입력¶

리더보드에 점수를 저장합니다.

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¶

필드명	설명	타입	필수 여부
leaderboardId	리더보드 ID	string	Y

Header parameters¶

필드명	설명	타입	필수 여부
Authorization	API 호출을 위한 인증 토큰 (Bearer)	string	Y

Request body¶

필드명	설명	타입	필수 여부
playerId	계정 식별자	long	Y
score	랭킹에 등록할 점수입니다. 최대 15자리(999,999,999,999,999)까지 입력 가능합니다.	integer	Y
achievementTimeUtc	점수 발생 시간(UTC+0 기준)입니다. `yyyy-MM-dd'T'HH:mm:ss.SSS` 형식입니다.	string	Y
extraData	계정 부가 정보(닉네임, 레벨, 국가 등)입니다. 최대 256자까지 입력 가능합니다.	string	N

Response¶

200 OK인 경우, Body는 비어있습니다.

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|유저1|KR"
}'

점수 삭제¶

리더보드에 등록한 유저 정보를 삭제합니다.

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¶

필드명	설명	타입	필수 여부
leaderboardId	리더보드 ID	string	Y
playerId	계정 식별자	string	Y

Header parameters¶

필드명	설명	타입	필수 여부
Authorization	API 호출을 위한 인증 토큰 (Bearer)	string	Y

Response¶

200 OK인 경우, Body는 비어있습니다.

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

랭킹 조회: 페이지 단위 조회¶

상위 랭킹부터 페이지 단위로 조회합니다.

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¶

필드명	설명	타입	필수 여부
leaderboardId	리더보드 ID	string	Y

Header parameters¶

필드명	설명	타입	필수 여부
Authorization	API 호출을 위한 인증 토큰 (Bearer)	string	Y

Query parameters¶

필드명	설명	타입	필수 여부
page	요청 페이지 번호입니다. 1부터 시작하며 기본값은 1입니다. 값이 5이면 5페이지 내용만 조회합니다.	integer	N
rowcount	페이지당 표시할 랭킹 정보 수입니다. 최대 100건이며 기본값은 100입니다.	integer	N
requesttimeutc	조회 기준 시간(UTC+0 기준)입니다. 기본값은 현재 시간입니다. `yyyy-MM-dd'T'HH:mm:ss.SSS` 형식입니다.	string	N
playerid	`playerid` 계정의 랭킹 정보가 존재한다면, 해당 플레이어 랭킹 정보도 함께 조회	long	N

Response¶

필드명	설명	타입
rankingList	랭킹 데이터 목록	json array
rankingList[].rank	순위	integer
rankingList[].playerId	계정 식별자	long
rankingList[].score	점수	long
rankingList[].achievementTimeUtc	점수를 등록한 시간(UTC+0 기준)입니다. `yyyy-MM-dd'T'HH:mm:ss.SSS` 형식입니다.	string
rankingList[].extraData	계정 부가 정보(닉네임, 레벨, 국가 등)	string
playerRank	Query Parameter에 입력한 `playerid` 유저 랭킹 정보(Query Parameter에 `playerid` 정보가 있을 경우에만 이 값을 반환함)	json
playerRank.rank	순위	integer
playerRank.playerId	계정 식별자	long
playerRank.score	점수	long
playerRank.achievementTimeUtc	점수가 등록된 시간(UTC+0 기준), `yyyy-MM-dd'T'HH:mm:ss.SSS` 형식	string
playerRank.extraData	계정 부가 정보(닉네임, 레벨, 국가 등)	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|유저1|KR"
        }, {
            "rank": 2,
            "playerId": 1000,
            "score": 87,
            "achievementTimeUtc": "2023-12-19T15:01:01.004",
            "extraData": "Lv.50|유저14|KR"
        }
    ],
    "playerRank": {
        "rank": 2,
        "playerId": 1000,
        "score": 87,
        "achievementTimeUtc": "2023-12-19T15:01:01.004",
       "extraData": "Lv.50|유저14|KR"
    }
}

Query Parameter에 playerid를 입력하지 않았다면, 결과값에 playerRank 자체를 받지 않습니다. 입력했더라도 해당 계정의 랭킹 정보가 존재하지 않는다면, playerRank는 아래와 같은 형식으로 반환됩니다.

"playerRank": null

랭킹 조회: 특정 유저 랭킹 정보 조회¶

특정 유저 랭킹 정보를 조회합니다.

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¶

필드명	설명	타입	필수 여부
leaderboardId	리더보드 ID	string	Y
playerId	계정 식별자	string	Y

Header parameters¶

필드명	설명	타입	필수 여부
Authorization	API 호출을 위한 인증 토큰 (Bearer)	string	Y

Query parameters¶

필드명	설명	타입	필수 여부
requesttimeutc	조회 기준 시간(UTC+0 기준), `yyyy-MM-dd'T'HH:mm:ss.SSS` 형식	string	N

Response¶

필드명	설명	타입
playerRank.rank	순위	integer
playerRank.playerId	계정 식별자	long
playerRank.score	점수	long
playerRank.achievementTimeUtc	점수가 등록된 시간(UTC+0 기준), `yyyy-MM-dd'T'HH:mm:ss.SSS` 형식	string
playerRank.extraData	계정 부가 정보(닉네임, 레벨, 국가 등)	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|유저14|KR"
    }
}

랭킹 조회: 특정 유저 주변 랭킹 정보 조회¶

특정 유저 주변의 랭킹 정보를 조회합니다. 특정 유저를 기준으로 상위 50명 또는 하위 50명에 해당하는 랭킹 정보를 얻을 수 있습니다.

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¶

필드명	설명	타입	필수 여부
leaderboardId	리더보드 ID	string	Y
playerId	계정 식별자	string	Y

Header parameters¶

필드명	설명	타입	필수 여부
Authorization	API 호출을 위한 인증 토큰 (Bearer)	string	Y

Query parameters¶

필드명	설명	타입	필수 여부
nearby	`playerId` 주변 랭킹 수입니다. 최대 100개입니다.	integer	Y
requesttimeutc	조회 기준 시간 (UTC+0 기준), `yyyy-MM-dd'T'HH:mm:ss.SSS` 형식	string	N

Response¶

필드명	설명	타입
rankingList	랭킹 데이터 목록	json array
rankingList[].rank	순위	integer
rankingList[].playerId	계정 식별자	long
rankingList[].score	점수	long
rankingList[].achievementTimeUtc	점수가 등록된 시간 (UTC+0 기준), `yyyy-MM-dd'T'HH:mm:ss.SSS` 형식	string
rankingList[].extraData	계정 부가 정보(닉네임, 레벨, 국가 등)	string
playerRank	Path Parameter에 입력한 `playerid` 유저 랭킹 정보	json
playerRank.rank	순위	integer
playerRank.playerId	계정 식별자	long
playerRank.score	점수	long
playerRank.achievementTimeUtc	점수가 등록된 시간 (UTC+0 기준), `yyyy-MM-dd'T'HH:mm:ss.SSS` 형식	string
playerRank.extraData	계정 부가 정보(닉네임, 레벨, 국가 등)	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|유저1|KR"
        }, {
            "rank": 2,
            "playerId": 1000,
            "score": 87,
            "achievementTimeUtc": "2023-12-19T15:01:01.004",
            "extraData": "Lv.50|유저2|KR"
        }, {
            "rank": 3,
            "playerId": 1002,
            "score": 70,
            "achievementTimeUtc": "2023-12-19T15:02:02.004",
            "extraData": "Lv.50|유저3|KR"
        }
    ],
    "playerRank": {
        "rank": 2,
        "playerId": 1000,
        "score": 87,
        "achievementTimeUtc": "2023-12-19T15:01:01.004",
        "extraData": "Lv.50|유저2|KR"
    }    
}

리더보드 사용자 수 조회¶

리더보드에 등록된 사용자 전체 수를 조회합니다.

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¶

필드명	설명	타입	필수 여부
leaderboardId	리더보드 ID	string	Y

Header parameters¶

필드명	설명	타입	필수 여부
Authorization	API 호출을 위한 인증 토큰 (Bearer)	string	Y

Query parameters¶

필드명	설명	타입	필수 여부
requesttimeutc	조회 기준 시간 (UTC+0 기준), 입력이 없을 경우 현재 시간 기준, `yyyy-MM-dd'T'HH:mm:ss.SSS` 형식	string	N

Response¶

필드명	설명	타입
count	등록된 유저의 수	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;
}