المراجعات

اجلب التقييمات وردّ عليها وحلّلها باستخدام حزمة SDK ‏listingsapi-js.

التقييمات (وتُسمى "interactions" في API) هي تقييمات بالنجوم وملاحظات نصية حرة تُجمع من Google وFacebook وYelp. تتوفر جميع أساليب التقييمات على نسخة العميل ListingsAPI. تؤدي عمليات الكتابة التي تفشل على جانب الخادم إلى طرح ValidationError، لذا لا تحتاج أبدًا إلى التحقق من علامات success في القيم المُعادة.

fetchInteractions

اجلب تقييمات موقع باستخدام عوامل تصفية اختيارية وتقسيم إلى صفحات قائم على المؤشرات. تُرمَّز معرّفات المواقع الرقمية تلقائيًا.

// Single pageconst result = await client.fetchInteractions(16808, {first:         25,startDate:     '2026-01-01',endDate:       '2026-06-30',ratingFilters: [1, 2],}); if (!Array.isArray(result)) {console.log(result.interactions);   // Interaction[]console.log(result.totalCount);     // number | undefinedconsole.log(result.pageInfo);       // { hasNextPage, hasPreviousPage, startCursor, endCursor }} // All reviews at once, returns a flat Interaction[]const all = await client.fetchInteractions(16808, {fetchAll:  true,startDate: '2026-01-01',});

الخيارات

القيم المُعادة

بدون fetchAll، يُعاد كائن InteractionResponse: success، وinteractions (Interaction[])، وpageInfo (hasNextPage، hasPreviousPage، startCursor، endCursor)، وtotalCount عندما تُبلغ API عنه، وraw (البيانات التي لم تُحلَّل). مع fetchAll: true، يُعاد Interaction[] مسطحًا. يتضمن كل Interaction الحقول id، وcontent، وrating، وsiteName، وsiteUrl، وreviewerName، وpublishedAt، وcategory، وresponses.

fetchReviewDetails

اجلب معلومات تفصيلية لتقييمات محددة باستخدام معرّف التفاعل. إذا كانت مصفوفة الإدخال فارغة، تتوقف المعالجة ويُعاد كائن فارغ دون إجراء اتصال بالشبكة.

const details = await client.fetchReviewDetails(['interaction-uuid-1','interaction-uuid-2',]);

respondToReview

انشر ردًا على تقييم. يُرسَل الرد إلى الدليل المصدر بصورة غير متزامنة.

await client.respondToReview('interaction-uuid','Thank you for the feedback! We hope to see you again soon.',);

editReviewResponse

عدّل ردًا موجودًا.

await client.editReviewResponse('review-uuid','response-uuid','Updated response text.',);

archiveReviewResponse

أرشِف ردًا (أخفِه).

await client.archiveReviewResponse('response-uuid');

تحليلات التقييمات

تأخذ أساليب التحليلات الثلاثة جميعها معرّف موقع بالإضافة إلى نطاق { startDate, endDate } اختياري (YYYY-MM-DD)، وتُعيد كائن ReviewAnalytics تختلف بنيته حسب نقطة النهاية.

fetchReviewAnalyticsOverview

إحصاءات عامة لفترة زمنية: تجميعات التقييم وعدد التقييمات للموقع.

const overview = await client.fetchReviewAnalyticsOverview(16808, {startDate: '2026-01-01',endDate:   '2026-06-30',});console.log(overview);

fetchReviewAnalyticsTimeline

أعداد التقييمات والتقييمات بمرور الوقت، وهي مناسبة للتمثيل البياني.

const timeline = await client.fetchReviewAnalyticsTimeline(16808, {startDate: '2026-01-01',endDate:   '2026-06-30',});

fetchReviewAnalyticsSitesStats

توزيع التقييمات حسب الموقع المصدر (Google، Facebook، Yelp).

const siteStats = await client.fetchReviewAnalyticsSitesStats(16808, {startDate: '2026-01-01',endDate:   '2026-06-30',});

fetchReviewPhrases

تحليل العبارات والمشاعر عبر موقع واحد أو أكثر خلال فترة زمنية. يأخذ كائن خيارات واحدًا؛ locationIds مطلوب، وتؤدي القائمة الفارغة إلى إرجاع [] دون إجراء اتصال بالشبكة.

const phrases = await client.fetchReviewPhrases({locationIds: ['TG9jYXRpb246MTY4MDg=', 'TG9jYXRpb246MTY4MDk='],startDate:   '2026-01-01',endDate:     '2026-06-30',siteUrls:    ['maps.google.com'],}); for (const p of phrases) {console.log(p.phrase, p.count, p.sentiment);}

الخيارات

إعدادات التقييمات

fetchReviewSettings

اجلب إعدادات مصادر التقييمات لموقع.

const settings = await client.fetchReviewSettings(16808);console.log(settings);

editReviewSettings

عيّن عناوين URL لمصادر التقييمات التي تُتابَع لموقع أو حدّثها. كل عنصر هو ReviewSiteUrl يتضمن name وurl.

await client.editReviewSettings(16808, [{ name: 'Google', url: 'https://www.google.com/maps/place/acme-dental' },{ name: 'Yelp',   url: 'https://www.yelp.com/biz/acme-dental-new-york' },]);

fetchReviewSiteConfig

اجلب قائمة مصادر التقييمات المؤهلة على مستوى الحساب بأكمله. لا يأخذ أي وسائط ويُعيد ReviewSiteConfig[].

const config = await client.fetchReviewSiteConfig();

موارد ذات صلة

• المواقع: ابحث عن معرّفات المواقع
• التحليلات: تحليلات الملفات التجارية على Google وBing وFacebook
• حالات الاستخدام: خطوات عملية لمراقبة التقييمات والرد عليها دفعة واحدة