RoomScope

最後更新

排行榜

依榜單、地區與期間提供的官方排行榜。

所有操作都以 API 金鑰進行身分驗證 (Authorization: Bearer <key>) ;錯誤一律使用共通的錯誤格式,說明請見 錯誤. 本頁由 API 的 OpenAPI 文件產生。

取得榜單的每日門檻

GET/v1/rankings/day-bars

最近 days 天內每個榜單日的資料:榜單列出的創作者人數、榜上最低分數(進榜門檻)與最高分數(讀自 RoomScope 在每日重置前觀察到的最後一份完整榜單),以及當天讀取到的完整榜單份數。適用於 daily 與聯賽榜單(league_a1 至 league_d5)。

權限範圍rank:read點數快取讀取

查詢參數

查詢參數 · GET /v1/rankings/day-bars
NameTypeDescription
regionOptional
string地區代碼。
Default: VN
boardOptional
stringdaily 或聯賽榜單。
Default: daily
daysOptional
integer往回推算的天數。 範圍 …–90.
Default: 30

請求

curl "https://api.next.toktokdata.live/v1/rankings/day-bars" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

回應

200 OK
{  "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 會指出問題所在。
  • 401 API 金鑰缺少或不存在。
  • 402 工作區的點數錢包不足以支付此呼叫;resetAt 表示點數重置的時間。
  • 403 金鑰缺少該權限範圍,或方案未包含此功能。
  • 429 超過請求速率(每秒、每分鐘或每日);請遵守 Retry-After。

列出榜單的過往期間

GET/v1/rankings/history

單一榜單已結束的期間,由新到舊排列,範圍限於方案的歷史紀錄期間內。

權限範圍rank:read點數快取讀取

查詢參數

查詢參數 · GET /v1/rankings/history
NameTypeDescription
boardRequired
string榜單鍵值:daily、hourly、popular_live、gaming_daily、gaming_weekly、shopping_daily、shopping_weekly(需要 shop:read),或聯賽榜單 league_a1 … league_d5。
regionOptional
stringISO 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"

回應

200 OK
{  "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 會指出問題所在。
  • 401 API 金鑰缺少或不存在。
  • 402 工作區的點數錢包不足以支付此呼叫;resetAt 表示點數重置的時間。
  • 403 金鑰缺少該權限範圍,或方案未包含此功能。
  • 429 超過請求速率(每秒、每分鐘或每日);請遵守 Retry-After。

取得遮罩列的 LIVE 總計

GET/v1/rankings/masked/{ref}

依榜單回傳的 maskedRef,取得遮罩榜單列近 30 天的 LIVE 總計:場次、直播秒數與平均峰值觀眾數。絕不包含創作者身分,也不包含可與具名列比對的每日或每場序列。ref 只在收到它的工作區有效,每次讀取榜單都會產生新的 ref。

權限範圍rank:read點數快取讀取

路徑參數

路徑參數 · GET /v1/rankings/masked/{ref}
NameTypeDescription
refRequired
string遮罩榜單列的 maskedRef。

請求

curl "https://api.next.toktokdata.live/v1/rankings/masked/ref" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

回應

200 OK
{  "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 會指出問題所在。
  • 401 API 金鑰缺少或不存在。
  • 402 工作區的點數錢包不足以支付此呼叫;resetAt 表示點數重置的時間。
  • 403 金鑰缺少該權限範圍,或方案未包含此功能。
  • 429 超過請求速率(每秒、每分鐘或每日);請遵守 Retry-After。

取得官方榜單

GET/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。

權限範圍rank:read點數快取讀取

查詢參數

查詢參數 · GET /v1/rankings/official
NameTypeDescription
boardRequired
string榜單鍵值:daily、hourly、popular_live、gaming_daily、gaming_weekly、shopping_daily、shopping_weekly(需要 shop:read),或聯賽榜單 league_a1 … league_d5。
regionOptional
stringISO 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"

回應

200 OK
{  "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 會指出問題所在。
  • 401 API 金鑰缺少或不存在。
  • 402 工作區的點數錢包不足以支付此呼叫;resetAt 表示點數重置的時間。
  • 403 金鑰缺少該權限範圍,或方案未包含此功能。
  • 429 超過請求速率(每秒、每分鐘或每日);請遵守 Retry-After。

列出支援地區

GET/v1/rankings/regions

目前有已觀測榜單的地區,附顯示用標籤。請快取一天。

權限範圍rank:read點數快取讀取

請求

curl "https://api.next.toktokdata.live/v1/rankings/regions" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

回應

200 OK
{  "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 會指出問題所在。
  • 401 API 金鑰缺少或不存在。
  • 402 工作區的點數錢包不足以支付此呼叫;resetAt 表示點數重置的時間。
  • 403 金鑰缺少該權限範圍,或方案未包含此功能。
  • 429 超過請求速率(每秒、每分鐘或每日);請遵守 Retry-After。
這個頁面對你有幫助嗎?