Listings APIListings API
تسجيل الدخول

جلب تحليلات الملفات التجارية على Google وFacebook وBing

اجلب المقاييس اليومية للملف التجاري على Google وFacebook والمشاهدات الأسبوعية على Bing لموقع، واحسب إجمالي سلسلة للشهر، وقارن بين فترتين.

توضح تحليلات الملفات التجارية عدد مرات ظهور موقع والتفاعل معه على كل منصة نشر: مرات الظهور وطلبات الاتجاهات والمكالمات والنقرات على الموقع الإلكتروني. كل مقياس عبارة عن سلسلة زمنية من نقاط { startTime, value }، لذا فإن الإجماليات التي تعرضها هي التي تحسبها بنفسك.

1. قراءة مقاييس Google لنطاق تواريخ

تُرجع GET /locations/{locationId}/google-analytics?fromDate=&toDate= القيمة data.googleInsights مع سلسلة يومية واحدة لكل مقياس. يمثل total مرات ظهور الملف التجاري، أي search زائد maps؛ ولا يتضمن مقاييس الإجراءات.

Google
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "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": null,      "businessFoodOrders": null,      "businessFoodMenuClicks": null    }  }}
السلسلةالمعنى
totalمرات الظهور، search زائد maps.
search, mapsمرات الظهور في Google Search وGoogle Maps.
directionsAction, phoneAction, websiteActionطلبات الاتجاهات والنقرات للاتصال والنقرات على الموقع الإلكتروني.
businessBookings, businessFoodOrders, businessFoodMenuClicksالحجوزات وطلبات الطعام والنقرات على قائمة الطعام، للملفات التجارية التي توفر هذه الخيارات.

يؤدي استخدام معرّف موقع بتنسيق غير صحيح إلى إرجاع 200 مع googleInsights: null ومصفوفة errors، مما يبدو كأنه ملف تجاري غير متصل. تحقق من errors أولًا.

2. قراءة مقاييس Facebook

تتخذ GET .../facebook-analytics البنية نفسها ضمن data.facebookInsights مع خمس سلاسل يومية: views وctaAction وdirectionsAction وphoneAction وwebsiteAction.

Facebook
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/facebook-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "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 }]    }  }}

يحسب ctaAction عدد النقرات على زر الدعوة إلى اتخاذ إجراء في الصفحة، وهو ما تستخدمه لقياس حملة «احجز الآن» أو «اتصل الآن». لا يوجد مقياس لإعجابات الصفحة.

3. قراءة مشاهدات Bing

تُرجع GET .../bing-analytics سلسلة واحدة، هي data.bingInsights.views، مجمّعة حسب الأسبوع بدلًا من اليوم. تُحدَّث البيانات كل يوم اثنين للأسبوع السابق، لذا اجلب نطاقًا يمتد لعدة أشهر للحصول على خط اتجاه.

Bing
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/bing-analytics?fromDate=2026-06-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "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 فارغة بدلًا من null. تعامل مع الحالتين على أنهما «لا شيء لعرضه».

4. جمع قيم سلسلة للحصول على إجمالي شهري

اجلب بيانات الشهر، ثم اجمع قيمة value لكل نقطة. ميّز بين null والصفر: يجب عرض الملف التجاري غير المتصل على أنه «غير متاح»، وليس كشهر بلا زيارات. تتضمن صفحة التحليلات في Node SDK الدالة المساعدة sumSeries نفسها.

Monthly total
# jq: null when the metric is null, otherwise the sum of valuescurl -s "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.googleInsights | { search: (if .search == null then null else ([.search[].value] | add) end),                               maps: (if .maps == null then null else ([.maps[].value] | add) end) }'

يتطلب Bing تحققًا إضافيًا واحدًا: مجموع قيم مصفوفة views فارغة يساوي 0، لذا تحقق من length == 0 إذا أردت عرض «لا توجد بيانات» في هذه الحالة أيضًا.

5. المقارنة بين فترتين

اجلب المقياس نفسه لنطاقين متساويين في المدة واحسب التغير من الإجماليين. لا توفر API مقارنة مدمجة لتحليلات الملفات التجارية؛ فحقول delta موجودة فقط في تحليلات التقييمات.

Two periods
curl -s "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2026-07-01&toDate=2026-07-31" \-H "Authorization: API $LISTINGSAPI_KEY" | jq '[.data.googleInsights.total[].value] | add' curl -s "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY" | jq '[.data.googleInsights.total[].value] | add'

تعامل مع ثلاث حالات: أن تكون قيمة أي من الفترتين null (غير متصل)، وأن تكون قيمة الفترة السابقة 0 (قسمة على صفر)، وأن يكون النطاق لم ينتهِ بعد، لأن مقارنة شهر غير مكتمل بشهر كامل تبدو دائمًا كانخفاض. يُحتسب كل استدعاء ضمن حد معدل الطلبات لديك، لذا خزّن بيانات الفترة السابقة مؤقتًا بدلًا من إعادة جلبها عند كل عملية عرض.

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