آخر تحديث
التصنيفات
لوحات التصنيف الرسمية حسب اللوحة والمنطقة والفترة.
تُصادَق كل عملية بمفتاح API (Authorization: Bearer <key>) وتستخدم الأخطاء الغلاف المشترك الموضّح في الأخطاء. مولَّد من مستند OpenAPI الخاص بواجهة API.
جلب الحد اليومي للوحة
/v1/rankings/day-barsلكل يوم من أيام اللوحة خلال آخر days يومًا: عدد صنّاع المحتوى المدرجين في اللوحة، وأدنى نتيجة فيها (الحد المطلوب لدخول اللوحة) وأعلى نتيجة، مقروءة من آخر لوحة كاملة رصدها RoomScope قبل إعادة الضبط اليومية، وعدد اللوحات الكاملة التي قرأها في ذلك اليوم. ينطبق على daily ولوحات الدوري (من league_a1 إلى league_d5).
معاملات الاستعلام
| Name | Type | Description |
|---|---|---|
regionOptional | string | رمز المنطقة. Default: VN |
boardOptional | string | daily أو لوحة دوري.Default: daily |
daysOptional | integer | عدد الأيام إلى الوراء. المدى …–90. Default: 30 |
الطلب
curl "https://api.next.toktokdata.live/v1/rankings/day-bars" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"الاستجابة
{ "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.
عرض الفترات السابقة للوحة تصنيف
/v1/rankings/historyالفترات المكتملة للوحة تصنيف واحدة، من الأحدث إلى الأقدم، ضمن نافذة السجل في الباقة.
معاملات الاستعلام
| Name | Type | Description |
|---|---|---|
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"الاستجابة
{ "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 لصف مخفي
/v1/rankings/masked/{ref}إجماليات LIVE لصف مخفي في لوحة الترتيب خلال 30 يومًا، حسب maskedRef الذي أعادته اللوحة: عدد الجلسات وثواني البث ومتوسط ذروة المشاهدين. لا تتضمن أبدًا هوية صانع المحتوى، ولا سلسلة يومية أو لكل جلسة يمكن مطابقتها مع صف يحمل اسمًا. يعمل المرجع فقط في مساحة العمل التي استلمته، وكل قراءة للوحة تُنشئ مراجع جديدة.
معاملات المسار
| Name | Type | Description |
|---|---|---|
refRequired | string | maskedRef لصف مخفي في لوحة الترتيب. |
الطلب
curl "https://api.next.toktokdata.live/v1/rankings/masked/ref" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"الاستجابة
{ "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.
جلب لوحة تصنيف رسمية
/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 حيث لم يكن في اللوحة.
معاملات الاستعلام
| Name | Type | Description |
|---|---|---|
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"الاستجابة
{ "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.
عرض المناطق المغطاة
/v1/rankings/regionsالمناطق التي لديها حاليًا لوحات تصنيف مرصودة، مع تسمية للعرض. خزّنها مؤقتًا لمدة يوم.
الطلب
curl "https://api.next.toktokdata.live/v1/rankings/regions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"الاستجابة
{ "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.