/api/v4/locations/{locationId}/google-analyticsالحصول على تحليلات Google لموقع
يعيد مقاييس التفاعل اليومية مع Google Business Profile لموقع خلال نطاق زمني.
المعلمات
المسار
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| locationId | string | مطلوب | Location ID, either the Base64 Relay id (e.g. TG9jYXRpb246MTgwMDI4OQ==) or the raw numeric database id (e.g. 1800289). Both forms resolve to the same location. |
الاستعلام
| الاسم | النوع | مطلوب | الوصف | الافتراضي |
|---|---|---|---|---|
| fromDate | string | اختياري | Start of the range (YYYY-MM-DD). Defaults to a recent window when omitted. | — |
| toDate | string | اختياري | End of the range (YYYY-MM-DD). | — |
الاستجابات
200Daily Google interaction metrics. Each metric is a time-series array; a metric is `null` when no data exists for the range or the profile is not connected.
{ "data": { "googleInsights": { "total": [ { "startTime": "2025-06-01T00:00:00+00:00", "value": 412 }, { "startTime": "2025-06-02T00:00:00+00:00", "value": 388 } ], "search": [ { "startTime": "2025-06-01T00:00:00+00:00", "value": 300 } ], "maps": [ { "startTime": "2025-06-01T00:00:00+00:00", "value": 112 } ], "directionsAction": [ { "startTime": "2025-06-01T00:00:00+00:00", "value": 24 } ], "phoneAction": [ { "startTime": "2025-06-01T00:00:00+00:00", "value": 8 } ], "websiteAction": [ { "startTime": "2025-06-01T00:00:00+00:00", "value": 41 } ], "businessBookings": [ { "startTime": "2025-06-01T00:00:00+00:00", "value": 0 } ], "businessFoodOrders": [ { "startTime": "2025-06-01T00:00:00+00:00", "value": 0 } ], "businessFoodMenuClicks": [ { "startTime": "2025-06-01T00:00:00+00:00", "value": 0 } ] } }}401Unauthenticated, missing or invalid API key.
يعيد بيانات التفاعل اليومية مع Google Business Profile لموقع. كل مقياس عبارة عن مصفوفة من نقاط سلسلة زمنية، وتحتوي كل نقطة على startTime (اليوم الذي يُجمَّع العدد ضمنه) وعلى value.
المقاييس المتاحة:
total: إجمالي مرات ظهور الملف، وهو مجموعsearchوmaps. هذا الإجمالي لا يشمل مقاييس الإجراءات أدناه، لذا في المثال أعلاه 412 = 300 من البحث + 112 من الخرائط.search: مرات الظهور في نتائج Google Search (على أجهزة الكمبيوتر والأجهزة الجوّالة مجتمعة)maps: مرات الظهور في نتائج Google Maps (على أجهزة الكمبيوتر والأجهزة الجوّالة مجتمعة)directionsAction: طلبات الحصول على الاتجاهات إلى الموقعphoneAction: النقرات على زر الاتصالwebsiteAction: النقرات للانتقال إلى الموقع الإلكترونيbusinessBookings: الحجوزات التي بُدئ بها من الملفbusinessFoodOrders: طلبات الطعام المقدَّمة من الملفbusinessFoodMenuClicks: النقرات على رابط قائمة الطعام
يمكن استخدام أيٍّ من صيغتَي id في المسار
يشير كلٌّ من 1800289 وTG9jYXRpb246MTgwMDI4OQ== إلى الموقع نفسه. يُفضَّل استخدام معرّف Relay بترميز Base64: فهو ما تعيده كل نقطة نهاية للقراءة، وهو الصيغة التي تقبلها بقية واجهة API. تؤدي القيمة التي ليست رقمًا ولا معرّف Relay قابلًا لفك الترميز إلى إرجاع 200 يكون متن استجابته {"data":{"googleInsights":null},"errors":[...]}، مما يسهل تفسيره خطأً على أنه عطل في الخادم.
curl -s 'https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2025-06-01&toDate=2025-06-30' \ -H "Authorization: API $LISTINGSAPI_KEY"إعداد تقرير عن أثر تحديث البيانات
من الاستخدامات الشائعة إعداد تقرير عن الظهور قبل التغيير وبعده: بعد إرسال تغييرات ساعات العمل أو الفئة إلى موقع، استعلم دوريًا من google-analytics عن الأسابيع السابقة للتغيير واللاحقة له، وارسم search + maps بيانيًا لإظهار الزيادة. تُعاد المقاييس الفردية بالقيمة null (بدلًا من مصفوفة فارغة) عندما لا تتوفر للموقع بيانات Google للفترة المطلوبة أو عندما لا يكون ملفه على Google متصلًا؛ لذا تعامل مع null و[] بالطريقة نفسها عند تجميع البيانات. اجمع هذه البيانات مع تحليلات Facebook وBing للحصول على رؤية عبر منصات النشر.
curl -X GET 'https://listingsapi.com/api/v4/locations/<locationId>/google-analytics' \ -H "Authorization: API $LISTINGSAPI_KEY"