Listings APIListings API
Masuk

Mengukur kinerja ulasan

Baca KPI ulasan suatu lokasi, buat grafik linimasa harian, bandingkan sumber, gali frasa umum, dan terima ringkasan harian serta mingguan melalui webhook.

Tiga endpoint terkait menyajikan ulasan suatu lokasi dalam bentuk angka: ikhtisar KPI, linimasa harian, dan perincian per sumber. Endpoint keempat mencantumkan frasa yang sering diulang pelanggan. Keempatnya cukup untuk membuat kartu ringkasan kinerja, grafik tren, dan panel keluhan.

1. Baca KPI untuk suatu lokasi

GET /locations/{locationId}/review-analytics-overview mengembalikan empat statistik pada data.interactionsAnalyticsStats.stats. Rentang tanggal bersifat opsional di sini; rentang tersebut mempersempit periode yang digunakan untuk menghitung nilai dan delta.

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 }      ]    }  }}
namevalueMaknanya
total-reviewsjumlahSemua ulasan untuk lokasi tersebut.
new-reviewsjumlahUlasan yang diterima dalam periode tersebut.
overall-rating1 hingga 5Rata-rata peringkat bintang.
review-response-ratepersenProporsi ulasan yang memiliki balasan dari pemilik.

Akun baru yang belum memiliki periode sebelumnya melaporkan delta sebesar 100, jadi jangan menafsirkan delta bulan pertama sebagai pertumbuhan.

2. Ambil linimasa harian untuk grafik

GET .../review-analytics-timeline mengembalikan satu entri per hari pada data.interactionsChartData.data. Selalu sertakan startDate dan endDate, atau layanan akan memilih periodenya sendiri. Tambahkan site (nama host seperti maps.google.com) untuk menampilkan satu sumber secara terpisah.

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

Gambarkan interactionCount sebagai batang dan averageRating sebagai garis. averageRating adalah rata-rata untuk hari tersebut, bukan rata-rata kumulatif, dan nilainya adalah null pada hari tanpa ulasan, jadi biarkan ada celah alih-alih menggambarkan nilai nol.

3. Perinci berdasarkan sumber

GET .../review-analytics-sites-stats mengembalikan satu entri per sumber ulasan pada data.interactionsSitesStats.stats. Gunakan data ini untuk melihat platform mana yang mengubah rata-rata.

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, dan newInteractions masing-masing memuat value dan delta. Satu averageRating.delta negatif sementara yang lainnya tetap menunjukkan masalah pada suatu platform; jika semuanya negatif, masalahnya mengarah ke toko. newInteractions sebesar 0 dengan recency yang sudah berbulan-bulan biasanya berarti koneksi sumber tidak lagi diperbarui, jadi periksa Mencantumkan sumber ulasan untuk suatu lokasi dan tambahkan kembali sumber tersebut melalui Mengedit pengaturan ulasan jika sumber tersebut sudah tidak ada.

4. Temukan frasa yang digunakan pelanggan

GET /review-phrases mengembalikan array biasa pada data.newReviewPhrases, dengan satu entri per frasa yang berulang dan struktur statistik yang sama dengan ikhtisar, yang dihitung hanya dari ulasan yang memuat frasa tersebut. Tambahkan ratingFilters=[1,2] untuk panel keluhan. locationIds dan ratingFilters adalah array JSON dalam string kueri, sehingga keduanya harus dikodekan untuk URL; SDK menangani pengodean tersebut untuk Anda.

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 menunjukkan seberapa sering frasa tersebut muncul, overall-rating menunjukkan apakah ulasan tersebut mengungkapkan kepuasan, dan delta menunjukkan apakah kondisinya memburuk. abs adalah perubahan absolut yang disertakan bersama persentase. Metode frasa dalam SDK tidak menyediakan ratingFilters atau phraseCount, jadi gunakan panggilan REST saat Anda membutuhkannya.

5. Terima ringkasan harian dan mingguan melalui webhook

Jika URL webhook telah dikonfigurasi, review_analytics.daily_snapshot dan review_analytics.weekly_snapshot dipicu sekali per lokasi per periode. Tafsirkan masing-masing sebagai hasil endpoint ikhtisar yang dihitung untuk periode tetap: total_reviews adalah total-reviews, new_reviews_in_period adalah new-reviews, dan average_rating adalah overall-rating untuk periode tersebut, dengan previous_average_rating untuk periode sebelumnya. Tingkat balasan, linimasa, dan perincian per sumber tidak disertakan dalam payload; panggil endpoint di atas saat peristiwa diterima jika Anda membutuhkannya.

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

Volume peristiwa dalam kelompok ini meningkat seiring jumlah lokasi Anda: 400 lokasi berarti 400 peristiwa harian dalam satu lonjakan, dan peristiwa yang melampaui batas per menit paket Anda akan dibuang, bukan dimasukkan ke antrean. Karena itu, tidak adanya ringkasan dapat memiliki lebih dari satu makna. Jangan pernah mencatatnya sebagai nilai nol; baca ulang ikhtisar untuk periode tersebut. Petunjuk penyiapannya ada di Merespons peristiwa dengan webhook.

Langkah berikutnya