Listings APIListings API
Masuk

Panduan mulai cepat

Hubungkan ke Listings API, tampilkan daftar lokasi Anda, buat lokasi dengan satu panggilan, dan balas ulasan.

1. Atur kunci API Anda

Dapatkan kunci Anda dari API Keys → New key di dasbor pengembang Listings API. SDK secara otomatis membacanya dari variabel lingkungan LISTINGSAPI_KEY.

bash
export LISTINGSAPI_KEY="your-api-key"

2. Tampilkan daftar lokasi Anda

quickstart.py
import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page:  print(loc.name, "--", loc.city, loc.stateIso) print(f"\nShowing {len(page)} locations, has_more={page.has_more}")
bash
python quickstart.py

Keluaran yang diharapkan:

bash
Acme Dental Downtown -- New York NYAcme Dental Midtown -- New York NYAcme Dental Brooklyn -- Brooklyn NY Showing 3 locations, has_more=False

Untuk meminta semua halaman secara otomatis, gunakan client.locations.list(first=100).auto_paging_iter(); metode ini mengikuti paginasi berbasis kursor sehingga Anda tidak perlu mengelola kursor secara manual.

3. Buat lokasi dengan satu panggilan

locations.add() menerima setiap field wajib sebagai argumen kata kunci dan memvalidasinya di sisi klien (panjang nama, deskripsi minimal 200 karakter, kategori, negara, kota) sebelum melakukan panggilan jaringan apa pun, sehingga payload yang tidak valid langsung ditolak dengan ValidationError yang jelas.

Python
import listingsapi client = listingsapi.ListingsAPI() result = client.locations.add(  name="Acme Dental Uptown",  description=(      "Acme Dental Uptown is a family-owned dental practice on the Upper "      "West Side of New York offering preventive care, cosmetic dentistry, "      "orthodontics, and emergency appointments. Our board-certified team "      "combines modern equipment with a gentle, patient-first approach."  ),  sub_category_id=1432,  country_iso="US",  city="New York",  street="482 Columbus Ave",  state_iso="NY",  postal_code="10024",  phone="6443859313",) print(result.location.id)print(result.location.name)

Platform publikasi menggunakan deskripsi sebagai teks utama profil bisnis, sehingga API mewajibkan setidaknya 200 karakter. Dapatkan nilai sub_category_id yang valid dari client.subcategories().

ID baru dikembalikan sebagai string base64 seperti TG9jYXRpb246MTY4MDg=. ID numerik dan base64 dapat saling menggantikan di semua bagian SDK yang menerima ID lokasi, sehingga client.locations.retrieve(16808) dan client.locations.retrieve("TG9jYXRpb246MTY4MDg=") mengambil lokasi yang sama.

4. Balas ulasan

Tampilkan daftar ulasan untuk suatu lokasi, lalu balas menggunakan interactionId ulasan tersebut:

Python
import listingsapi client = listingsapi.ListingsAPI() reviews = client.reviews.list(16808, first=10, rating_filters=[4, 5])for review in reviews:  print(review.rating, "-", review.get("content")) # A page can come back empty, and not every review is repliable: some sites# allow one owner reply per review, and some are read-only for the account.repliable = [r for r in reviews if r.get("canRespond")]if not repliable:  print("nothing to reply to")else:  client.reviews.respond(      interaction_id=repliable[0].interactionId,      content="Thank you for the kind review! We look forward to seeing you again soon.",  )

Periksa canRespond sebelum membalas, dan jangan pernah mengakses elemen halaman melalui indeks tanpa terlebih dahulu memastikan halaman tersebut tidak kosong: reviews[0] pada halaman kosong memicu IndexError, dan upaya membalas ulasan yang telah ditutup oleh platform asal akan gagal di platform publikasi, bukan di API.

Jika platform menolak balasan, SDK memicu ValidationError meskipun status HTTP adalah 200; Anda tidak perlu memeriksa flag success sendiri.

5. Tangani kesalahan

Python
import listingsapi try:  client = listingsapi.ListingsAPI(api_key="bad-key")  client.locations.list()except listingsapi.AuthenticationError as e:  print("Invalid key:", e.code)

Kunci yang tidak valid menghasilkan respons HTTP 401 dengan kode platform SY90005; SDK memicu AuthenticationError. Sebagai langkah antisipasi, SDK juga menangani kode kesalahan yang sama jika kode tersebut muncul dalam isi respons 200. Lihat Penanganan kesalahan untuk hierarki exception lengkap dan referensi kode kesalahan untuk matriks status HTTP.

Langkah berikutnya