اجلب التقييمات لموقع واحد أو لحسابك بالكامل

اعرض أحدث تقييمات موقع، وصفِّ التقييمات المنخفضة بلا رد، وتنقّل بين الصفحات بالمؤشرات، واجلب تقييمات جميع مواقع الحساب، وتلقَّ إشعارات عبر webhook.

تُسمّى التقييمات interactions في API. تُعاد جميع التقييمات من Google أو Facebook أو Yelp في قائمة واحدة لكل موقع، وفي تجميع واحد للحساب، بحيث يغطي تكامل واحد كل مصدر تربطه.

1. اعرض أحدث التقييمات لموقع واحد

GET /locations/{locationId}/reviews هو اتصال يعتمد على مؤشرات التصفح عند data.interactions. تأتي النتائج من الأحدث إلى الأقدم، والقيمة الافتراضية لـ first هي 20، لذا لا يمثّل استدعاء واحد السجل الكامل مطلقًا. يقبل المسار المعرّف بترميز base64 أو الرقم العادي.

Latest reviews

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews?first=10" \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "interactions": {      "pageInfo": { "hasNextPage": true, "endCursor": "SW50ZXJhY3Rpb246MV8xNTU0..." },      "edges": [        {          "node": {            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",            "source": "maps.google.com",            "content": "nice place for family together",            "authorName": "vaibhav nakate",            "rating": 5,            "date": "2019-04-02T22:11:13.036997+00:00",            "responded": false,            "responseCount": 0,            "canRespond": true,            "permalink": "https://maps.google.com/maps?cid=..."          },          "cursor": "SW50ZXJhY3Rpb246MV8xNTU0..."        }      ],      "totalCount": 425    }  }}

اقرأ data.interactions.edges[].node. id هو UUID عادي، وليس معرّف Relay بترميز base64، وهو ما تمرّره عند الرد. totalCount هو عدد النتائج المطابقة في مجموعة النتائج بأكملها، وليس في هذه الصفحة. يبيّن canRespond ما إذا كان ذلك المصدر يقبل ردود المالك عبر API.

2. صفِّ النتائج لإظهار التقييمات المنخفضة التي لم يُرَدّ عليها

تُمرَّر مرشّحات المصفوفات كسلاسل نصية بصيغة JSON ضمن سلسلة الاستعلام: يُبقي ratingFilters=[1,2] التقييمات ذات النجمة الواحدة والنجمتين، ويُبقي responseStatus=["PENDING"] التقييمات التي ليس لها رد من المالك. يجب ترميز الأقواس وعلامات الاقتباس بترميز URL، لذا يستخدم مثال cURL الخيار -G مع --data-urlencode، مما يرمّز كل قيمة ويُلحقها بعنوان URL نيابةً عنك. سلسلة الاستعلام الحرفية المكافئة هي ratingFilters=%5B1%2C2%5D&responseStatus=%5B%22PENDING%22%5D.

Unanswered 1-2 stars

curl -G "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'ratingFilters=[1,2]' \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'sortOrder=["NEWEST_FIRST"]' \--data-urlencode 'first=50'

المرشّحات التي يمكنك الجمع بينها:

المعامل	القيم	ملاحظات
`siteUrls`	`["maps.google.com"]`, `["facebook.com"]`, `["yelp.com"]`	أسماء المضيفين من عرض مصادر التقييمات لحساب.
`ratingFilters`	`[1,2]` وما إلى ذلك	التقييمات بالنجوم التي تريد الإبقاء عليها.
`responseStatus`	`["PENDING"]` أو `["RESPONDED"]`	ما إذا كان هناك رد من المالك.
`sortOrder`	`["NEWEST_FIRST"]`, `["OLDEST_FIRST"]`, `["LAST_RESPONDED"]`	الترتيب الافتراضي هو من الأحدث إلى الأقدم.
`startDate`, `endDate`	`YYYY-MM-DD`	سلاسل نصية عادية، وليست بصيغة JSON.
`searchString`	نص حر	بحث نصي كامل في متن التقييم.

3. تنقّل بين الصفحات باستخدام مؤشرات التصفح

أعِد تمرير pageInfo.endCursor بوصفه after. توقّف عندما تكون قيمة hasNextPage هي false أو عندما تُرجع صفحة مصفوفة edges فارغة؛ فعندما تقع حدود الصفحة عند أقدم تقييم، تتبعها صفحة فارغة واحدة. يمكن لكلتا حزمتَي SDK قراءة الصفحات نيابةً عنك.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews?first=50&after=SW50ZXJhY3Rpb246MV8xNTU0..." \-H "Authorization: API $LISTINGSAPI_KEY"

يُحتسب كل طلب ضمن حد معدل الطلبات المسموح لك به، ويتطلب موقع يحتوي على 425 تقييمًا، عند استخدام first=50، تسعة استدعاءات. عند تلقي 429، انتظر Retry-After قبل طلب الصفحة التالية. للمزامنة المجدولة، حدّد نطاق التشغيل باستخدام startDate وendDate بدلًا من إعادة قراءة السجل. راجع حدود معدل الطلبات.

4. اجلب التقييمات من الحساب بالكامل باستخدام التجميع

يُرجع GET /rollup_interactions العقد نفسها عبر جميع المواقع التي يتيح المفتاح الاطلاع عليها، عند data.rollupInteractions، مع locationId في كل عقدة. يقبل المرشّحات نفسها بالإضافة إلى tag، الذي تكون قيمته الافتراضية all. لا يوجد مرشّح للموقع؛ جمّع النتائج بحسب locationId بنفسك. لا توفّر أيٌّ من حزمتَي SDK دالةً لاستدعاء نقطة النهاية هذه حتى الآن، لذا تستدعيها أمثلة SDK باستخدام requests وfetch.

Account-wide pending

curl -G "https://listingsapi.com/api/v4/rollup_interactions" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'sortOrder=["NEWEST_FIRST"]' \--data-urlencode 'first=50'

لكل عقدة البنية نفسها الواردة في الخطوة 1 بالإضافة إلى locationId رقمي، وهو databaseId الخاص بالمتجر. قد لا يتضمن pageInfo الخاص بالتجميع الحقل endCursor، لذا استخدم cursor الخاص بآخر عنصر edge بوصفه after؛ فالقيمتان متكافئتان.

5. اجلب التفاصيل الكاملة باستخدام المعرّف

عندما تكون لديك معرّفات مخزّنة، يُرجع GET /reviewDetails نسخًا محدّثة دون تقسيمها إلى صفحات. interactionIds هو مصفوفة JSON، مرمّزة بترميز URL مثل المرشّحات الأخرى. الاستجابة عبارة عن مصفوفة عادية عند data.interactionDetails.interactions، ويتضمن كل تفاعل responses الخاص به.

Details by id

curl -G "https://listingsapi.com/api/v4/reviewDetails" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'interactionIds=["9e26d2a8-a6ed-42ea-8454-47d1c92ea841"]'

JSON

{  "data": {    "interactionDetails": {      "interactions": [        {          "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",          "responded": true,          "responseCount": 1,          "responses": [            {              "id": "2090753a-ece6-4837-8336-8494ad308523",              "content": "Thank you so much for the kind words!",              "interactionStatus": "CONFIRMED"            }          ]        }      ]    }  }}

يؤدي استخدام معرّف من حساب آخر إلى إرجاع 200 مع interactionDetails: null وخطأ SY90001، لذا تحقّق من null قبل الوصول إلى العناصر باستخدام الفهرس.

6. تلقَّ أحداث webhook بدلًا من الاستقصاء الدوري

عند إعداد عنوان URL الخاص بـ webhooks، يُطلَق حدث interaction.review عند استيعاب تقييم أو تغيّره. تقع حقول التقييم ضمن data.interaction، وليس مباشرةً ضمن data، وdata.interaction.id هو UUID نفسه الذي تُرجعه القائمة.

تنبيهان. تُمرَّر قيمة location_id في هذا الحدث دون توحيد صيغتها: فقد تكون سلسلة نصية رقمية أو null، لذا حوّلها بنفسك بدلًا من الاعتماد على نوعها. وتصل قيمة id نفسها مجددًا كلما تغيّر التقييم، لذا تعامل مع الحدث بوصفه إشارة لإعادة قراءة التقييم، وليس بوصفه عملية إدراج لمرة واحدة. يجري التسليم بمحاولة واحدة دون إعادة المحاولة، لذا واصل إجراء الفحص الدوري الوارد في الخطوة 4 بوصفه إجراءً احتياطيًا. ترد تعليمات الإعداد في الاستجابة للأحداث باستخدام webhooks.

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

الرد على التقييمات: رُدّ على التقييمات المعلّقة التي عثرت عليها للتو، ثم عدّل الرد أو أرشفه.
تحليلات التقييمات: التقييم وعدد التقييمات ومعدل الرد للموقع نفسه.
المرجع: سرد التفاعلات، الحصول على التفاعلات المجمّعة، الحصول على التفاعلات حسب المعرّفات، سمات التفاعلات.
حزم SDK: التقييمات في Python، التقييمات في Node.