/api/v4/review-phrasesعرض عبارات التقييمات
يعيد العبارات التي يستخدمها العملاء أكثر من غيرها في تقييمات موقع، مع إحصاءات التقييمات الخاصة بكل عبارة.
المعلمات
الاستعلام
| الاسم | النوع | مطلوب | الوصف | الافتراضي |
|---|---|---|---|---|
| locationIds | string | اختياري | JSON array of location IDs to aggregate over, e.g. `[1800289,1800290]`. Query values are JSON-parsed, so a bare single ID also works. Omit to cover every location the key can read. | — |
| siteUrls | string | اختياري | JSON array of review sources to include, e.g. `["maps.google.com"]`. | — |
| startDate | string | اختياري | Only count reviews on or after this date (`YYYY-MM-DD`). | — |
| endDate | string | اختياري | Only count reviews on or before this date (`YYYY-MM-DD`). | — |
| searchString | string | اختياري | Only return phrases containing this substring. | — |
| phraseCount | integer | اختياري | Maximum number of phrases to return. | — |
| categories | string | اختياري | JSON array of interaction categories to include (see the interaction attributes reference). | — |
| ratingFilters | string | اختياري | JSON array of star ratings to include, e.g. `[1,2]` to mine only unhappy reviews. | — |
| responseStatus | string | اختياري | JSON array of `RESPONDED` / `PENDING` to restrict by whether the review has an owner reply. | — |
| sortOrder | string | اختياري | One of `NEWEST_FIRST`, `OLDEST_FIRST`, `LAST_RESPONDED`, `LOWEST_RATING`, `HIGHEST_RATING`. | — |
| category | string | اختياري | Deprecated single-value form of `categories`. Kept for v4 compatibility; prefer `categories`. | — |
| ratingFilter | integer | اختياري | Deprecated single-value form of `ratingFilters`. Kept for v4 compatibility; prefer `ratingFilters`. | — |
الاستجابات
200Phrases with their per-phrase review stats. Response key `newReviewPhrases`, a top-level array.
{ "data": { "newReviewPhrases": [ { "reviewPhrase": "friendly staff", "phraseStats": { "stats": [ { "name": "total-reviews", "value": 46, "delta": 12.5, "abs": 5 }, { "name": "overall-rating", "value": 4.7, "delta": 1.1, "abs": 0.05 } ] } }, { "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 } ] } } ] }}401Unauthenticated, missing or invalid API key.
403The key is valid but not permitted to read one of the requested locations (`SY90003`).
يعيد العبارات المتكررة في نصوص تقييمات موقع، مع إحصاءات التقييمات الخاصة بمجموعة التقييمات التي تحتوي على كل عبارة. وهو يجيب عن السؤال «ما الذي يكرر العملاء ذكره، وهل يذكرونه بإيجابية أم بسلبية؟».
data.newReviewPhrases عبارة عن مصفوفة في المستوى الأعلى، وليس استجابة مقسمة إلى صفحات. استخدم phraseCount لتحديد الحد الأقصى لطولها.
يحتوي كل عنصر على:
reviewPhrase: العبارة نفسها.phraseStats.stats: البنية نفسها{ name, value, delta }الواردة في الحصول على تحليلات التفاعلات، مع احتساب الإحصاءات للتقييمات التي تحتوي على تلك العبارة فقط، بالإضافة إلى حقلabsيحمل التغير المطلق (بدلًا من التغير النسبي المئوي).
كل عوامل التصفية اختيارية ويمكن الجمع بينها، لذا يمكن استخدام هذا المسار أيضًا للبحث النصي في التقييمات: استخدام ratingFilters=[1,2] مع startDate يعطي شكاوى الشهر الماضي، مرتبة حسب مدى تكرارها.
حالة استخدام: لوحة «أبرز الشكاوى»
لإنشاء لوحة شكاوى لموقع، استدعِ هذا المسار مع ratingFilters=[1,2]، وقيمة startDate تعود إلى 90 يومًا مضت، وphraseCount=10. تكون النتيجة العبارات العشر الأكثر ورودًا في التقييمات ذات التقييمات المنخفضة. تتيح لك قراءة phraseStats لـ overall-rating لكل عبارة معرفة ما إذا كانت العبارة حالة شاذة فعلًا أم مجرد مفردات شائعة، ويوضح delta ما إذا كانت تزداد سوءًا.
نظرًا إلى أن قيم الاستعلام تُحلَّل بصيغة JSON، تُدرَج المصفوفات في سلسلة الاستعلام بصيغة JSON: ?ratingFilters=[1,2]&siteUrls=["maps.google.com"].
الاستجابة أعلاه مثال.
curl -X GET 'https://listingsapi.com/api/v4/review-phrases' \ -H "Authorization: API $LISTINGSAPI_KEY"