Pilih cara integrasi

Bandingkan REST API, SDK Python dan Node, server MCP, serta webhook berdasarkan arsitektur aplikasi dan kebutuhan integrasi Anda.

Semua metode integrasi menggunakan kunci API dan URL dasar yang sama: https://listingsapi.com/api/v4. Anda dapat menggunakan REST API atau SDK untuk permintaan API, webhook untuk pembaruan berbasis peristiwa, dan server MCP untuk melakukan integrasi dengan bantuan agen AI.

1. Pilih cara Anda akan memanggil API

REST API. Gunakan REST API untuk mengakses semua endpoint secara langsung melalui HTTP. Aplikasi Anda harus mengurai respons, menangani kedua metode paginasi, dan memeriksa array errors[] untuk menemukan kesalahan API.

Python SDK. Instal Python SDK dengan pip install listingsapi. SDK ini menyediakan kelas sumber daya melalui antarmuka seperti client.locations dan client.reviews. SDK ini menangani paginasi kursor dengan auto_paging_iter(), mencoba kembali permintaan yang mengembalikan respons 429 atau 5xx, dan memvalidasi payload lokasi dalam locations.add() sebelum mengirim permintaan API. Baca Python SDK.

Node SDK. Instal Node SDK dengan npm install listingsapi-js. SDK ini memerlukan Node.js 18 atau yang lebih baru, menyertakan definisi tipe TypeScript, dan tidak memiliki dependensi runtime. Metode SDK tersedia langsung pada instans klien, misalnya client.fetchAllLocations(). Atur fetchAll: true untuk mengambil semua hasil yang dipaginasi dalam satu respons. ID numerik secara otomatis dikodekan ke Base64 sebelum permintaan API dikirim. Baca Node SDK.

Server MCP. Hubungkan klien AI seperti Claude, ChatGPT, Cursor, dan Gemini ke server MCP ListingsAPI di https://listingsapi.com/mcp menggunakan Streamable HTTP. Instalasi server MCP lokal tidak diperlukan. Server ini menyediakan alat untuk mencari dokumentasi ListingsAPI, menemukan endpoint REST, dan menjalankan operasi API yang didukung. Autentikasi menggunakan kunci API atau OAuth. Buka /dashboard/mcp untuk melihat konfigurasi klien, alat MCP yang tersedia, dan tingkat izin kunci API yang diperlukan untuk setiap alat. Hubungkan agen AI dengan MCP.

Webhook. Gunakan webhook bersama REST API, SDK, atau server MCP untuk menerima pembaruan berbasis peristiwa. Ketika lokasi, profil bisnis, ulasan, atau postingan berubah, ListingsAPI mengirim permintaan HTTP POST ke URL webhook yang dikonfigurasi untuk akun Anda. Hal ini memungkinkan aplikasi Anda memproses perubahan tanpa melakukan polling ke API untuk mendapatkan pembaruan. Baca Gambaran umum webhook.

2. Pahami model autentikasi

REST API dan SDK mengautentikasi permintaan menggunakan kunci API. Sertakan kunci tersebut dalam header permintaan HTTP Authorization menggunakan skema autentikasi API:

Authorization: API <YOUR_API_KEY>

Kunci API memiliki akses Read (baca) atau Write (tulis). Kunci Read dapat mengakses operasi baca, termasuk pencarian dan laporan. Kunci Write diperlukan untuk operasi yang membuat atau memperbarui sumber daya. Jika Anda mengirim kunci Read ke endpoint tulis, endpoint tersebut mengembalikan HTTP 400 dengan kode kesalahan SY90016.

Cakupan kunci API terbatas pada satu akun. Permintaan yang dibuat dengan kunci dari akun yang sama menggunakan kuota batas laju yang sama pada tingkat akun.

Server MCP juga mendukung autentikasi OAuth. Klien MCP dapat melakukan autentikasi melalui peramban menggunakan OAuth sebagai pengganti kunci API. Permintaan REST API dan SDK melakukan autentikasi menggunakan header Authorization. Lihat dokumentasi Autentikasi untuk detail konfigurasi.

3. Pahami model paginasi

Endpoint daftar REST menggunakan paginasi berbasis kursor atau berbasis offset. SDK mengabstraksikan model paginasi ini.

Endpoint berbasis kursor menerima first dan after. Hasil dikembalikan melalui edges[].node, dan pageInfo.endCursor menyediakan kursor untuk permintaan berikutnya.

Endpoint berbasis offset menerima page dan perPage. Hasil dikembalikan dalam records[], dan pageInfo.totalRecords melaporkan jumlah total rekaman yang tersedia.

Contoh berikut menjalankan operasi yang sama untuk mengambil daftar lokasi menggunakan tiga metode integrasi. Implementasi cURL mengharuskan aplikasi mengurai struktur respons API secara langsung.

curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY" # Read data.allLocations.edges[].node, then pass# data.allLocations.pageInfo.endCursor back as ?after= for the next page.

Untuk semua metode integrasi, kesalahan API dikembalikan dalam array errors[], dengan setiap pesan kesalahan diawali kode kesalahan SY. Permintaan tulis dapat mengembalikan HTTP 200 dengan success: false, sehingga isi respons harus diperiksa sebelum operasi dianggap berhasil.

Saat akun melampaui batas laju permintaannya, API mengembalikan HTTP 429 dengan header Retry-After. Paket Launch mendukung hingga 10 permintaan per menit. Lihat dokumentasi Kode kesalahan dan Batas laju permintaan untuk detailnya.

4. Pilih antara webhook dan polling

Gunakan polling saat aplikasi Anda memerlukan status sumber daya sesuai jadwal yang ditetapkan, seperti sinkronisasi semua lokasi setiap malam, atau saat peristiwa yang diperlukan tidak didukung oleh webhook. Gunakan webhook saat aplikasi Anda perlu memproses perubahan ketika terjadi, seperti penerimaan ulasan baru, perubahan status profil bisnis, atau penolakan postingan Google.

Konfigurasikan satu URL webhook per akun di /dashboard/webhooks. Setiap permintaan webhook menyertakan header X-ListingsAPI-Signature dalam format berikut:

X-ListingsAPI-Signature: sha256=<base64 HMAC>

Endpoint webhook harus mengembalikan respons 2xx dalam waktu 5 detik. Pengiriman yang gagal tidak dicoba ulang.

Gunakan peristiwa webhook sebagai pemicu untuk mengambil status terkini sumber daya dari API. Karena pengiriman webhook tidak dicoba ulang, jalankan proses rekonsiliasi terjadwal untuk mendeteksi pembaruan yang mungkin terlewat. Lihat Tanggapi peristiwa dengan webhook untuk contoh implementasi.

5. Bandingkan sekilas

Langkah berikutnya

• Tambahkan lokasi: panggilan tulis pertama Anda, menggunakan opsi mana pun yang Anda pilih.
• Tanggapi peristiwa dengan webhook: siapkan penerima untuk pengiriman bertanda tangan.
• Python SDK dan Node SDK: instal, konfigurasikan, dan baca tabel metode.
• Autentikasi, Batas laju permintaan, dan Kode kesalahan: tiga referensi yang berlaku untuk semua opsi.