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

قياس أداء التقييمات

اقرأ مؤشرات الأداء الرئيسية لتقييمات موقع، وارسم المخطط الزمني اليومي، وقارن المصادر، واستخرج العبارات الشائعة، وتلقَّ لقطات يومية وأسبوعية عبر webhook.

تصف 3 نقاط نهاية مترابطة تقييمات موقع بالأرقام: نظرة عامة على مؤشرات الأداء الرئيسية، ومخطط زمني يومي، وتفصيل حسب المصدر. وتسرد نقطة نهاية رابعة العبارات التي يكررها العملاء. وتكفي هذه البيانات مجتمعة لإنشاء بطاقة لعرض مؤشرات الأداء، ومخطط للاتجاهات، ولوحة للشكاوى.

1. قراءة مؤشرات الأداء الرئيسية لموقع

تُرجع GET /locations/{locationId}/review-analytics-overview 4 إحصاءات في data.interactionsAnalyticsStats.stats. النطاق الزمني اختياري هنا؛ وهو يضيّق الفترة التي تُحسب خلالها القيم والفروق.

Overview
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-overview?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "interactionsAnalyticsStats": {      "stats": [        { "name": "total-reviews", "value": 128, "delta": 6.67 },        { "name": "new-reviews", "value": 9, "delta": -25 },        { "name": "overall-rating", "value": 4.43, "delta": 2.31 },        { "name": "review-response-rate", "value": 62.5, "delta": 12.5 }      ]    }  }}
namevalueتُقرأ على أنها
total-reviewsعددجميع تقييمات الموقع.
new-reviewsعددالتقييمات الواردة خلال الفترة.
overall-ratingمن 1 إلى 5متوسط التقييم بالنجوم.
review-response-rateنسبة مئويةنسبة التقييمات التي تتضمن ردًا من المالك.

يُظهر الحساب الجديد الذي لا توجد له فترة سابقة قيمة delta تساوي 100، لذا لا تفسّر فروق الشهر الأول على أنها نمو.

2. جلب المخطط الزمني اليومي لرسمه

تُرجع GET .../review-analytics-timeline عنصرًا واحدًا لكل يوم في data.interactionsChartData.data. مرّر دائمًا startDate وendDate، وإلا فستختار الخدمة الفترة بنفسها. أضف site (اسم مضيف مثل maps.google.com) لرسم مصدر واحد على حدة.

Timeline
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-timeline?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "interactionsChartData": {      "data": [        { "date": "2026-08-01", "interactionCount": 4, "averageRating": 4.5 },        { "date": "2026-08-02", "interactionCount": 0, "averageRating": null },        { "date": "2026-08-03", "interactionCount": 7, "averageRating": 4.285714285714286 }      ]    }  }}

ارسم interactionCount على هيئة أعمدة وaverageRating على هيئة خط. يمثّل averageRating متوسط ذلك اليوم، وليس متوسطًا تراكميًا، وتكون قيمته null في اليوم الذي لا توجد فيه تقييمات، لذا اترك فجوة بدلًا من رسم قيمة صفرية.

3. تفصيل البيانات حسب المصدر

تُرجع GET .../review-analytics-sites-stats عنصرًا واحدًا لكل مصدر تقييمات في data.interactionsSitesStats.stats. استخدمها لمعرفة المنصة التي غيّرت المتوسط.

By source
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-sites-stats?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "interactionsSitesStats": {      "stats": [        {          "key": "google",          "siteUrl": "maps.google.com",          "averageRating": { "value": 4.6, "delta": 2.2 },          "totalInteractions": { "value": 412, "delta": 6.1 },          "newInteractions": { "value": 24, "delta": 33.3 },          "recency": "2026-09-06T14:12:00Z",          "humanizedRecency": "3 days ago"        },        {          "key": "facebook",          "siteUrl": "facebook.com",          "averageRating": { "value": 4.1, "delta": -1.4 },          "newInteractions": { "value": 0, "delta": -100 },          "recency": null,          "humanizedRecency": null        }      ]    }  }}

يتضمن كل من averageRating وtotalInteractions وnewInteractions قيمة value وقيمة delta. تشير قيمة averageRating.delta سالبة واحدة إلى جانب قيم نظيرة ثابتة إلى مشكلة في منصة؛ أما كون جميع القيم سالبة فيشير إلى مشكلة في المتجر. عادةً ما تعني قيمة newInteractions التي تساوي 0 مع recency يعود إلى أشهر مضت أن اتصال المصدر لم يعد محدّثًا، لذا تحقّق من سرد مصادر التقييمات لموقع وأعِد إضافة المصدر باستخدام تعديل إعدادات التقييمات إذا لم يعد موجودًا.

4. العثور على العبارات التي يستخدمها العملاء

تُرجع GET /review-phrases مصفوفة بسيطة في data.newReviewPhrases، تضم عنصرًا واحدًا لكل عبارة متكررة، وبنية إحصاءات مماثلة لبنية النظرة العامة، تُحسب من التقييمات التي تحتوي على العبارة فقط. أضف ratingFilters=[1,2] لإنشاء لوحة للشكاوى. يُمرَّر locationIds وratingFilters على هيئة مصفوفتَي JSON في سلسلة الاستعلام، لذا يجب ترميزهما بترميز URL؛ وتتولى حزم SDK ذلك نيابةً عنك.

Phrases
curl -G "https://listingsapi.com/api/v4/review-phrases" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'locationIds=[1800289]' \--data-urlencode 'ratingFilters=[1,2]' \--data-urlencode 'startDate=2026-06-01' \--data-urlencode 'endDate=2026-08-31' \--data-urlencode 'phraseCount=10'
JSON
{  "data": {    "newReviewPhrases": [      {        "reviewPhrase": "long wait",        "phraseStats": {          "stats": [            { "name": "total-reviews", "value": 11, "delta": 37.5, "abs": 3 },            { "name": "overall-rating", "value": 2.9, "delta": -8.4, "abs": -0.27 }          ]        }      }    ]  }}

يوضح total-reviews عدد مرات ظهور العبارة، ويوضح overall-rating ما إذا كانت تلك التقييمات تعبّر عن رضا، ويوضح delta ما إذا كان الوضع يزداد سوءًا. يمثّل abs التغير المطلق إلى جانب النسبة المئوية. لا تتيح دوال العبارات في حزم SDK استخدام ratingFilters أو phraseCount، لذا استخدم استدعاء REST عندما تحتاج إليهما.

5. تلقّي لقطات يومية وأسبوعية عبر webhook

عند إعداد عنوان URL لاستقبال webhooks، يُطلَق review_analytics.daily_snapshot وreview_analytics.weekly_snapshot مرة واحدة لكل موقع في كل فترة. اقرأ كلًا منهما بوصفه ناتج نقطة نهاية النظرة العامة المحسوب لفترة ثابتة: total_reviews هو total-reviews، وnew_reviews_in_period هو new-reviews، وaverage_rating هو overall-rating لتلك الفترة، مع previous_average_rating للفترة السابقة لها. لا تتضمن الحمولة معدل الردود أو المخطط الزمني أو التفصيل حسب المصدر؛ استدعِ نقاط النهاية المذكورة أعلاه عند وصول الحدث إذا احتجت إلى هذه البيانات.

JSON
{  "event": "review_analytics.weekly_snapshot",  "timestamp": "2026-08-24T02:00:00Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "period": "2026-08-17",    "granularity": "weekly",    "total_reviews": 1237,    "new_reviews_in_period": 18,    "average_rating": 4.6123,    "previous_average_rating": 4.5901  }}

يتناسب حجم هذه المجموعة من الأحداث مع عدد مواقعك: وجود 400 موقع يعني ورود 400 حدث يومي دفعة واحدة، وتُسقَط الأحداث التي تتجاوز الحد الأقصى المسموح به في الدقيقة ضمن خطتك، ولا تُوضَع في قائمة انتظار. لذلك، فإن غياب لقطة لا يتيح استنتاجًا قاطعًا. لا تسجّل قيمة صفرية لها مطلقًا؛ بل أعِد قراءة النظرة العامة لتلك الفترة. ترد تعليمات الإعداد في الاستجابة للأحداث باستخدام webhooks.

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