最終更新
ランキング
ランキングの種類、地域、期間ごとの公式ランキング。
すべての操作は API キーで認証します (Authorization: Bearer <key>) 。エラーには共通のエンベロープを使用します。詳しくは次のページを参照してください: エラー. このページは API の OpenAPI ドキュメントから生成しています。
ランキングの日次ボーダーを取得
/v1/rankings/day-bars直近 days 日間のランキングの各日について、ランキングに載ったクリエイター数、最低スコア(ランキング入りのボーダー)と最高スコア(RoomScope が日次リセット前に観測した最後の完全なランキングから読み取り)、およびその日に読み取った完全なランキングの数。daily とリーグランキング(league_a1 〜 league_d5)が対象です。
クエリパラメーター
| Name | Type | Description |
|---|---|---|
regionOptional | string | 地域コード。 Default: VN |
boardOptional | string | daily またはリーグランキング。Default: daily |
daysOptional | integer | さかのぼる日数。 範囲 …–90. Default: 30 |
リクエスト
curl "https://api.next.toktokdata.live/v1/rankings/day-bars" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"レスポンス
{ "data": { "region": "VN", "board": "daily", "days": [ { "boardDay": "2026-11-06", "dayEnd": "2026-11-06T17:00:00.000Z", "leagueClass": null, "entryCount": 99, "minScore": 23150, "maxScore": 880338, "boardCount": 12 } ] }, "provenance": { "observedAt": "2026-11-07T09:00:00.000Z", "freshness": "near_realtime", "source": "tiktok_observed_rank_board", "sourceKind": "official", "coverageStatus": "observed", "methodologyVersion": "board-day-bar-v1", "window": { "from": "2026-10-09", "to": "2026-11-07", "label": "30d" } }}エラー
400パラメーターまたはボディが不正です。問題の内容はcodeで示されます。401API キーがないか、不明なキーです。402ワークスペースのクレジットウォレットでこの呼び出しをまかなえません。クレジットがリセットされる日時はresetAtで示されます。403キーに必要なスコープがないか、プランにその機能が含まれていません。429リクエストのレートを超えました(毎秒・毎分・毎日のいずれか)。Retry-Afterに従ってください。
ランキングの過去の期間を一覧表示
/v1/rankings/history1 つのランキングの完了した期間を、プランの履歴保持期間の範囲内で新しい順に返します。
クエリパラメーター
| Name | Type | Description |
|---|---|---|
boardRequired | string | ランキングのキー:daily、hourly、popular_live、gaming_daily、gaming_weekly、shopping_daily、shopping_weekly(shop:read が必要)、またはリーグランキング league_a1 … league_d5。 |
regionOptional | string | ISO 3166-1 alpha-2 の地域コード。 Default: VN |
cursorOptional | string | 前のページの nextCursor から得た不透明なカーソル。 |
limitOptional | integer | 1 ページあたりの期間数。 範囲 1–24. Default: 24 |
leagueTierOptional | string | リーグのティアで絞り込み(A1 … D5)。 |
リクエスト
curl "https://api.next.toktokdata.live/v1/rankings/history?board=daily" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"レスポンス
{ "data": { "board": "daily", "region": "VN", "periods": [ { "periodKey": "2026-10-31", "observedAt": "2026-11-01T10:46:44.935Z", "coverageStatus": "observed", "publishable": true, "entries": [ { "rank": 1, "creatorUid": "990000000000000001", "uniqueId": "linh.live", "nickname": "Linh Live", "avatarUrl": null, "isLive": false, "roomId": null, "score": 99000, "leagueClass": null, "leagueClassSource": null, "leagueClassAsOf": null, "movement": "same", "previousRank": null, "masked": false, "unmaskTier": null }, { "rank": 2, "creatorUid": "990000000000000102", "uniqueId": "creator.02", "nickname": "Creator 02", "avatarUrl": null, "isLive": false, "roomId": null, "score": 98000, "leagueClass": null, "leagueClassSource": null, "leagueClassAsOf": null, "movement": "same", "previousRank": null, "masked": false, "unmaskTier": null } ] } ], "nextCursor": null, "hasMore": false, "historyWindowDays": 365, "historyTruncated": false }, "provenance": { "observedAt": "2026-11-01T10:46:44.935Z", "freshness": "historical", "source": "tiktok_observed_rank_board", "sourceKind": "official", "coverageStatus": "observed", "methodologyVersion": "rankings-official-v1", "window": null }}エラー
400パラメーターまたはボディが不正です。問題の内容はcodeで示されます。401API キーがないか、不明なキーです。402ワークスペースのクレジットウォレットでこの呼び出しをまかなえません。クレジットがリセットされる日時はresetAtで示されます。403キーに必要なスコープがないか、プランにその機能が含まれていません。429リクエストのレートを超えました(毎秒・毎分・毎日のいずれか)。Retry-Afterに従ってください。
マスクされた行の LIVE 合計を取得
/v1/rankings/masked/{ref}ランキングが返した maskedRef で、マスクされた行の過去 30 日間の LIVE 合計(セッション数、配信秒数、平均ピーク視聴者数)を返します。クリエイターの身元は含まれず、名前のある行と照合できる日別・セッション別の系列も含まれません。ref はそれを受け取ったワークスペースでのみ使え、ランキングを読むたびに新しい ref が発行されます。
パスパラメーター
| Name | Type | Description |
|---|---|---|
refRequired | string | マスクされた行の maskedRef。 |
リクエスト
curl "https://api.next.toktokdata.live/v1/rankings/masked/ref" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"レスポンス
{ "data": { "sessionsSummary": { "sessions": 6, "liveSeconds": 31400, "averagePeakViewers": 1640 } }, "provenance": { "observedAt": "2026-11-02T13:05:11.000Z", "freshness": "historical", "source": "creator_analytics", "sourceKind": "derived", "coverageStatus": "partial", "methodologyVersion": "masked-creator-v3", "window": { "from": "2026-10-04T08:00:00.000Z", "to": "2026-11-03T08:00:00.000Z", "label": "30d" } }}エラー
400パラメーターまたはボディが不正です。問題の内容はcodeで示されます。401API キーがないか、不明なキーです。402ワークスペースのクレジットウォレットでこの呼び出しをまかなえません。クレジットがリセットされる日時はresetAtで示されます。403キーに必要なスコープがないか、プランにその機能が含まれていません。429リクエストのレートを超えました(毎秒・毎分・毎日のいずれか)。Retry-Afterに従ってください。
公式ランキングを取得
/v1/rankings/official1 つの地域の 1 つのランキングを、TikTok が公開しているとおりに返します。ランキングはカバー率が基準を満たした後にのみ再現されます。エントリーを表示する前に publishable と coverage を確認してください。プランで名前を表示できる範囲を超えるエントリーは、rank と score は保持したまま masked: true で返され、身元情報は含まれず(creatorUid、avatarUrl、roomId は null)、名前を表示できるプランが unmaskTier に入ります。maskedRef を使うと /v1/rankings/masked/{ref} で LIVE 合計を読めます。マスクされたエントリーは movement、previousRank、sparkline も null です。これらは以前の位置を示してしまうためです。現在の期間では、それ以外のすべてのエントリーに sparkline が付きます。これは直近 7 つの完了した期間それぞれのスコアで、古い順に並び、ランキングに入っていなかった期間は null です。
クエリパラメーター
| Name | Type | Description |
|---|---|---|
boardRequired | string | ランキングのキー:daily、hourly、popular_live、gaming_daily、gaming_weekly、shopping_daily、shopping_weekly(shop:read が必要)、またはリーグランキング league_a1 … league_d5。 |
regionOptional | string | ISO 3166-1 alpha-2 の地域コード。 Default: VN |
periodOptional | "current" | "history" | current は進行中の期間、history は直近の完了した期間です。Default: current |
limitOptional | integer | 最大エントリー数。 範囲 1–200. Default: 200 |
liveOnlyOptional | "true" | "false" | 現在配信中のクリエイターのみ。 Default: false |
leagueTierOptional | string | リーグのティアで絞り込み(A1 … D5)。 |
リクエスト
curl "https://api.next.toktokdata.live/v1/rankings/official?board=daily" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"レスポンス
{ "data": { "board": { "kind": "official", "board": "daily", "region": "VN", "periodKey": "2026-10-31", "resetAt": null, "publishable": true, "coverage": { "completeBoards": 1, "expectedBoards": 22, "ratio": 0.045454545454545456, "threshold": 0.8 }, "entries": [ { "rank": 1, "creatorUid": "990000000000000001", "uniqueId": "linh.live", "nickname": "Linh Live", "avatarUrl": null, "isLive": true, "roomId": "7990000000000000001", "score": 99000, "leagueClass": null, "leagueClassSource": null, "leagueClassAsOf": null, "movement": "new", "previousRank": null, "masked": false, "unmaskTier": null, "sparkline": [ null, 812000, 846500, 901200, 955000, 1010300, 99000 ] }, { "rank": 2, "creatorUid": "990000000000000102", "uniqueId": "creator.02", "nickname": "Creator 02", "avatarUrl": null, "isLive": false, "roomId": null, "score": 98000, "leagueClass": null, "leagueClassSource": null, "leagueClassAsOf": null, "movement": "new", "previousRank": null, "masked": false, "unmaskTier": null, "sparkline": [ null, 803880, 838035, 892188, 945450, 1000197, 97020 ] } ] } }, "provenance": { "observedAt": "2026-11-01T10:46:44.935Z", "freshness": "historical", "source": "tiktok_observed_rank_board", "sourceKind": "official", "coverageStatus": "observed", "methodologyVersion": "rankings-official-v1", "window": { "from": null, "to": null, "label": "daily" } }}エラー
400パラメーターまたはボディが不正です。問題の内容はcodeで示されます。401API キーがないか、不明なキーです。402ワークスペースのクレジットウォレットでこの呼び出しをまかなえません。クレジットがリセットされる日時はresetAtで示されます。403キーに必要なスコープがないか、プランにその機能が含まれていません。429リクエストのレートを超えました(毎秒・毎分・毎日のいずれか)。Retry-Afterに従ってください。
対応地域を一覧表示
/v1/rankings/regions観測済みのランキングが現在ある地域を、表示用のラベル付きで返します。1 日キャッシュしてください。
リクエスト
curl "https://api.next.toktokdata.live/v1/rankings/regions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"レスポンス
{ "data": { "regions": [ { "region": "VN", "label": "VN · Vietnam", "coverage": { "completeBoards": 1, "expectedBoards": 22, "ratio": 0.045454545454545456, "threshold": 0.8 }, "boards": [ "daily" ], "notOfferedBoards": [] } ] }, "provenance": { "observedAt": "2026-11-01T10:46:44.935Z", "freshness": "historical", "source": "tiktok_observed_rank_board", "sourceKind": "official", "coverageStatus": "observed", "methodologyVersion": "rankings-official-v1", "window": null }}エラー
400パラメーターまたはボディが不正です。問題の内容はcodeで示されます。401API キーがないか、不明なキーです。402ワークスペースのクレジットウォレットでこの呼び出しをまかなえません。クレジットがリセットされる日時はresetAtで示されます。403キーに必要なスコープがないか、プランにその機能が含まれていません。429リクエストのレートを超えました(毎秒・毎分・毎日のいずれか)。Retry-Afterに従ってください。