Listings APIListings API
Oturum aç

Python SDK

Tür tanımlı kaynaklar, imleç tabanlı sayfalama, otomatik yeniden denemeler ve adlandırılmış hatalar sunan resmî Listings API Python istemcisi.

listingsapi paketi, Listings API için resmi Python istemcisidir. REST katmanını; tür tanımlı kaynak sınıfları, imleç tabanlı sayfalama, geçici hatalarda otomatik yeniden deneme ve platformun HTTP 200 ile döndürdüğü hata içerikleri dahil her hata durumu için adlandırılmış bir istisna ile sunar.

Kurulum

bash
pip install listingsapi

Python 3.9 veya üzerini gerektirir. Tek çalışma zamanı bağımlılığı requests paketidir.

Kimlik doğrulama

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

API anahtarınızı Listings API geliştirici kontrol panelindeki API Keys → New key bölümünden alın.

İstemci, isteğe bağlı üç anahtar sözcük argümanı alır:

SeçenekVarsayılanAçıklama
base_urlhttps://listingsapi.comİsteklerin gönderileceği API sunucusu
timeout240.0Saniye cinsinden istek başına zaman aşımı
max_retries2Retry-After dikkate alınarak 429 ve 5xx yanıtlarında otomatik yeniden deneme

Ayrıntılar için Yapılandırma bölümüne bakın.

Kısa örnek

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}")

Kaynaklar

Her kaynak, istemcinin bir özelliğidir:

ÖzellikYönettiği öğeler ve işlemler
client.locationsİşletme konumları: listeleme, arama, tek çağrıyla oluşturma, güncelleme, arşivleme
client.reviewsYorumlar ve yanıtlar, ayrıca client.reviews.analytics altındaki analizler
client.postsGoogle ve Facebook için duyuru, etkinlik ve teklif gönderileri
client.socialSocial markaları, bağlı sosyal medya hesapları ve Facebook, Instagram, X, LinkedIn ve Pinterest gönderileri
client.listingsPremium ve sesli arama işletme kayıtları, yinelenen işletme kayıtları, bağlama ve bağlantıyı kesme
client.analyticsGoogle, Bing ve Facebook profil istatistikleri
client.photosKonum fotoğrafları: yükleme, kaldırma, yıldızla işaretleme
client.connected_accountsGoogle ve Facebook OAuth bağlantıları
client.workflowsHazır otomasyonlar: yorumlara otomatik yanıt verme, itibar raporu, işletme kayıtlarının durumunu denetleme

İstemcinin kendisinde dört yardımcı metot bulunur:

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

Sayfalama

Liste döndüren metotlar imleç tabanlı sayfalama kullanır. Sayfalama kullanan her metot, üzerinde yineleme yapılabilen ve .has_more, .next_page(), .auto_paging_iter() ve .total içeren bir SyncPage döndürür.

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)

Yanıt nesneleri

Tüm metotlar APIObject (öznitelik ve dict erişimi) veya SyncPage (üzerinde yineleme yapılabilen, sayfalanmış) döndürür. APIObject ayrıca .get() ve .to_dict() desteği sunar.

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()

Hata işleme

Her SDK hatası listingsapi.ListingsAPIError sınıfından türetilir. API hataları, APIError istisnasını veya alt sınıflarından birini oluşturur: AuthenticationError, PermissionDeniedError, NotFoundError, ValidationError, RateLimitError (.retry_after ile) ve InternalServerError. Ağ hataları APIConnectionError istisnasını oluşturur.

APIError; status_code, code (platformun ilk hata kodu, e.g. SY10005), errors (her öğe {"code", "message", "context"} sözlüklerine dönüştürülerek standartlaştırılmıştır) ve response_body içerir.

Platform bazı hataları HTTP 200 yanıt gövdesinde bildirir: üst düzey errors[] içerikleri (geçersiz token'lar SY90005 olarak döner) ve success=false içeren yazma yanıtları. SDK bu durumlarda da istisna oluşturur, böylece success bayraklarını kendiniz kontrol etmeniz gerekmez.

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"])

İstisna hiyerarşisinin tamamı için Hata işleme bölümüne bakın.

Sonraki adımlar