Listings APIListings API
Masuk

Python SDK

Klien Python resmi untuk Listings API dengan sumber daya bertipe, paginasi kursor, percobaan ulang otomatis, dan galat bernama.

Paket listingsapi adalah klien Python resmi untuk Listings API. Paket ini membungkus lapisan REST dengan kelas sumber daya bertipe, paginasi berbasis kursor, percobaan ulang otomatis saat terjadi kesalahan sementara, dan pengecualian bernama untuk setiap jenis kegagalan, termasuk payload kesalahan yang dikembalikan platform dengan HTTP 200.

Instalasi

bash
pip install listingsapi

Memerlukan Python 3.9 atau yang lebih baru. Satu-satunya dependensi saat dijalankan adalah requests.

Autentikasi

Python
import listingsapi # Reads LISTINGSAPI_KEY from the environment automaticallyclient = listingsapi.ListingsAPI() # Or pass the key explicitlyclient = listingsapi.ListingsAPI(api_key="your-api-key")

Dapatkan kunci API Anda melalui API Keys → New key di dasbor pengembang Listings API.

Klien menerima tiga argumen kata kunci opsional:

OpsiNilai bawaanDeskripsi
base_urlhttps://listingsapi.comHost API tujuan pengiriman permintaan
timeout240.0Batas waktu setiap permintaan dalam detik
max_retries2Percobaan ulang otomatis untuk respons 429 dan 5xx, dengan mematuhi Retry-After

Lihat Konfigurasi untuk detailnya.

Contoh singkat

list_locations.py
import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page:  print(loc.name, loc.city) print(f"has_more: {page.has_more}")

Sumber daya

Setiap sumber daya merupakan properti klien:

PropertiYang dikelola
client.locationsLokasi bisnis: menampilkan daftar, mencari, membuat dengan satu panggilan, memperbarui, mengarsipkan
client.reviewsUlasan dan balasan, serta analitik melalui client.reviews.analytics
client.postsPostingan pengumuman, acara, dan penawaran ke Google dan Facebook
client.socialMerek di Social, akun media sosial yang terhubung, dan postingan ke Facebook, Instagram, X, LinkedIn, dan Pinterest
client.listingsProfil bisnis premium dan suara, duplikat, menghubungkan dan memutuskan koneksi
client.analyticsInsight profil Google, Bing, dan Facebook
client.photosFoto lokasi: mengunggah, menghapus, memberi bintang
client.connected_accountsKoneksi OAuth ke Google dan Facebook
client.workflowsOtomatisasi siap pakai: balasan ulasan otomatis, laporan reputasi, audit kondisi profil bisnis

Empat metode pendukung tersedia langsung pada klien:

Python
client.plan_sites()       # directories included in your planclient.subcategories()    # business categories (IDs for locations.add)client.countries()        # supported countries and states (ISO codes)client.subscriptions()    # active subscriptions for the account

Paginasi

Metode yang mengembalikan daftar menggunakan paginasi berbasis kursor. Setiap metode berpaginasi mengembalikan SyncPage: dapat diiterasi, dengan .has_more, .next_page(), .auto_paging_iter(), dan .total.

Python
# Fetch one pagepage = client.locations.list(first=25)for loc in page:  print(loc.name) # Check if more pages existif page.has_more:  next_page = page.next_page() # Auto-paginate through every resultfor loc in client.locations.list(first=100).auto_paging_iter():  print(loc.name)

Objek respons

Semua metode mengembalikan APIObject (akses melalui atribut dan dict) atau SyncPage (dapat diiterasi dan berpaginasi). APIObject juga mendukung .get() dan .to_dict().

Python
loc = client.locations.retrieve(16808) # Attribute accessprint(loc.name)print(loc.city) # Dict-style accessprint(loc["stateIso"]) # Safe access with a defaultprint(loc.get("website", "no website")) # Raw dictdata = loc.to_dict()

Penanganan kesalahan

Setiap kesalahan SDK diturunkan dari listingsapi.ListingsAPIError. Kegagalan API memunculkan APIError atau salah satu subkelasnya: AuthenticationError, PermissionDeniedError, NotFoundError, ValidationError, RateLimitError (dengan .retry_after), dan InternalServerError. Kegagalan jaringan memunculkan APIConnectionError.

APIError memuat status_code, code (kode kesalahan platform pertama, e.g. SY10005), errors (setiap entri dinormalisasi menjadi dict {"code", "message", "context"}), dan response_body.

Platform melaporkan beberapa kegagalan dalam isi respons HTTP 200: payload errors[] pada tingkat teratas (token yang tidak valid dikembalikan sebagai SY90005) dan respons operasi tulis dengan success=false. SDK juga memunculkan pengecualian untuk kegagalan tersebut, sehingga Anda tidak perlu memeriksa flag success sendiri.

Python
import listingsapi client = listingsapi.ListingsAPI() try:  client.locations.retrieve(999999)except listingsapi.NotFoundError:  print("No such location")except listingsapi.RateLimitError as e:  print(f"Rate limited, retry in {e.retry_after}s")except listingsapi.APIError as e:  print(e.status_code, e.code)  for err in e.errors:      print(err["code"], err["message"])

Lihat Penanganan kesalahan untuk hierarki pengecualian lengkap.

Langkah berikutnya