RoomScope

آخر تحديث

التصنيفات

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

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

عرض الفترات السابقة للوحة تصنيف

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

جلب لوحة تصنيف رسمية

GET/v1/rankings/official

لوحة تصنيف واحدة لمنطقة واحدة، كما تنشرها TikTok. لا يُعاد إنتاج لوحات التصنيف إلا بعد أن تجتاز التغطية حدًا معينًا: اقرأ publishable وcoverage قبل عرض الإدخالات. أما الإدخالات التي تتجاوز ما تُظهره الباقة فتحتفظ بـ rank وscore لكنها تُرجَع مع masked: true، ودون هوية، ومع unmaskTier الذي يُظهرها. وفي الفترة الحالية يحمل كل إدخال 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.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.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.
هل كانت هذه الصفحة مفيدة؟