التحليلات

كل نقطة نهاية لتحليلات الملف التجاري مع مثال باستخدام cURL وPython وNode: مقاييس يومية من Google وFacebook ومشاهدات أسبوعية من Bing لموقع.

توضح تحليلات الملف التجاري عدد مرات ظهور الموقع والإجراءات التي اتُّخذت بشأنه على كل منصة نشر: مرات الظهور، ومشاهدات الصفحة، وطلبات الاتجاهات، والمكالمات، والنقرات على الموقع الإلكتروني. توجد 3 نقاط نهاية، واحدة لكل منصة نشر، وجميعها مخصصة للقراءة، لذا يكفي مفتاح Read (قراءة). كل مقياس عبارة عن سلسلة زمنية من نقاط { startTime, value }؛ ولا تُرجع واجهة API إجماليات في صورة قيم مفردة، لذا فإن المجاميع التي تعرضها هي التي تحسبها بنفسك.

نظرة سريعة على نقاط النهاية

تشترك نقاط النهاية الثلاث في المعاملات نفسها. كلٌّ من fromDate وtoDate بالتنسيق YYYY-MM-DD، وكلاهما اختياري؛ إذا أغفلتهما، تُستخدم الفترة الحديثة الافتراضية لمنصة النشر. يقبل المسار معرّف Relay بترميز base64 أو الرقم مباشرةً. إذا لم تكن القيمة أيًّا منهما، تُرجع نقطة النهاية 200 مع تعيين كائن insights إلى null وإرفاق مصفوفة errors، وهو ما يبدو كحالة ملف تجاري غير متصل، لذا تحقّق من errors أولًا.

قراءة مقاييس Google لنطاق زمني

تُرجع GET /locations/{locationId}/google-analytics الكائن data.googleInsights مع سلسلة يومية واحدة لكل مقياس. يمثل total مرات ظهور الملف التجاري، أي search مضافًا إليه maps؛ ولا يشمل مقاييس الإجراءات. استخدمه لإعداد تقرير يقارن مستوى الظهور قبل تغيير البيانات وبعده.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "googleInsights": {      "total": [        { "startTime": "2026-08-01T00:00:00+00:00", "value": 412 },        { "startTime": "2026-08-02T00:00:00+00:00", "value": 388 }      ],      "search": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 300 }],      "maps": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 112 }],      "directionsAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 24 }],      "phoneAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 8 }],      "websiteAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 41 }],      "businessBookings": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 0 }],      "businessFoodOrders": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 0 }],      "businessFoodMenuClicks": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 0 }]    }  }}

يمثل startTime في كل نقطة اليوم الذي يُجمَّع العدد ضمنه. في المثال، تبلغ قيمة total في اليوم الأول 412، وهي 300 من search مضافًا إليها 112 من maps.

تكون قيمة المقياس null، وليست مصفوفة فارغة، عندما لا تتوفر للموقع بيانات من Google خلال الفترة أو عندما لا يكون ملفه التجاري على Google متصلًا. تعامل مع null و[] بالطريقة نفسها عند التجميع.

قراءة مقاييس Facebook لنطاق زمني

تتبع GET /locations/{locationId}/facebook-analytics البنية نفسها ضمن data.facebookInsights، مع 5 سلاسل يومية. وتتطلب أن تكون صفحة Facebook الخاصة بالموقع متصلة. يُستخدم ctaAction لقياس أداء زر "احجز الآن" أو "اتصل الآن" خلال فترة الحملة.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/facebook-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "facebookInsights": {      "views": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 120 }],      "ctaAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 5 }],      "directionsAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 3 }],      "phoneAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 2 }],      "websiteAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 9 }]    }  }}

لا يوجد مقياس لإعجابات الصفحة. تُرجع كل سلسلة القيمة null عندما لا تتوفر للصفحة بيانات ضمن النطاق أو عندما لا تكون متصلة، لذا تحقّق من null قبل التكرار عبر عناصرها.

قراءة مشاهدات Bing لنطاق زمني

يُرجع GET /locations/{locationId}/bing-analytics سلسلة واحدة، data.bingInsights.views، مجمّعة حسب الأسبوع بدلاً من اليوم. تمثل كل نقطة عدد المشاهدات لأسبوع واحد يبدأ عند startTime. تُحدَّث البيانات كل يوم اثنين للأسبوع السابق، لذا فإن أحدث أسبوع مكتمل هو آخر أسبوع ستراه. اجلب نطاقاً يمتد لعدة أشهر للحصول على خط اتجاه؛ فهو غير مناسب لإسناد النتائج على مستوى اليوم.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/bing-analytics?fromDate=2026-06-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "bingInsights": {      "views": [        { "startTime": "2026-06-01T00:00:00+00:00", "value": 73 },        { "startTime": "2026-06-08T00:00:00+00:00", "value": 58 }      ]    }  }}

على خلاف Google وFacebook، يشير Bing إلى عدم وجود بيانات بمصفوفة views فارغة مع 200، وليس بصيغة null. تعامل مع كلتا الحالتين على أنهما "لا شيء لعرضه"، وتحقق من length == 0 إذا أردت إظهار عبارة "لا توجد بيانات"، لأن مجموع عناصر المصفوفة الفارغة يساوي 0.

الأخطاء التي ستواجهها

لا تذكر الصفحات المرجعية أي رموز أخطاء خاصة بموارد التحليلات. الحالات التي ستواجهها:

القائمة الكاملة موجودة في رموز الأخطاء.

الخطوات التالية

• جلب تحليلات الملف التجاري: اجمع قيم سلسلة للحصول على إجمالي شهري وقارن بين فترتين، مع تطبيق عمليات التحقق الوقائية الخاصة بـ null.
• تحليلات التقييمات: التقييم وعدد التقييمات ومعدل الرد للموقع نفسه، مع فروق محسوبة تلقائياً بين الفترات.
• التقييمات: نقاط نهاية تحليلات التقييمات إلى جانب بقية نقاط نهاية مورد التقييمات.
• الصفحة الرئيسية للمرجع: التحليلات. حزم SDK: تحليلات Python، تحليلات Node.