RoomScope

آخر تحديث

التصنيفات

لوحات التصنيف الرسمية حسب اللوحة والمنطقة والفترة.

تُصادَق كل عملية بمفتاح API (Authorization: Bearer <key>) وتستخدم الأخطاء الغلاف المشترك الموضّح في الأخطاء. مولَّد من مستند OpenAPI الخاص بواجهة API.

جلب الحد اليومي للوحة

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
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"

الاستجابة

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}

إجماليات LIVE لصف مخفي في لوحة الترتيب خلال 30 يومًا، حسب maskedRef الذي أعادته اللوحة: عدد الجلسات وثواني البث ومتوسط ذروة المشاهدين. لا تتضمن أبدًا هوية صانع المحتوى، ولا سلسلة يومية أو لكل جلسة يمكن مطابقتها مع صف يحمل اسمًا. يعمل المرجع فقط في مساحة العمل التي استلمته، وكل قراءة للوحة تُنشئ مراجع جديدة.

النطاقrank:readوحدات الرصيدقراءة مخزنة مؤقتًا

معاملات المسار

معاملات المسار · 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 معامل أو جسم طلب غير صالح؛ ويحدد 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 إجماليات LIVE الخاصة بها عبر /v1/rankings/masked/{ref}. كما أن قيم 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
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 معامل أو جسم طلب غير صالح؛ ويحدد 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.
هل كانت هذه الصفحة مفيدة؟