Listings APIListings API
Masuk

Ambil ulasan untuk satu lokasi atau seluruh akun Anda

Lihat ulasan terbaru per lokasi, filter peringkat rendah tanpa balasan, gunakan paginasi kursor, telusuri seluruh akun, dan terima notifikasi webhook.

Ulasan disebut interactions dalam API. Setiap ulasan dari Google, Facebook, atau Yelp dikembalikan dalam satu daftar per lokasi dan satu rekap untuk akun, sehingga satu integrasi mencakup setiap sumber yang Anda hubungkan.

1. Tampilkan ulasan terbaru untuk satu lokasi

GET /locations/{locationId}/reviews adalah koneksi cursor di data.interactions. Hasil diurutkan dari yang terbaru, dan nilai default first adalah 20, sehingga satu panggilan tidak pernah mencakup seluruh riwayat. Path menerima id base64 atau angka biasa.

Latest reviews
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews?first=10" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "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",            "responded": false,            "responseCount": 0,            "canRespond": true,            "permalink": "https://maps.google.com/maps?cid=..."          },          "cursor": "SW50ZXJhY3Rpb246MV8xNTU0..."        }      ],      "totalCount": 425    }  }}

Baca data.interactions.edges[].node. id adalah UUID biasa, bukan id Relay base64, dan itulah yang Anda kirim saat membalas. totalCount adalah jumlah hasil yang cocok di seluruh kumpulan hasil, bukan hanya halaman ini. canRespond menunjukkan apakah sumber tersebut menerima balasan pemilik melalui API.

2. Filter ulasan berperingkat rendah yang belum dibalas

Filter array berupa string JSON dalam query string: ratingFilters=[1,2] hanya menyertakan ulasan berbintang 1 dan 2, dan responseStatus=["PENDING"] hanya menyertakan ulasan tanpa balasan pemilik. Tanda kurung siku dan tanda kutip harus dikodekan untuk URL, sehingga contoh cURL menggunakan -G dengan --data-urlencode, yang mengodekan setiap nilai dan menambahkannya ke URL untuk Anda. Query string literal yang setara adalah ratingFilters=%5B1%2C2%5D&responseStatus=%5B%22PENDING%22%5D.

Unanswered 1-2 stars
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=50'

Filter yang dapat Anda gabungkan:

ParameterNilaiCatatan
siteUrls["maps.google.com"], ["facebook.com"], ["yelp.com"]Hostname dari Tampilkan sumber ulasan untuk suatu akun.
ratingFilters[1,2] dan seterusnyaPeringkat bintang yang akan disertakan.
responseStatus["PENDING"] atau ["RESPONDED"]Apakah ada balasan pemilik.
sortOrder["NEWEST_FIRST"], ["OLDEST_FIRST"], ["LAST_RESPONDED"]Urutan default adalah dari yang terbaru.
startDate, endDateYYYY-MM-DDString biasa, bukan JSON.
searchStringteks bebasPencarian teks lengkap pada isi ulasan.

3. Telusuri halaman menggunakan cursor

Kirim kembali pageInfo.endCursor sebagai after. Berhenti ketika hasNextPage bernilai false atau suatu halaman mengembalikan array edges kosong; jika batas halaman tepat pada ulasan terlama, halaman berikutnya akan kosong. Kedua SDK dapat membaca halaman-halaman tersebut untuk Anda.

Next page
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews?first=50&after=SW50ZXJhY3Rpb246MV8xNTU0..." \-H "Authorization: API $LISTINGSAPI_KEY"

Setiap permintaan diperhitungkan dalam batas laju Anda, dan lokasi dengan 425 ulasan memerlukan 9 panggilan jika menggunakan first=50. Saat menerima 429, tunggu sesuai Retry-After sebelum mengambil halaman berikutnya. Untuk sinkronisasi terjadwal, batasi cakupan proses dengan startDate dan endDate alih-alih membaca ulang riwayat. Lihat Batas laju.

4. Telusuri seluruh akun menggunakan rekap

GET /rollup_interactions mengembalikan node yang sama dari semua lokasi yang dapat diakses oleh kunci tersebut, di data.rollupInteractions, dengan locationId pada setiap node. Endpoint ini menerima filter yang sama ditambah tag, yang nilai default-nya adalah all. Tidak ada filter lokasi; kelompokkan sendiri berdasarkan locationId. Kedua SDK belum menyediakan pembungkus untuk endpoint ini, sehingga contoh SDK memanggilnya dengan requests dan fetch.

Account-wide pending
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'

Setiap node memiliki struktur yang sama seperti pada langkah 1 ditambah locationId numerik, yaitu databaseId toko tersebut. pageInfo pada rekap mungkin tidak menyertakan endCursor, jadi gunakan cursor dari edge terakhir sebagai after; kedua nilai tersebut setara.

5. Ambil detail lengkap berdasarkan id

Jika Anda telah menyimpan id, GET /reviewDetails mengembalikan salinan terbaru tanpa paginasi. interactionIds adalah array JSON yang dikodekan untuk URL seperti filter lainnya. Respons berupa array biasa di data.interactionDetails.interactions, dan setiap interaction menyertakan responses miliknya.

Details by id
curl -G "https://listingsapi.com/api/v4/reviewDetails" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'interactionIds=["9e26d2a8-a6ed-42ea-8454-47d1c92ea841"]'
JSON
{  "data": {    "interactionDetails": {      "interactions": [        {          "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",          "responded": true,          "responseCount": 1,          "responses": [            {              "id": "2090753a-ece6-4837-8336-8494ad308523",              "content": "Thank you so much for the kind words!",              "interactionStatus": "CONFIRMED"            }          ]        }      ]    }  }}

Id dari akun lain mengembalikan 200 dengan interactionDetails: null dan error SY90001, jadi periksa keberadaan null sebelum mengakses elemen berdasarkan indeks.

6. Terima peristiwa webhook alih-alih melakukan polling

Jika URL webhook telah dikonfigurasi, peristiwa interaction.review dipicu saat ulasan masuk ke sistem atau berubah. Field ulasan berada di bawah data.interaction, bukan langsung di bawah data, dan data.interaction.id adalah UUID yang sama dengan yang dikembalikan oleh daftar.

Dua hal yang perlu diperhatikan. location_id pada peristiwa ini diteruskan tanpa dinormalisasi: nilainya bisa berupa string numerik atau null, jadi konversikan sendiri alih-alih mengandalkan tipenya. Dan id yang sama diterima kembali setiap kali ulasan berubah, jadi perlakukan peristiwa tersebut sebagai sinyal untuk membaca ulang ulasan, bukan sebagai penyisipan satu kali. Pengiriman hanya dicoba satu kali tanpa percobaan ulang, jadi tetap lakukan pemeriksaan berkala dari langkah 4 sebagai cadangan. Panduan penyiapannya ada di Bereaksi terhadap peristiwa dengan webhook.

Langkah selanjutnya