الانتقال إلى المحتوى الرئيسي
POST
احصل على التحليلات والبيانات الديموغرافية لملف المستخدم الاجتماعي، مثل الانطباعات والمشاهدات والمتابعين. متاح حاليًا لـ Bluesky وFacebook Pages وGoogle My Business وInstagram وLinkedIn وPinterest وReddit وSnapchat وThreads وTikTok وX/Twitter وYouTube.
Facebook: أوقفت Meta بعض مقاييس Reach والفيديو (15 يونيو 2026). أزالت Meta مقاييس Insights الخاصة بـ unique impression وvideo-view لمدة 3 ثوانٍ (unique) عبر جميع إصدارات Graph API، لذا لم يعد كائن Facebook analytics يُرجع عائلة pagePostsImpressions* (pagePostsImpressions، pagePostsImpressionsPaid، pagePostsImpressionsUnique، pagePostsImpressionsOrganicUnique، pagePostsImpressionsViral*، pagePostsImpressionsNonviral*، pagePostsServedImpressionsOrganicUnique) أو pageVideoViewsUnique. استخدم pageMediaView لقياس الوصول (يُخطَّط لخلف مسمّى Total Unique Media Views). لا يتأثر pagePostEngagements وpageVideoViews وpageVideoViewsPaid. المرجع: تغييرات API القادمة — 15 يونيو 2026.
  • تحليلات Facebook Page متاحة فقط للصفحات التي تحتوي 100 إعجاب أو أكثر، مثل البيانات الديموغرافية. عادةً ما يُحدّث Facebook مقاييسه مرة واحدة كل 24 ساعة.
  • قد يستغرق Instagram حتى 48 ساعة لحساب بيانات التحليلات. تحليلات عدد المتابعين غير متوفرة إذا كان عدد المتابعين أقل من 100. تُرجع المقاييس الديموغرافية أفضل 45 أداءً فقط، ويُستخدم فقط المشاهدون الذين تتوفر لدينا بياناتهم الديموغرافية في حسابات المقاييس الديموغرافية، ولا تُرجع البيانات الديموغرافية إذا كان لمستخدم Instagram أقل من 100 تفاعل خلال آخر 30 يومًا.
  • عند استرجاع تحليلات Instagram الاجتماعية، قد لا تظهر المعلومات الديموغرافية في الاستجابة لمقاييس معينة. تظهر المعلومات الديموغرافية عندما يكون هناك أكثر من 100 شخص في كل تصنيف. يُرجى مراجعة تحذير بيانات Instagram الديموغرافية لمزيد من المعلومات.
  • يدعم LinkedIn تحليلات Company Page وتحليلات الملف الشخصي (member) على حد سواء. للملفات الشخصية، يتضمّن كائن analytics قيمة followersCount مدى الحياة، ونموّ المتابعين اليومي في followersDaily[]، ومقاييس المنشورات المجمعة (impressionCount، uniqueImpressionsCount، likeCount، commentCount، shareCount). قيم count الإجمالية في LinkedIn تتّسق تدريجيًا وليست فورية، وقد تستغرق حتى 24-48 ساعة في بعض الحالات. القيم المجمعة shareCount وlikeCount وcommentCount للملفات الشخصية هي best-effort وقد تختلف قليلًا عن الأرقام المعروضة في واجهة LinkedIn.
  • قد يستغرق TikTok 24-48 ساعة لتحديث بيانات التحليلات، مثل مشاهدات الفيديو والبيانات الديموغرافية والإعجابات والمشاركات والتعليقات.
  • يُرجى مراجعة نقطة نهاية تحليلات المنشور لمعلومات إضافية.

معاملات الرأس (Header)

معاملات النص (Body)

platforms
array
مطلوب
منصات التواصل الاجتماعي التي تريد الحصول على التحليلات لها. تقبل مصفوفة من السلاسل النصية بالقيم التالية:
quarters
integer
يحدّد كم من الربوع (quarters) للبيانات التاريخية سيُرجَع. الربع هو:
  • 85 يومًا لـ Facebook
  • 90 يومًا لـ Instagram وTikTok وYouTube
  • 90 يومًا لـ Snapchat (بحدّ أقصى 1 quarter / 90 يومًا نظرًا لقيود Snapchat API)
متاح لمنصات Facebook وInstagram وSnapchat وTikTok وYouTube. القيم الصالحة: 1–4. فقط القيم الأكبر من 0 تُفعّل تصفية التواريخ.تصفية التواريخ (Instagram وTikTok): تكون تصفية التواريخ نشطة عندما يكون daily=true أو quarters > 0. إذا لم يُقدَّم daily ولا quarters، تُرجَع بيانات كامل الفترة دون تطبيق أي تصفية للتاريخ.ملاحظة: يُعامَل quarters: 0 الآن كأنه لا يوجد نطاق تاريخ (بيانات كامل الفترة). سابقًا، كان quarters: 0 يُعامَل كأنه quarters: 1.
daily
boolean
افتراضي:false
عند الضبط على true، تُرجع بيانات التحليلات كسلسلة زمنية يومية بدلًا من الإجماليات المجمّعة. هذا الخيار متاح فقط لمنصات Facebook وInstagram وSnapchat وTikTok وYouTube. نظرًا لحجم البيانات الأكبر، يُوصى باستخدام الضغط.بالنسبة لـ Instagram وTikTok، فإن ضبط daily=true يُفعّل أيضًا تصفية التواريخ باستخدام نافذة quarters افتراضية أقصر.Instagram reach: مع daily=true، تُرجع استجابة Instagram كائن reach متداخل (يحتوي على period وسلسلة زمنية values) بدلًا من الحقل القياسي reachCount الذي يُرجَع في الوضع غير اليومي.
period60Days
boolean
افتراضي:false
لتحليلات TikTok، عند الضبط على true، يُرجع فقط إجماليات 60 يومًا للتعليقات والمشاركات والمشاهدات (commentCountTotal، shareCountTotal، viewCountTotal). يوفر ذلك أزمنة استجابة أسرع مقارنةً باسترجاع سجل التحليلات الكامل. ملاحظة: لا تستخدم هذا المعامل مع daily=true لأنهما غير متوافقين.مهم: اعتبارًا من 1 مارس 2025، انتقل TikTok إلى إجماليات 60 يومًا. اعتبارًا من أبريل 2026، يستخدم TikTok تصفية التواريخ المستندة إلى quarters — استخدم المعامل quarters للتحكم في نافذة التاريخ (مثلًا، quarters: 1 = 90 يومًا، quarters: 2 = 180 يومًا). راجع التغييرات القادمة للتفاصيل.
youtube
object
خيارات خاصة بمنصة YouTube لتحليلاتها.lifetime (boolean، افتراضي: false): عند الضبط على true، يتضمّن lifetimeLikes في الاستجابة — مجموع الإعجابات عبر جميع الفيديوهات العامة على القناة. يُحسب ذلك بجلب جميع الفيديوهات وجمع أعداد الإعجابات، لذا قد يستغرق وقتًا أطول للقنوات التي تحتوي على العديد من الفيديوهات.الحدّ: القنوات التي تحتوي أكثر من 1,000 فيديو ستُرجع lifetimeLikes: null وتحذيرًا في مصفوفة warnings في المستوى الأعلى. يمنع هذا الاستخدام المفرط لواجهة API.التخزين المؤقت: لكل قناة، مع مدد TTL أقصر للحالات غير الناجحة بحيث تلتقط المحاولات اللاحقة تغييرات الحالة سريعًا:
  • قيمة lifetimeLikes الناجحة: 24 ساعة.
  • انسحاب 1,000 فيديو (تحذير code: 445): ساعة واحدة — قصيرة بما يكفي بحيث لا تنتظر قناة حذفت فيديوهات لتنخفض تحت الحدّ يومًا كاملًا للحصول على قيمة حقيقية.
  • إخفاقات مؤقتة في YouTube Data API (تحذير code: 446): لا يتم تخزينها مؤقتًا — الطلب التالي يعيد المحاولة.
ملاحظة: تُستبعد الفيديوهات المحذوفة أو الخاصة من المجموع، لذا قد يختلف الإجمالي عن “الإجمالي الحقيقي” للإعجابات مدى الحياة للقنوات التي أزالت فيديوهات.مثال طلب:
userId
string
X/Twitter فقط. يسمح لك هذا المعامل باسترجاع المنشورات من مستخدم X/Twitter محدد عبر معرّفه الرقمي، بدلًا من حسابك المرتبط.على سبيل المثال، للحصول على جميع منشورات المعرّف @Google، ستستخدم userId الرقمي 20536157.يمكنك العثور على userId الرقمي لأي مستخدم X/Twitter عبر نقطة النهاية Brands Get User.ملاحظة: استخدم API KEY فقط في الرأس لتقديم هذا الطلب. لا تُضمّن Profile Key.
userName
string
X/Twitter فقط. يسمح لك هذا المعامل باسترجاع المنشورات من مستخدم X/Twitter محدد عبر معرّفه (handle)، بدلًا من حسابك المرتبط.على سبيل المثال، للحصول على جميع منشورات المعرّف @Google.ملاحظة: استخدم API KEY فقط في الرأس لتقديم هذا الطلب. لا تُضمّن Profile Key.
عندما تكون المقاييس التراكمية (مثل المتابعين، الإعجابات) غير متوفرة مؤقتًا من الشبكة الاجتماعية، تعبّئها واجهة API تلقائيًا (backfill) من البيانات المخزَّنة. قد يظهر حقلان اختياريان في كائن analytics الخاص بكل منصة:
  • backfilledFrom (سلسلة نصية، ISO 8601) — يظهر عندما يُستبدَل مقياس تراكمي واحد أو أكثر من البيانات المخزَّنة. تشير الطابع الزمني إلى آخر تحديث للبيانات المخزَّنة.
  • recoveredFrom (سلسلة نصية، ISO 8601) — يظهر عندما تُستعاد استجابة التحليلات بأكملها من البيانات المخزَّنة بسبب فشل كامل في API. تشير الطابع الزمني إلى آخر تحديث للبيانات المخزَّنة.
تُعدّ البيانات المخزَّنة الأقدم من 4 أيام قديمة ولن تُستخدم في backfill أو الاسترداد.LinkedIn reactions: يخضع مقياس reactions التراكمي على مستوى المنشور (كائن يحتوي أعداد التفاعلات لكل نوع) لهذا الـ backfill المخصّص للحالات الفارغة فقط. عندما يُقيّد LinkedIn معدلات جلب reactions، تُنقل القيمة من آخر لقطة ناجحة — ويُضبط backfilledFrom على الطابع الزمني لتلك اللقطة — بدلًا من التراجع إلى قيمة فارغة.
تحليلات LinkedIn الشخصية (member) — يلزم إعادة الربط. الملفات الشخصية على LinkedIn التي رُبطت قبل إطلاق تحليلات member لا تمتلك نطاقات التحليلات المطلوبة. طلبات التحليلات الاجتماعية لهذه الملفات تُرجع رمز الخطأ 475 (“re-link your LinkedIn profile to enable analytics”). يجب على مالك الحساب إعادة ربط ملفه الشخصي على LinkedIn في صفحة Social Accounts لمنح النطاقات الجديدة. أعطِ الأمر بضع دقائق بعد إعادة الربط ليختفي الرمز 475 (تُخزّن Ayrshare وLinkedIn حالة الأذونات مؤقتًا لفترة قصيرة، عادةً 5-10 دقائق). النشر لا يتأثر.
warnings (مصفوفة من الكائنات، حقل اختياري في المستوى الأعلى) — يظهر فقط عندما تحتاج Ayrshare إلى إبلاغ المتصل بحالة غير قاتلة (مثلًا، تخطي حساب اختياري). غائب عن الاستجابة عندما لا يكون هناك ما يستدعي التحذير.كل إدخال هو كائن مُنظَّم، وليس نصًا حرًّا:رموز التحذير المعروفة:
  • 445 — تم تخطي lifetimeLikes لأن قناة YouTube تتجاوز حدّ 1,000 فيديو.
  • 446lifetimeLikes غير متاح لأن YouTube Data API أرجعت أخطاء لقائمة تشغيل الرفوعات أو لكل دفعة videos.list.