リーダーボードAPI

前提条件¶

Leaderboard APIを使用するには、以下の項目を準備する必要があります：

API呼び出しのための認証トークン（認証キー）： Hive コンソール > アプリセンター > プロジェクト管理 > ゲーム詳細 > 基本情報 > 認証キー
使用するリーダーボードID： Hive コンソール > リーダーボード > ランキング管理

リクエストURL¶

サーバー	URL
LIVE	api-leaderboard.withhive.com
SANDBOX	sandbox-api-leaderboard.withhive.com

レスポンスコード¶

APIの一般的なレスポンスコード。

コード	値	説明
200	成功	-
400	不正なリクエスト	無効な `leaderboardId` またはパラメータ入力
401	認証されていない	リクエストメッセージのAuthorizationヘッダーが欠落しているか、その値が無効です
403	禁止されています	API呼び出しのための認証トークン（認証キー）が無効です
500	内部サーバーエラー	サーバー内の問題

スコアを送信¶

リーダーボードにスコアを保存します。

リクエストURL¶

ライブURL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/score
サンドボックスURL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/score
HTTPメソッド	POST
コンテンツタイプ	application/json

パスパラメータ¶

フィールド名	説明	タイプ	必須
leaderboardId	リーダーボードID	文字列	Y

ヘッダーパラメータ¶

フィールド名	説明	タイプ	必須
Authorization	APIを呼び出すための認証トークン（ベアラー）	文字列	Y

リクエストボディ¶

フィールド名	説明	タイプ	必須
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	playeridアカウントの追加情報（ニックネーム、レベル、国など）です。最大256文字を入力できます。	string	N

応答¶

200 OKの場合、レスポンスボディは空です。

リクエストサンプル¶

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

スコアを削除する（ユーザー情報を削除）¶

リーダーボードに登録されたユーザー情報を削除します。

リクエストURL¶

ライブURL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}
サンドボックスURL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}
HTTPメソッド	DELETE
コンテンツタイプ	application/json

パスパラメータ¶

フィールド名	説明	タイプ	必須
leaderboardId	リーダーボードID	文字列	Y
playerId	アカウント識別子	文字列	Y

ヘッダーパラメータ¶

フィールド名	説明	タイプ	必須
Authorization	APIを呼び出すための認証トークン (Bearer)	文字列	Y

応答¶

200 OKの場合、レスポンスボディは空です。

リクエストサンプル¶

curl --location
--request DELETE 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/players/1004'
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'
--data ''

タンキングの問い合わせ: ページごとの問い合わせ¶

上位からページごとにランキングを照会します。

リクエストURL¶

ライブURL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/ranks
サンドボックスURL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/ranks
HTTPメソッド	GET
コンテンツタイプ	application/json

パスパラメータ¶

フィールド名	説明	タイプ	必須
leaderboardId	リーダーボードID	文字列	Y

ヘッダーパラメータ¶

フィールド名	説明	タイプ	必須
Authorization	API呼び出しに必要な認証トークン（ベアラー）	文字列	Y

クエリパラメータ¶

フィールド名	説明	タイプ	必須
page	リクエストされたページ番号。1から始まり、デフォルトは1です。値が5の場合、ページ5の内容のみが照会されます。	整数	N
rowcount	ページごとに表示するランキング情報の数。最大100、デフォルトは100です。	整数	N
requesttimeutc	照会の基準時間（UTC+0に基づく）。デフォルトは現在の時間です。フォーマットは`yyyy-MM-dd'T'HH:mm:ss.SSS`です。	文字列	N
playerid	playeridアカウントのランキング情報が存在する場合、そのプレイヤーのランキング情報も照会します。	長整数	N

応答¶

フィールド名	説明	型
rankingList	ランキングデータのリスト	json 配列
rankingList[].rank	ランク	整数
rankingList[].playerId	アカウント識別子	長整数
rankingList[].score	スコア	長整数
rankingList[].achievementTimeUtc	スコアが登録された時間（UTC+0に基づく）。形式: `yyyy-MM-dd'T'HH:mm:ss.SSS`	文字列
rankingList[].extraData	playeridアカウントの追加情報（ニックネーム、レベル、国など）	文字列
playerRank	クエリパラメータに提供された`playerid`のユーザーのランキング情報（クエリパラメータに`playerid`情報が存在する場合のみ返される）	json
playerRank.rank	ランク	整数
playerRank.playerId	アカウント識別子	長整数
playerRank.score	スコア	長整数
playerRank.achievementTimeUtc	スコアが登録された時間（UTC+0に基づく）、形式: `yyyy-MM-dd'T'HH:mm:ss.SSS`	文字列
playerRank.extraData	playeridアカウントの追加情報（ニックネーム、レベル、国など）	文字列

リクエストサンプル¶

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'

レスポンスサンプル¶

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

クエリパラメータにplayeridが提供されていない場合、結果にはplayerRankが含まれません。提供されているが、アカウントのランキング情報がない場合、playerRankは次の形式で返されます:

"playerRank": null

ランキングを問い合わせる: 特定のユーザーのランキング情報を問い合わせる¶

特定のユーザーのクエリランキング情報を取得します。

リクエストURL¶

ライブURL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks
サンドボックスURL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks
HTTPメソッド	GET
コンテンツタイプ	application/json

パスパラメータ¶

フィールド名	説明	タイプ	必須
leaderboardId	リーダーボードID	文字列	Y
playerId	アカウント識別子	文字列	Y

ヘッダーパラメータ¶

フィールド名	説明	タイプ	必須
Authorization	API呼び出しに必要な認証トークン（ベアラー）	文字列	Y

クエリパラメータ¶

フィールド名	説明	タイプ	必須
requesttimeutc	問い合わせの基準時間（UTC+0に基づく）、形式: `yyyy-MM-dd'T'HH:mm:ss.SSS`	文字列	N

応答¶

フィールド名	説明	型
playerRank.rank	ランク	整数
playerRank.playerId	アカウント識別子	長整数
playerRank.score	スコア	長整数
playerRank.achievementTimeUtc	スコアが登録された時間（UTC+0に基づく）、形式: `yyyy-MM-dd'T'HH:mm:ss.SSS`	文字列
playerRank.extraData	playeridアカウントの追加情報（ニックネーム、レベル、国など）	文字列

リクエストサンプル¶

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'

応答サンプル¶

{
    "playerRank": {
        "rank": 2,
        "playerId": 1000,
        "score": 87,
        "achievementTimeUtc": "2023-12-19T15:01:01.004",
        "extraData": "Lv.50|User14|KR"
    }
}

ランキングの問い合わせ: 特定のユーザーに関するランキング情報¶

特定のユーザーに関するランキング情報を照会します。特定のユーザーの周りの上位50人または下位50人のユーザーに関するランキング情報を取得できます。

リクエストURL¶

ライブURL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks
サンドボックスURL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks
HTTPメソッド	GET
コンテンツタイプ	application/json

パスパラメータ¶

フィールド名	説明	タイプ	必須
leaderboardId	リーダーボードID	文字列	Y
playerId	アカウント識別子	文字列	Y

ヘッダーパラメータ¶

フィールド名	説明	タイプ	必須
Authorization	API呼び出しに必要な認証トークン（ベアラー）	文字列	Y

クエリパラメータ¶

フィールド名	説明	タイプ	必須
nearby	`playerId`の周りのランキングの数。最大100。	整数	Y
requesttimeutc	問い合わせの基準時間 (UTC+0)、フォーマット: `yyyy-MM-dd'T'HH:mm:ss.SSS`	文字列	N

応答¶

フィールド名	説明	タイプ
rankingList	ランキングデータのリスト	json 配列
rankingList[].rank	ランク	整数
rankingList[].playerId	アカウント識別子	長整数
rankingList[].score	スコア	長整数
rankingList[].achievementTimeUtc	スコアが登録された時間 (UTC+0)、形式: `yyyy-MM-dd'T'HH:mm:ss.SSS`	文字列
rankingList[].extraData	playerid アカウントの追加情報 (ニックネーム、レベル、国など)	文字列
playerRank	パスパラメータに入力された `playerid` のユーザーランキング情報	json
playerRank.rank	ランク	整数
playerRank.playerId	アカウント識別子	長整数
playerRank.score	スコア	長整数
playerRank.achievementTimeUtc	スコアが記録された時間 (UTC+0)、形式: `yyyy-MM-dd'T'HH:mm:ss.SSS`	文字列
playerRank.extraData	playerid アカウントの追加情報 (ニックネーム、レベル、国など)	文字列

リクエストサンプル¶

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'

応答サンプル¶

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

リーダーボードユーザーの数を問い合わせる¶

リーダーボードに登録されているユーザーの総数をクエリします。

リクエストURL¶

ライブURL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/count
サンドボックスURL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/count
HTTPメソッド	GET
コンテンツタイプ	application/json

パスパラメータ¶

フィールド名	説明	タイプ	必須
leaderboardId	リーダーボードID	文字列	Y

ヘッダーパラメータ¶

フィールド名	説明	タイプ	必須
Authorization	API呼び出しに必要な認証トークン（ベアラー）	文字列	Y

クエリパラメータ¶

フィールド名	説明	タイプ	必須
requesttimeutc	問い合わせの基準時間（UTC+0）。入力しない場合は現在の時間が基準となります。フォーマット: `yyyy-MM-dd'T'HH:mm:ss.SSS`	文字列	N

応答¶

フィールド名	説明	タイプ
count	登録ユーザーの数	整数

リクエストサンプル¶

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'

レスポンスサンプル¶

{
    "count": 3;
}