리더보드 API
사전 준비
리더보드 API를 사용하려면 다음 항목이 준비되어야 합니다.
- Client ID와 Client Secret 발급: 보안키 설정에서 발급합니다.
- API 호출을 위한 Access Token(JWT) 발급: 위 1에서 발급한 Client ID와 Client Secret으로 OAuth Token 발급하기 API를 호출합니다. Access Token의 유효 기간은 1시간입니다.
- 사용할 리더보드 ID 확인: Hive 콘솔 > 리더보드 > 랭킹 관리
Note
리더보드 API는 JWT 인증 방식으로 동작합니다. 모든 API 요청 헤더인 X-Access-Token에 Access Token을 반드시 포함해야 합니다.
Request URL
| 서버 | URL |
| LIVE | api-leaderboard.withhive.com |
| SANDBOX | sandbox-api-leaderboard.withhive.com |
공통 응답
모든 API 응답에는 JWT 검증 결과인 token_validation 필드가 포함됩니다.
| 필드명 | 설명 | 타입 |
| token_validation | JWT 검증 결과 | json |
| token_validation.result_code | JWT 검증 결과 코드 (0 = 성공, 상세는 JWT 검증 오류 코드 참고) | integer |
| token_validation.result_msg | JWT 검증 결과 메시지 | string |
JWT 검증 실패 예시
{
"reason": "Access Token 만료",
"token_validation": {
"result_code": 2408,
"result_msg": "The access token is expired. Please refresh your token."
}
}
Response codes
API 공통 응답 코드입니다.
| 코드 | 값 | 설명 |
| 200 | 성공 | - |
| 400 | Bad Request | 잘못된 leaderboardId 혹은 Param 입력, 또는 Access Token에 해당하는 OAuth Client 정보가 없음(token_validation.result_code: 2400) |
| 401 | Unauthorized | Access Token 형식 오류(2405), 요청 헤더의 X-Access-Token 누락(2406), 서명 오류(2407), 만료(2408), 또는 Grant Type 불일치(2410) |
| 403 | Forbidden | Access Token을 발급받은 게임의 리더보드가 아님 |
| 500 | Internal Server Error | 서버 내부적으로 문제가 발생함 |
Note
JWT 검증에 실패하면 token_validation 필드로 상세한 오류 정보를 확인할 수 있습니다. 자세한 내용은 JWT 검증 오류 코드를 참고하세요.
리더보드에 점수를 저장합니다.
Request URL
Path parameters
| 필드명 | 설명 | 타입 | 필수 여부 |
| leaderboardId | 리더보드 ID | string | Y |
| 필드명 | 설명 | 타입 | 필수 여부 |
| X-Access-Token | 앱 서버 인증을 위한 OAuth 2.0 Access Token
(OAuth Token 발급하기 참고) | 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에는 공통 응답의 token_validation만 포함됩니다.
Request sample
curl --location 'https://sandbox-api-leaderboard.withhive.com/v2/leaderboards/1/score'
--header 'Content-Type: application/json'
--header 'X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...'
--data '{
"playerId": 1000,
"score": 87,
"achievementTimeUtc": "2023-12-19T15:01:01.004",
"extraData": "Lv.14|유저1|KR"
}'
Response sample
{
"token_validation": {
"result_code": 0,
"result_msg": "success"
}
}
점수 삭제
리더보드에 등록한 사용자 정보를 삭제합니다.
Request URL
Path parameters
| 필드명 | 설명 | 타입 | 필수 여부 |
| leaderboardId | 리더보드 ID | string | Y |
| playerId | 계정 식별자 | string | Y |
| 필드명 | 설명 | 타입 | 필수 여부 |
| X-Access-Token | 앱 서버 인증을 위한 OAuth 2.0 Access Token
(OAuth Token 발급하기 참고) | string | Y |
Response
200 OK인 경우, Body에는 공통 응답의 token_validation만 포함됩니다.
Request sample
curl --location
--request DELETE 'https://sandbox-api-leaderboard.withhive.com/v2/leaderboards/1/players/1004'
--header 'X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...'
--data ''
Response sample
{
"token_validation": {
"result_code": 0,
"result_msg": "success"
}
}
랭킹 조회: 페이지 단위 조회
상위 랭킹부터 페이지 단위로 조회합니다.
Request URL
Path parameters
| 필드명 | 설명 | 타입 | 필수 여부 |
| leaderboardId | 리더보드 ID | string | Y |
| 필드명 | 설명 | 타입 | 필수 여부 |
| X-Access-Token | 앱 서버 인증을 위한 OAuth 2.0 Access Token
(OAuth Token 발급하기 참고) | 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 |
| token_validation | JWT 검증 결과 (공통 응답 참고) | json |
Request sample
curl --location 'https://sandbox-api-leaderboard.withhive.com/v2/leaderboards/1/ranks?page=1&rowcount=100&playerid=1000&requesttimeutc=2023-12-19T15%3A01%3A01.004'
--header 'X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...'
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"
},
"token_validation": {
"result_code": 0,
"result_msg": "success"
}
}
Query Parameter에 playerid를 입력하지 않았다면, 결과값에 playerRank 자체를 받지 않습니다. 입력했더라도 해당 계정의 랭킹 정보가 존재하지 않는다면, playerRank는 아래와 같은 형식으로 반환됩니다.
랭킹 조회: 특정 사용자 랭킹 정보 조회
특정 사용자 랭킹 정보를 조회합니다.
Request URL
Path parameters
| 필드명 | 설명 | 타입 | 필수 여부 |
| leaderboardId | 리더보드 ID | string | Y |
| playerId | 계정 식별자 | string | Y |
| 필드명 | 설명 | 타입 | 필수 여부 |
| X-Access-Token | 앱 서버 인증을 위한 OAuth 2.0 Access Token
(OAuth Token 발급하기 참고) | 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 |
| token_validation | JWT 검증 결과 (공통 응답 참고) | json |
Request sample
curl --location 'https://sandbox-api-leaderboard.withhive.com/v2/leaderboards/1/players/1000/ranks?requesttimeutc=2023-12-19T15%3A01%3A01.004'
--header 'X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...'
Response sample
{
"playerRank": {
"rank": 2,
"playerId": 1000,
"score": 87,
"achievementTimeUtc": "2023-12-19T15:01:01.004",
"extraData": "Lv.50|유저14|KR"
},
"token_validation": {
"result_code": 0,
"result_msg": "success"
}
}
랭킹 조회: 특정 사용자 주변 랭킹 정보 조회
특정 사용자 주변의 랭킹 정보를 조회합니다. 특정 사용자를 기준으로 상위 50명 또는 하위 50명에 해당하는 랭킹 정보를 얻을 수 있습니다.
Request URL
Path parameters
| 필드명 | 설명 | 타입 | 필수 여부 |
| leaderboardId | 리더보드 ID | string | Y |
| playerId | 계정 식별자 | string | Y |
| 필드명 | 설명 | 타입 | 필수 여부 |
| X-Access-Token | 앱 서버 인증을 위한 OAuth 2.0 Access Token
(OAuth Token 발급하기 참고) | 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 |
| token_validation | JWT 검증 결과 (공통 응답 참고) | json |
Request sample
curl --location 'https://sandbox-api-leaderboard.withhive.com/v2/leaderboards/1/players/1000/ranks?nearby=100&requesttimeutc=2023-12-19T15%3A01%3A01.004'
--header 'X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...'
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"
},
"token_validation": {
"result_code": 0,
"result_msg": "success"
}
}
리더보드 사용자 수 조회
리더보드에 등록된 사용자 전체 수를 조회합니다.
Request URL
Path Parameters
| 필드명 | 설명 | 타입 | 필수 여부 |
| leaderboardId | 리더보드 ID | string | Y |
| 필드명 | 설명 | 타입 | 필수 여부 |
| X-Access-Token | 앱 서버 인증을 위한 OAuth 2.0 Access Token
(OAuth Token 발급하기 참고) | string | Y |
Query parameters
| 필드명 | 설명 | 타입 | 필수 여부 |
| requesttimeutc | 조회 기준 시간(UTC+0 기준), 입력이 없을 경우 현재 시간 기준, yyyy-MM-dd'T'HH:mm:ss.SSS 형식 | string | N |
Response
| 필드명 | 설명 | 타입 |
| count | 등록된 사용자의 수 | integer |
| token_validation | JWT 검증 결과 (공통 응답 참고) | json |
Request sample
curl --location 'https://sandbox-api-leaderboard.withhive.com/v2/leaderboards/1/players/count?requesttimeutc=2023-12-19T15%3A01%3A01.004'
--header 'X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...'
Response sample
{
"count": 3,
"token_validation": {
"result_code": 0,
"result_msg": "success"
}
}