RoomScope

อัปเดตล่าสุด

อันดับ

บอร์ดอันดับทางการแยกตามบอร์ด ภูมิภาค และรอบ

ทุกการดำเนินการยืนยันตัวตนด้วย API key (Authorization: Bearer <key>) และข้อผิดพลาดใช้โครงสร้างร่วมที่อธิบายไว้ใน ข้อผิดพลาด. สร้างจากเอกสาร OpenAPI ของ API

ดึงเกณฑ์รายวันของบอร์ด

GET/v1/rankings/day-bars

สำหรับแต่ละวันของบอร์ดใน days วันล่าสุด: จำนวนครีเอเตอร์ที่บอร์ดแสดง คะแนนต่ำสุดบนบอร์ด (เกณฑ์ในการติดบอร์ด) และคะแนนสูงสุด ซึ่งอ่านจากบอร์ดฉบับสมบูรณ์ล่าสุดที่ RoomScope สังเกตได้ก่อนการรีเซ็ตรายวัน รวมถึงจำนวนบอร์ดฉบับสมบูรณ์ที่อ่านได้ในวันนั้น ใช้กับ daily และบอร์ดลีก (league_a1 ถึง league_d5)

สโคปrank:readเครดิตอ่านข้อมูลแคช

พารามิเตอร์ query

พารามิเตอร์ query · 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 พารามิเตอร์หรือ body ไม่ถูกต้อง code จะระบุปัญหา
  • 401 ไม่มี API key หรือไม่รู้จัก API key
  • 402 กระเป๋าเครดิตของเวิร์กสเปซมีไม่พอสำหรับการเรียกนี้ resetAt บอกเวลาที่เครดิตจะรีเซ็ต
  • 403 คีย์ไม่มีสโคปที่ต้องการ หรือแพ็กเกจไม่รวมฟีเจอร์นี้
  • 429 เกินอัตราคำขอ (ต่อวินาที ต่อนาที หรือต่อวัน) โปรดทำตาม Retry-After

แสดงรายการรอบที่ผ่านมาของบอร์ด

GET/v1/rankings/history

รอบที่จบแล้วของบอร์ดหนึ่ง เรียงจากใหม่ไปเก่า ภายในช่วงเวลาประวัติของแพ็กเกจ

สโคปrank:readเครดิตอ่านข้อมูลแคช

พารามิเตอร์ query

พารามิเตอร์ query · 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
stringรหัสภูมิภาคตาม ISO 3166-1 alpha-2
Default: VN
cursorOptional
stringcursor แบบทึบจาก 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 พารามิเตอร์หรือ body ไม่ถูกต้อง code จะระบุปัญหา
  • 401 ไม่มี API key หรือไม่รู้จัก API key
  • 402 กระเป๋าเครดิตของเวิร์กสเปซมีไม่พอสำหรับการเรียกนี้ resetAt บอกเวลาที่เครดิตจะรีเซ็ต
  • 403 คีย์ไม่มีสโคปที่ต้องการ หรือแพ็กเกจไม่รวมฟีเจอร์นี้
  • 429 เกินอัตราคำขอ (ต่อวินาที ต่อนาที หรือต่อวัน) โปรดทำตาม Retry-After

ดึงยอดรวม LIVE ของแถวที่ถูกซ่อน

GET/v1/rankings/masked/{ref}

ยอดรวม LIVE ย้อนหลัง 30 วันของแถวที่ถูกซ่อนบนกระดาน ตาม maskedRef ที่กระดานส่งกลับ: จำนวนเซสชัน วินาทีที่ไลฟ์ และผู้ชมสูงสุดเฉลี่ย ไม่มีตัวตนของครีเอเตอร์ และไม่มีข้อมูลรายวันหรือรายเซสชันที่จับคู่กับแถวที่มีชื่อได้ ref ใช้ได้เฉพาะใน workspace ที่ได้รับมัน และการอ่านกระดานแต่ละครั้งจะสร้าง ref ใหม่

สโคปrank:readเครดิตอ่านข้อมูลแคช

พารามิเตอร์ใน path

พารามิเตอร์ใน path · GET /v1/rankings/masked/{ref}
NameTypeDescription
refRequired
stringmaskedRef ของแถวที่ถูกซ่อนบนกระดาน

คำขอ

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 พารามิเตอร์หรือ body ไม่ถูกต้อง code จะระบุปัญหา
  • 401 ไม่มี API key หรือไม่รู้จัก API key
  • 402 กระเป๋าเครดิตของเวิร์กสเปซมีไม่พอสำหรับการเรียกนี้ resetAt บอกเวลาที่เครดิตจะรีเซ็ต
  • 403 คีย์ไม่มีสโคปที่ต้องการ หรือแพ็กเกจไม่รวมฟีเจอร์นี้
  • 429 เกินอัตราคำขอ (ต่อวินาที ต่อนาที หรือต่อวัน) โปรดทำตาม Retry-After

ดึงบอร์ดทางการ

GET/v1/rankings/official

กระดานหนึ่งกระดานของหนึ่งภูมิภาค ตามที่ TikTok เผยแพร่ กระดานจะถูกจำลองก็ต่อเมื่อความครอบคลุมผ่านเกณฑ์: อ่าน publishable และ coverage ก่อนแสดงรายการ รายการที่เกินขอบเขตที่แพ็กเกจเปิดเผยยังคงมี rank และ score แต่ถูกส่งกลับด้วย masked: true โดยไม่มีตัวตน (creatorUid, avatarUrl และ roomId เป็น null) พร้อม unmaskTier ที่เปิดเผยได้ maskedRef ใช้อ่านยอดรวม LIVE ผ่าน /v1/rankings/masked/{ref} รายการที่ถูกซ่อนยังมี movement, previousRank และ sparkline เป็น null เพราะจะบอกได้ว่าเคยอยู่ตรงไหน ในช่วงเวลาปัจจุบัน รายการอื่นทุกรายการมี sparkline: คะแนนในแต่ละช่วงที่สมบูรณ์เจ็ดช่วงล่าสุด เรียงจากเก่าไปใหม่ และเป็น null เมื่อไม่ได้อยู่บนกระดาน

สโคปrank:readเครดิตอ่านข้อมูลแคช

พารามิเตอร์ query

พารามิเตอร์ query · 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
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"

ผลลัพธ์

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 พารามิเตอร์หรือ body ไม่ถูกต้อง code จะระบุปัญหา
  • 401 ไม่มี API key หรือไม่รู้จัก API key
  • 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 พารามิเตอร์หรือ body ไม่ถูกต้อง code จะระบุปัญหา
  • 401 ไม่มี API key หรือไม่รู้จัก API key
  • 402 กระเป๋าเครดิตของเวิร์กสเปซมีไม่พอสำหรับการเรียกนี้ resetAt บอกเวลาที่เครดิตจะรีเซ็ต
  • 403 คีย์ไม่มีสโคปที่ต้องการ หรือแพ็กเกจไม่รวมฟีเจอร์นี้
  • 429 เกินอัตราคำขอ (ต่อวินาที ต่อนาที หรือต่อวัน) โปรดทำตาม Retry-After
หน้านี้มีประโยชน์หรือไม่