最終更新 2026年11月1日

クイックスタート

キーを作成し、エンドポイントを呼び出し、出典情報を読み取る。必要なのはこの 3 ステップだけです。すべてのリクエストは、ダッシュボードと共通のワークスペースのクレジットウォレットから計量されます。

前提条件

RoomScope のワークスペース。お持ちでない場合は無料で始めるから作成してください。Free プランでも API からキャッシュ済みのランキングを読み取れます。
キーを管理できるロール（keys:manage）。ワークスペースのオーナーにはデフォルトで付与されています。

1. API キーを作成する

ダッシュボードで 設定 → API キー → キーを作成 を開き、名前を付けて必要なスコープを選びます。シークレットが表示されるのは一度だけです。シークレットマネージャーに保存してください。以降はキーのプレフィックスしか表示されません。

キーはサーバー側で保管する

キーをブラウザのバンドルやモバイルアプリに含めないでください。バックエンドのプロキシを用意し、そのプロキシに必要なスコープだけをキーに付与します（たとえばランキングなら rank:read）。

2. 最初のリクエストを送る

ベトナムの本日の公式デイリーランキングを取得します。先に環境変数 ROOMSCOPE_API_KEY を設定しておいてください。

curl "https://api.toktokdata.live/v1/rankings/official?board=daily&region=VN&period=current&limit=10" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY" \  -H "Accept: application/json"

3. レスポンスを読む

成功したレスポンスには必ず data オブジェクトと provenance オブジェクトが含まれます。provenance（出典）は、シグナルがいつ観測されたか、カバー率がどこまで揃っていたかを示します。メタデータではなく、結果の一部として扱ってください。

200 OK

{  "data": {    "board": {      "publishable": true,      "periodKey": "2026-11-01",      "resetAt": "2026-11-02T00:00:00Z",      "coverage": { "completeBoards": 24, "expectedBoards": 24 },      "entries": [        {          "rank": 1,          "creatorUid": "7123456789012345678",          "uniqueId": "room.one",          "nickname": "Room One",          "score": 2410000,          "isLive": true,          "leagueClass": null,          "movement": "same",          "masked": false,          "unmaskTier": null        }      ]    }  },  "provenance": { "coverageStatus": "observed", "observedAt": "2026-11-01T09:58:12Z" }}

ランキングがまだ公開可能でない場合（publishable: false）、エントリーの一覧は空になり、その理由を provenance.coverageStatus が示します。名前を伏せたエントリー（masked: true）には、名前を表示できるプランが unmaskTier に入っています。

次のステップ

認証：スコープ、ローテーション、401 と 403 の意味。
エラー：エラーエンベロープと、リトライすべきタイミング。
ランキングのリファレンス：GET /v1/rankings/official のすべてのパラメーター。

このページは役に立ちましたか？