Ulasan

Semua endpoint ulasan dengan contoh cURL, Python, dan Node: sumber, pengaturan, daftar, rekap, detail, balas, edit, arsip, frasa, dan analitik.

Ulasan adalah penilaian bintang dan komentar yang diberikan pelanggan di Google, Facebook, dan Yelp. API menyimpan satu salinan setiap ulasan, memungkinkan Anda membalas, dan menghitung analitik ulasan. Path REST menggunakan reviews; kunci respons dan judul halaman referensi menggunakan interactions, nama internal lama untuk objek yang sama. Panduan ini menggunakan istilah ulasan secara konsisten. Operasi baca memerlukan kunci Read (baca). Membalas, mengedit, mengarsipkan, dan mengubah pengaturan memerlukan kunci Write (tulis); penggunaan kunci Read pada operasi tulis mengembalikan 400 dengan SY90016.

Sekilas tentang endpoint

Daftar sumber ulasan yang diizinkan oleh paket Anda

GET /reviews/site-config mengembalikan katalog platform ulasan yang berhak diakses oleh akun. Endpoint ini tidak menerima parameter dan cakupannya adalah satu akun, jadi simpan hasilnya dalam cache alih-alih memanggilnya untuk setiap lokasi. Nilai siteUrl adalah hostname yang diterima oleh semua filter lain dalam resource ini.

curl https://listingsapi.com/api/v4/reviews/site-config \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionSiteConfig": [      { "site": "Google", "siteUrl": "maps.google.com" },      { "site": "Facebook", "siteUrl": "facebook.com" },      { "site": "Yelp", "siteUrl": "yelp.com" }    ]  }}

Baca data.interactionSiteConfig[]. Contoh ini menggunakan akun paket Launch; kumpulan sumber yang tersedia bergantung pada paket dan sektor industri. Gunakan siteUrl untuk filter siteUrls pada endpoint daftar dan untuk siteUrls[].name saat mengedit pengaturan.

Daftar sumber yang dikonfigurasi untuk suatu lokasi

GET /locations/{locationId}/reviews/settings mengembalikan satu entri untuk setiap platform yang didukung paket, beserta URL tempat ulasan diambil. Endpoint ini menyediakan operasi baca yang berpasangan dengan endpoint edit di bawah. Path menerima id base64 atau angka biasa.

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

{  "data": {    "interactionsSetting": {      "siteSettings": [        { "name": "maps.google.com", "url": null },        { "name": "facebook.com", "url": null },        { "name": "yelp.com", "url": null }      ]    }  }}

Baca data.interactionsSetting.siteSettings[]. url yang tidak bernilai null berarti platform terhubung dan ulasan sedang diambil dari halaman tersebut. url yang bernilai null berarti platform tersedia tetapi belum dikonfigurasi. Google dan Facebook terisi secara otomatis saat Anda menghubungkan akun tersebut melalui OAuth dan tidak dapat ditimpa oleh endpoint edit. Yelp harus disebutkan secara eksplisit.

Edit pengaturan ulasan suatu lokasi

POST /locations/reviews/settings/edit mengatur sumber yang dipantau untuk suatu lokasi dan penilaian bintang yang dianggap positif. Field ditempatkan langsung di body, bukan di dalam pembungkus input. Menambahkan sumber akan memasukkan proses pengambilan data ke antrean, sehingga ulasan dari situs baru tersebut akan masuk kemudian, bukan dalam respons ini.

curl -X POST https://listingsapi.com/api/v4/locations/reviews/settings/edit \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "locationId": "TG9jYXRpb246MTgwMDI4OQ==",  "positiveInteractionThreshold": 4,  "siteUrls": [    { "name": "maps.google.com", "url": null },    { "name": "yelp.com", "url": "https://www.yelp.com/biz/blue-bottle-coffee-oakland" }  ]}'

{  "data": {    "editInteractionsSetting": {      "errors": null,      "interactionSetting": {        "locationId": "1800289",        "positiveInteractionThreshold": 4,        "siteSettings": [          { "name": "maps.google.com", "url": null, "monitored": true, "canRespond": true },          { "name": "yelp.com", "url": "https://www.yelp.com/biz/blue-bottle-coffee-oakland", "monitored": true, "canRespond": false }        ]      }    }  }}

Baca data.editInteractionsSetting.interactionSetting.siteSettings[] untuk mengetahui pilihan yang tersimpan. monitored menunjukkan bahwa sumber aktif; canRespond menunjukkan apakah balasan pemilik dapat dikirim ke sumber tersebut melalui API. Sumber yang ditolak oleh validasi, seperti URL yang tidak dapat dijangkau atau situs di luar cakupan paket, dikembalikan dalam errors tanpa mengubah pengaturan, jadi periksa errors saat menerima 200. SDK akan memunculkan ValidationError dalam kasus tersebut.

Menampilkan daftar ulasan untuk suatu lokasi

GET /locations/{locationId}/reviews adalah koneksi cursor di data.interactions, dengan urutan terbaru terlebih dahulu. Nilai default first adalah 20, sehingga satu panggilan tidak pernah mencakup seluruh riwayat. Filter array berupa string JSON dalam query string dan harus dikodekan untuk URL; contoh cURL menggunakan -G dengan --data-urlencode untuk keperluan tersebut.

Ditambah category, categories, dan ratingFilter bernilai tunggal yang bersifat opsional dan tercantum di halaman referensi.

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=25'

{  "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",            "type": "Review",            "responded": false,            "responseCount": 0,            "canRespond": true,            "permalink": "https://maps.google.com/maps?cid=..."          },          "cursor": "SW50ZXJhY3Rpb246MV8xNTU0..."        }      ],      "totalCount": 425    }  }}

Baca edges[].node. id adalah nilai yang Anda teruskan saat membalas, dan canRespond menunjukkan apakah sumber tersebut menerima balasan pemilik. totalCount adalah jumlah kecocokan di seluruh kumpulan hasil, bukan hanya di halaman ini. Hentikan paginasi saat hasNextPage bernilai false atau suatu halaman mengembalikan edges yang kosong; batas halaman yang tepat berada pada ulasan terlama akan diikuti oleh satu halaman kosong.

Memeriksa semua lokasi dengan agregasi

GET /rollup_interactions adalah koneksi cursor yang sama, yang mencakup semua lokasi yang dapat diakses oleh kunci tersebut, di data.rollupInteractions, dengan locationId numerik pada setiap node. Koneksi ini menerima filter yang sama dengan daftar per lokasi. Tidak ada filter lokasi; argumen locationIds diabaikan, bukan ditolak. Kedua SDK belum menyediakan wrapper untuk endpoint ini, sehingga contoh menggunakan requests dan fetch.

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'

{  "data": {    "rollupInteractions": {      "pageInfo": { "hasNextPage": true, "hasPreviousPage": false },      "edges": [        {          "node": {            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",            "source": "maps.google.com",            "content": "Excellent service, highly recommend.",            "rating": 5,            "responded": false,            "canRespond": true,            "locationId": 1800289          },          "cursor": "SW50ZXJhY3Rpb246OWUyNmQyYTg="        }      ],      "totalCount": 1284    }  }}

Kelompokkan node berdasarkan locationId, yaitu databaseId toko tersebut. pageInfo pada agregasi mungkin tidak menyertakan endCursor, jadi gunakan cursor dari edge terakhir sebagai after; kedua nilai tersebut setara. Batasi eksekusi terjadwal dengan startDate dan endDate alih-alih membaca ulang riwayat, dan patuhi Retry-After saat menerima 429.

Mengambil ulasan berdasarkan id

GET /reviewDetails mengembalikan salinan terbaru dari ulasan yang tersimpan tanpa paginasi. Respons berupa array biasa di data.interactionDetails.interactions, tanpa edges atau pageInfo, dan setiap ulasan menyertakan responses masing-masing. Gunakan endpoint ini untuk memuat ulang data dalam daftar pantauan dan menemukan responseId yang Anda perlukan untuk mengedit atau mengarsipkan.

curl -G "https://listingsapi.com/api/v4/reviewDetails" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'interactionIds=["b2fa765e-c62b-4e0b-b1d6-1c67c855f5e0"]'

{  "data": {    "interactionDetails": {      "interactions": [        {          "id": "b2fa765e-c62b-4e0b-b1d6-1c67c855f5e0",          "source": "maps.google.com",          "content": "Great place for dessert!",          "rating": 5,          "responded": true,          "responseCount": 1,          "canRespond": true,          "responses": [            {              "id": "2090753a-ece6-4837-8336-8494ad308523",              "content": "Thank you so much for the kind words!",              "interactionStatus": "CONFIRMED",              "editedResponse": false            }          ]        }      ]    }  }}

responses[].id adalah responseId untuk endpoint pengeditan dan pengarsipan. Penggunaan id dari akun lain menghasilkan respons 200 dengan interactionDetails: null dan error SY90001, jadi periksa keberadaan null sebelum mengakses elemen berdasarkan indeks.

Field ulasan dan balasan

Referensi atribut adalah halaman khusus dokumentasi yang mencantumkan semua field pada objek ulasan dan objek balasan. Field yang paling sering Anda gunakan:

Setiap balasan dalam responses[] memuat id, content, authorName, date, interactionStatus, editedResponse, respondedWith (id templat), dan remarks (detail kegagalan). interactionStatus beralih melalui status berikut:

Kirim balasan pemilik

POST /locations/reviews/respond mengirim balasan publik di platform sumber. Field ditempatkan langsung di body. Balasan langsung diterima dan dikirim secara asinkron, sehingga interactionStatus dimulai dengan CREATED. Periksa canRespond pada ulasan terlebih dahulu.

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "interactionId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responseContent": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!"}'

{  "data": {    "respondToInteraction": {      "interaction": {        "id": "2090753a-ece6-4837-8336-8494ad308523",        "interactionId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",        "content": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!",        "interactionStatus": "CREATED",        "editedResponse": false      },      "errors": null    }  }}

Simpan interaction.id: nilai ini adalah responseId untuk mengedit dan mengarsipkan. Balasan yang ditolak dikembalikan sebagai 200 dengan errors terisi di dalam data.respondToInteraction, jadi baca body; SDK memunculkan ValidationError. Baca ulang ulasan berdasarkan ID setelah menunggu sebentar untuk melihat balasan mencapai COMPLETED atau CONFIRMED.

Edit balasan

POST /locations/reviews/respond/edit mengubah teks balasan yang ada. Hasil pengeditan dikirim ulang ke platform, sehingga interactionStatus kembali ke CREATED dan editedResponse menjadi true setelah perubahan diterapkan di platform. Utamakan cara ini daripada mengarsipkan dan mengirim ulang pada platform yang mengizinkan satu balasan.

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond/edit \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "reviewId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responseId": "2090753a-ece6-4837-8336-8494ad308523",  "responseContent": "Thank you again: we have updated our reply to include our new store hours."}'

{  "data": {    "editResponse": {      "status": "true",      "reviewId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",      "responseId": "2090753a-ece6-4837-8336-8494ad308523"    }  }}

status adalah string "true" saat pengeditan diterima. Konfirmasikan teks baru melalui panggilan untuk mengambil detail dan periksa interactionStatus balasan.

Arsipkan balasan

POST /locations/reviews/respond/archive menghapus balasan dari responses ulasan yang dilacak di sisi kami. Ini merupakan penghapusan lunak: balasan yang sudah tayang di Google, Yelp, atau Facebook tetap ada di sana. Gunakan operasi ini untuk menghapus draf yang gagal atau sudah digantikan; gunakan operasi edit untuk balasan yang sudah dipublikasikan.

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond/archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "responseId": "2090753a-ece6-4837-8336-8494ad308523" }'

{  "data": {    "archiveResponse": {      "status": "true"    }  }}

Setelah pengarsipan, responseCount ulasan berkurang dan responded mencerminkan balasan yang tersisa.

Ambil daftar frasa yang diulang pelanggan

GET /review-phrases mengembalikan array biasa pada data.newReviewPhrases, dengan satu entri per frasa yang berulang, masing-masing berisi statistik yang dihitung hanya dari ulasan yang memuat frasa tersebut. Hasilnya tidak menggunakan paginasi; batasi dengan phraseCount. Setiap filter bersifat opsional dan dapat digabungkan, sehingga ratingFilters=[1,2] dengan startDate menghasilkan keluhan dari kuartal lalu.

Ditambah categories yang opsional serta category dan ratingFilter bernilai tunggal yang sudah usang, yang tercantum di halaman referensi.

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'

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

total-reviews menunjukkan seberapa sering frasa muncul, overall-rating adalah peringkat rata-rata ulasan tersebut, delta adalah persentase perubahan dibandingkan periode sebelumnya, dan abs adalah perubahan absolut. 403 dengan SY90003 berarti kunci tidak dapat membaca salah satu lokasi yang diminta.

Baca KPI ulasan untuk suatu lokasi

GET /locations/{locationId}/review-analytics-overview mengembalikan empat statistik pada data.interactionsAnalyticsStats.stats. Rentang tanggal bersifat opsional; rentang ini mempersempit periode yang digunakan untuk menghitung nilai dan deltanya. Setiap delta adalah persentase perubahan dibandingkan periode sebelumnya yang berdurasi sama.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-overview?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

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

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

Ambil linimasa ulasan harian

GET /locations/{locationId}/review-analytics-timeline mengembalikan satu entri per hari di data.interactionsChartData.data. Sertakan startDate dan endDate setiap kali rentang waktu grafik perlu ditentukan; jika keduanya dihilangkan, layanan akan memilih rentang waktunya sendiri. Tambahkan site untuk menampilkan satu sumber secara terpisah.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-timeline?startDate=2026-08-01&endDate=2026-08-31&site=maps.google.com" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "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. Rata-rata tersebut hanya untuk hari itu, bukan rata-rata berjalan, dan nilainya adalah null pada hari tanpa ulasan, jadi biarkan ada celah alih-alih menggambar nilai nol.

Rinci analitik ulasan berdasarkan sumber

GET /locations/{locationId}/review-analytics-sites-stats mengembalikan satu entri per sumber ulasan di data.interactionsSitesStats.stats. Gunakan untuk mengetahui platform mana yang mengubah rata-rata.

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"

{  "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",          "baseRating": 4.5,          "baseInteractions": 388,          "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; baseRating dan baseInteractions adalah nilai pada awal periode yang menjadi titik acuan pengukuran delta. recency adalah stempel waktu ulasan terbaru, atau null jika sumber tersebut belum pernah mengembalikan ulasan. newInteractions bernilai 0 dengan recency yang sudah berusia beberapa bulan biasanya berarti koneksi sumber tidak lagi diperbarui, jadi periksa sumber lokasi tersebut.

Kesalahan yang akan Anda temui

Operasi tulis juga dapat mengembalikan 200 dengan errors yang terisi di dalam data.<op>, jadi baca body respons setiap operasi tulis. Daftar lengkapnya ada di Kode kesalahan.

Langkah berikutnya

• Ambil ulasan: buat antrean ulasan yang menunggu penanganan dan terima pemberitahuan melalui webhook.
• Tanggapi ulasan: balas, konfirmasi, edit, arsipkan.
• Analitik ulasan: kartu skor, grafik, panel keluhan, cuplikan harian.
• Analitik: metrik profil Google, Facebook, dan Bing untuk lokasi yang sama.
• Halaman utama referensi: Ulasan. SDK: Ulasan Python, Ulasan Node.