Listings APIListings API
Oturum aç

Yorum performansını ölçün

Konumun yorum KPI'larını inceleyin, günlük grafik çizin, kaynakları kıyaslayın, yaygın ifadeleri bulun; webhook ile günlük ve haftalık özetler alın.

Birbiriyle ilişkili 3 uç nokta, bir konumun yorumlarını sayısal olarak açıklar: KPI'lara genel bakış, günlük zaman çizelgesi ve kaynak bazında döküm. 4. uç nokta, müşterilerin tekrarladığı ifadeleri listeler. Bunlar birlikte bir performans kartı, bir eğilim grafiği ve bir şikâyet paneli için yeterlidir.

1. Bir konumun KPI'larını okuyun

GET /locations/{locationId}/review-analytics-overview, data.interactionsAnalyticsStats.stats içinde 4 istatistik döndürür. Tarih aralığı burada isteğe bağlıdır; değerlerin ve değişimlerin hesaplandığı zaman aralığını daraltır.

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Şöyle yorumlayın
total-reviewsadetKonumun tüm yorumları.
new-reviewsadetDönem içinde alınan yorumlar.
overall-rating1 ile 5 arasıOrtalama yıldız puanı.
review-response-rateyüzdeİşletme sahibinin yanıt verdiği yorumların oranı.

Önceki dönemi bulunmayan yeni bir hesapta delta değeri 100 olarak bildirilir; bu nedenle ilk ayın değişimlerini büyüme olarak yorumlamayın.

2. Grafik için günlük zaman çizelgesini alın

GET .../review-analytics-timeline, data.interactionsChartData.data içinde her gün için bir kayıt döndürür. Her zaman startDate ve endDate parametrelerini iletin; aksi takdirde hizmet kendi zaman aralığını seçer. Tek bir kaynağı ayrı olarak çizmek için site parametresini (maps.google.com gibi bir ana makine adı) ekleyin.

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 değerini çubuklarla, averageRating değerini ise çizgiyle gösterin. averageRating, birikimli ortalamayı değil, o günün ortalamasını gösterir ve yorum bulunmayan günlerde null olur; bu nedenle sıfır çizmek yerine boşluk bırakın.

3. Kaynak bazında dökümünü alın

GET .../review-analytics-sites-stats, data.interactionsSitesStats.stats içinde her yorum kaynağı için bir kayıt döndürür. Ortalamayı hangi platformun değiştirdiğini görmek için bunu kullanın.

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 ve newInteractions öğelerinin her biri bir value ve bir delta içerir. Diğerleri sabit kalırken tek bir averageRating.delta değerinin negatif olması bir platforma işaret eder; tümünün negatif olması ise mağazaya işaret eder. newInteractions değerinin 0 olması ve recency tarihinin aylar öncesine ait olması genellikle kaynak bağlantısının güncelliğini yitirdiği anlamına gelir; bu nedenle Bir konumun yorum kaynaklarını listeleyin bölümünü kontrol edin ve kaynak artık yoksa Yorum ayarlarını düzenleyin ile yeniden ekleyin.

4. Müşterilerin kullandığı ifadeleri bulun

GET /review-phrases, data.newReviewPhrases içinde düz bir dizi döndürür; tekrarlanan her ifade için, genel bakışla aynı istatistik yapısına sahip ve yalnızca o ifadeyi içeren yorumlar üzerinden hesaplanan bir kayıt bulunur. Bir şikâyet paneli için ratingFilters=[1,2] ekleyin. locationIds ve ratingFilters, sorgu dizesindeki JSON dizileridir; bu nedenle URL kodlaması uygulanmalıdır; SDK'lar bunu sizin için yapar.

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 ifadenin ne sıklıkta geçtiğini, overall-rating bu yorumların memnuniyet ifade edip etmediğini, delta ise durumun kötüleşip kötüleşmediğini gösterir. abs, yüzde değişiminin yanında verilen mutlak değişimdir. SDK'nın ifade yöntemleri ratingFilters veya phraseCount parametrelerini sunmaz; bu nedenle bunlara ihtiyacınız olduğunda REST çağrısını kullanın.

5. Webhook aracılığıyla günlük ve haftalık anlık görüntüler alın

Bir webhook URL'si yapılandırıldığında review_analytics.daily_snapshot ve review_analytics.weekly_snapshot, her konum için her dönemde bir kez tetiklenir. Her birini, genel bakış uç noktasının sabit bir dönem için hesaplanmış sonucu olarak yorumlayın: o dönem için total_reviews değeri total-reviews, new_reviews_in_period değeri new-reviews ve average_rating değeri overall-rating olur; bir önceki dönem için de previous_average_rating bulunur. Yanıt oranı, zaman çizelgesi ve kaynak bazında döküm, veri yükünde bulunmaz; bunlara ihtiyacınız varsa olay geldiğinde yukarıdaki uç noktaları çağırın.

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  }}

Bu olay ailesinin hacmi konum sayınızla orantılı olarak artar: 400 konum, bir anda gelen 400 günlük olay anlamına gelir ve planınızın dakika başına sınırını aşan olaylar kuyruğa alınmaz, düşürülür. Bu nedenle eksik bir anlık görüntünün ne anlama geldiği belirsizdir. Bunun için asla sıfır kaydetmeyin; bunun yerine o dönemin genel bakışını yeniden okuyun. Kurulum bilgileri Webhook'larla olaylara tepki verin bölümündedir.

Sonraki adımlar