最後更新
排行榜
依榜單、地區與期間提供的官方排行榜。
所有操作都以 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/history單一榜單已結束的期間,由新到舊排列,範圍限於方案的歷史紀錄期間內。
查詢參數
| 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–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/official依 TikTok 公布的樣子回傳某地區的一個榜單。榜單只有在覆蓋率通過門檻後才會重現:顯示項目前請先讀取 publishable 與 coverage。超出方案可揭露範圍的項目保留 rank 與 score,但以 masked: true 回傳,不含身分(creatorUid、avatarUrl 與 roomId 為 null),並附上可揭露它們的方案 unmaskTier;maskedRef 可透過 /v1/rankings/masked/{ref} 讀取其 LIVE 總計。遮罩項目的 movement、previousRank 與 sparkline 也為 null,因為它們會透露先前的位置。在目前期間,其他每個項目都帶有 sparkline:它在最近七個完整期間各自的分數,由舊到新,不在榜上的期間為 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目前有已觀測榜單的地區,附顯示用標籤。請快取一天。
請求
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。