ابدأ هنا

صيغة الاستجابة

الغلاف، وكتلة meta، والحقول الأساسية، وقيم null، والبيانات الأصلية (raw).

الغلاف

كل استجابة ناجحة على الشكل { data, meta }. في المسار الذي يعيد كائنًا واحدًا يكون data كائنًا واحدًا، وفي المسار المقسّم إلى صفحات يكون مصفوفة.

response

{
  "data": { … },            // one object, or an array on paged routes
  "meta": {
    "credits_used": 1,
    "credits_remaining": 2499,
    "cache": "MISS",          // or "HIT"
    "data_age_s": 0,          // seconds since we fetched it upstream
    "request_id": "req_01K5…",
    "next_cursor": "eyJ…"     // paged routes only, absent on the last page
  }
}

ونرسل الأرقام نفسها في الترويسات أيضًا، للعملاء الذين يقرؤون الترويسات وحدها أو يسجّلونها: X-Credits-Used وX-Credits-Remaining وX-Cache وX-Data-Age وX-Request-Id.

حقول موجودة في كل كائن

أيًّا كان النوع، يحمل كل كائن هذه الحقول. يحدد source مصدر البيانات: official (واجهة API الرسمية للمنصة)، أو own (أداة جمع البيانات الخاصة بنا)، أو upstream:<provider>.

الحقل	النوع	ملاحظات
platform	Platform
id	string
url	url
fetched_at	datetime
source	"official" \| "own" \| "upstream:…"
raw	unknown	اختياري
enrichment	Enrichment	قد يكون null, اختياري

قيم null بدل الحقول المفقودة

الحقل الذي لا تملكه المنصة قيمته null، ولا يُحذف ولا يُعاد تسميته أبدًا. لا يعرض Bluesky عدد المشاهدات، لذا يحمل منشور Bluesky القيمة engagement.views: null، بينما يحمل منشور TikTok رقمًا في الموضع نفسه. يقرأ الكود عندك المسار نفسه في كل مكان، ويعالج حالة إضافية واحدة فقط.

تعني null «لا تعرض المنصة هذه القيمة» أو «القيمة مخفية»، ولا تعني الصفر أبدًا. المنشور الذي لا إعجابات له يحمل likes: 0.

البيانات الأصلية

أضف include_raw=true إلى أي طلب قراءة لتحصل على بيانات المنصة كما هي، دون تعديل، في الحقل raw داخل كل كائن (وفي meta.raw للمسارات المقسّمة إلى صفحات). استخدمها للحقل النادر الذي لا يتضمنه المخطط الموحّد بعد. هذه البيانات ليست جزءًا من التزامات المخطط، وقد تتغير حين تتغير المنصة.

الأنواع

لدينا 18 نوعًا موحّدًا. وتعيد كل عملية النوع نفسه دائمًا، على كل منصة تقدّمها. تجد قائمة الحقول كاملة في الأنواع الموحّدة.