Listings APIListings API
Masuk

Lakukan panggilan API pertama Anda

Lakukan autentikasi, tampilkan daftar lokasi Anda, pahami struktur respons, telusuri hasil per halaman, dan pelajari cara kerja ID.

Panduan ini mengasumsikan Anda sudah memiliki akun dan kunci API dari Memulai. Setiap permintaan dijalankan pada API produksi di https://listingsapi.com, sehingga panggilan tulis dengan kunci API biasa mengubah data nyata. Untuk mencoba API tanpa memengaruhi platform publikasi yang sebenarnya, gunakan akses harian sandbox gratis.

1. Atur kunci API Anda

Salin kunci dari Kunci API di dasbor, lalu ekspor satu kali di shell Anda:

bash
export LISTINGSAPI_KEY="your-api-key"

Setiap kunci memiliki tingkat akses. Kunci Read (baca) mencakup semua pencarian dan laporan dalam panduan ini. Membuat atau memperbarui apa pun, membalas ulasan, atau menerbitkan postingan memerlukan kunci Write (tulis). Jika Anda mengirim kunci Read ke endpoint tulis, endpoint tersebut mengembalikan status HTTP 400 dengan kode kesalahan SY90016.

2. Tampilkan daftar lokasi Anda

Endpoint lain merujuk ke lokasi berdasarkan ID-nya, jadi mulailah dengan menampilkan daftar lokasi yang Anda miliki. Header Authorization pada REST menggunakan skema API, diikuti spasi dan kunci API Anda: Authorization: API <YOUR_API_KEY>.

List locations
curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY"

3. Baca respons

REST API mengembalikan respons bertingkat, bukan hanya array. Nama operasi berada di bawah data, hasil daftar dikembalikan sebagai connection yang berisi edges, dan setiap edge berisi node:

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "approved": "APPROVED",            "subCategoryName": "Restaurants"          }        }      ],      "pageInfo": {        "hasNextPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ=="      }    }  }}

Python SDK mengembalikan halaman berisi objek yang dapat diiterasi. Node SDK mengembalikan locations dan pageInfo. Saat Anda memanggil REST API secara langsung, baca data.allLocations.edges[].node.

4. Telusuri halaman hasil

Endpoint daftar untuk lokasi dan ulasan menggunakan paginasi berbasis kursor. Minta satu halaman dengan first, lalu teruskan pageInfo.endCursor sebagai after untuk mengambil halaman berikutnya. SDK dapat membaca semua halaman untuk Anda.

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

Tidak semua endpoint menggunakan cara paginasi ini. Akun yang terhubung, ringkasan duplikat, dan postingan menggunakan page dan perPage dengan array records. Setiap panduan menyebutkan format paginasi yang digunakan oleh endpoint-nya.

5. Dua jenis ID

Setiap rekaman memiliki dua pengenal. id adalah string base64 seperti TG9jYXRpb246MTgwMDI4OQ==, yang jika didekode menghasilkan Location:1800289. databaseId adalah angka biasa, yaitu 1800289.

Simpan id dalam format base64. Setiap endpoint tulis memerlukan ID yang dikodekan dalam base64, dan nilai-nilai tersebut dikembalikan dalam payload webhook. Banyak endpoint baca yang menerima lokasi dalam path juga menerima angka aslinya, dan kedua SDK menerima salah satu format serta melakukan pengodean untuk Anda.

6. Kesalahan dan batas laju permintaan

Respons kegagalan mengembalikan status HTTP yang sesuai beserta array errors. Pesannya diawali kode kesalahan SY, yang tercantum dalam Kode kesalahan:

JSON
{  "data": { "allLocations": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

Batas laju permintaan ditentukan berdasarkan paket dan dihitung per menit, jam, dan hari. Paket Launch mengizinkan 10 permintaan per menit. Saat Anda melampaui batas, API mengembalikan 429 dengan header Retry-After; tunggu selama jumlah detik yang ditentukan sebelum mencoba lagi. SDK memunculkan RateLimitError dan menyediakan nilai yang sama. Detail lengkap tersedia di Batas laju permintaan.

Langkah berikutnya