Cập nhật lần cuối
Bảng xếp hạng
Bảng xếp hạng chính thức theo bảng, khu vực và kỳ.
Mọi thao tác đều xác thực bằng API key (Authorization: Bearer <key>) và lỗi dùng chung envelope được mô tả trong Lỗi. Được tạo từ tài liệu OpenAPI của API.
Lấy ngưỡng hằng ngày của một bảng
/v1/rankings/day-barsVới mỗi ngày bảng trong days ngày gần nhất: số creator bảng liệt kê, điểm thấp nhất trên bảng (ngưỡng để lọt vào bảng) và điểm cao nhất, đọc từ bảng hoàn chỉnh cuối cùng RoomScope quan sát được trước khi bảng reset hằng ngày, cùng số bảng hoàn chỉnh đã đọc trong ngày đó. Áp dụng cho daily và các bảng league (league_a1 đến league_d5).
Tham số query
| Name | Type | Description |
|---|---|---|
regionOptional | string | Mã khu vực. Default: VN |
boardOptional | string | daily hoặc một bảng league.Default: daily |
daysOptional | integer | Số ngày lùi lại. Khoảng giá trị …–90. Default: 30 |
Request
curl "https://api.next.toktokdata.live/v1/rankings/day-bars" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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" } }}Lỗi
400Tham số hoặc body không hợp lệ;codecho biết vấn đề.401API key bị thiếu hoặc không xác định.402Ví credit của workspace không đủ cho lệnh gọi;resetAtcho biết khi nào credit được reset.403Key thiếu scope, hoặc gói không bao gồm tính năng này.429Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theoRetry-After.
Liệt kê các kỳ đã qua của một bảng
/v1/rankings/historyCác kỳ đã hoàn tất của một bảng, mới nhất trước, trong khoảng lịch sử của gói.
Tham số query
| Name | Type | Description |
|---|---|---|
boardRequired | string | Khóa của bảng: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly (cần shop:read), hoặc một bảng league từ league_a1 … league_d5. |
regionOptional | string | Mã khu vực ISO 3166-1 alpha-2. Default: VN |
cursorOptional | string | Cursor mờ lấy từ nextCursor của trang trước. |
limitOptional | integer | Số kỳ mỗi trang. Khoảng giá trị 1–24. Default: 24 |
leagueTierOptional | string | Lọc theo hạng league, A1 … D5. |
Request
curl "https://api.next.toktokdata.live/v1/rankings/history?board=daily" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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 }}Lỗi
400Tham số hoặc body không hợp lệ;codecho biết vấn đề.401API key bị thiếu hoặc không xác định.402Ví credit của workspace không đủ cho lệnh gọi;resetAtcho biết khi nào credit được reset.403Key thiếu scope, hoặc gói không bao gồm tính năng này.429Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theoRetry-After.
Lấy số tổng LIVE của một hàng bị che
/v1/rankings/masked/{ref}Số tổng LIVE trong 30 ngày của một hàng bị che trên bảng, theo maskedRef mà bảng trả về: số phiên, số giây live và người xem đỉnh trung bình. Không bao giờ có danh tính của creator, cũng không có chuỗi theo ngày hay theo phiên có thể so khớp với một hàng có tên. Một ref chỉ dùng được trong workspace đã nhận nó, và mỗi lần đọc bảng tạo ref mới.
Tham số path
| Name | Type | Description |
|---|---|---|
refRequired | string | maskedRef của một hàng bị che trên bảng. |
Request
curl "https://api.next.toktokdata.live/v1/rankings/masked/ref" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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" } }}Lỗi
400Tham số hoặc body không hợp lệ;codecho biết vấn đề.401API key bị thiếu hoặc không xác định.402Ví credit của workspace không đủ cho lệnh gọi;resetAtcho biết khi nào credit được reset.403Key thiếu scope, hoặc gói không bao gồm tính năng này.429Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theoRetry-After.
Lấy một bảng chính thức
/v1/rankings/officialMột bảng cho một khu vực, đúng như TikTok công bố. Bảng chỉ được tái hiện sau khi độ phủ vượt qua một ngưỡng: hãy đọc publishable và coverage trước khi hiển thị các entry. Những entry vượt quá phạm vi gói được hiện tên vẫn giữ rank và score nhưng được trả về với masked: true, không có danh tính (creatorUid, avatarUrl và roomId là null), kèm unmaskTier là gói hiện tên chúng; maskedRef đọc số tổng LIVE của chúng qua /v1/rankings/masked/{ref}. Entry bị che cũng có movement, previousRank và sparkline là null, vì chúng sẽ cho biết entry đó từng ở đâu. Ở kỳ hiện tại, mọi entry khác mang sparkline: điểm của nó trong từng kỳ đầy đủ ở bảy kỳ gần nhất, cũ nhất trước, null ở kỳ nó không có mặt trên bảng.
Tham số query
| Name | Type | Description |
|---|---|---|
boardRequired | string | Khóa của bảng: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly (cần shop:read), hoặc một bảng league từ league_a1 … league_d5. |
regionOptional | string | Mã khu vực ISO 3166-1 alpha-2. Default: VN |
periodOptional | "current" | "history" | current là kỳ đang chạy, history là kỳ gần nhất đã hoàn tất.Default: current |
limitOptional | integer | Số entry tối đa. Khoảng giá trị 1–200. Default: 200 |
liveOnlyOptional | "true" | "false" | Chỉ các creator đang live ngay lúc này. Default: false |
leagueTierOptional | string | Lọc theo hạng league, A1 … D5. |
Request
curl "https://api.next.toktokdata.live/v1/rankings/official?board=daily" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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" } }}Lỗi
400Tham số hoặc body không hợp lệ;codecho biết vấn đề.401API key bị thiếu hoặc không xác định.402Ví credit của workspace không đủ cho lệnh gọi;resetAtcho biết khi nào credit được reset.403Key thiếu scope, hoặc gói không bao gồm tính năng này.429Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theoRetry-After.
Liệt kê các khu vực được phủ
/v1/rankings/regionsCác khu vực hiện có bảng đã quan sát, kèm nhãn hiển thị. Hãy cache kết quả trong một ngày.
Request
curl "https://api.next.toktokdata.live/v1/rankings/regions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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 }}Lỗi
400Tham số hoặc body không hợp lệ;codecho biết vấn đề.401API key bị thiếu hoặc không xác định.402Ví credit của workspace không đủ cho lệnh gọi;resetAtcho biết khi nào credit được reset.403Key thiếu scope, hoặc gói không bao gồm tính năng này.429Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theoRetry-After.