Listings APIListings API
Oturum aç

Hızlı başlangıç

Listings API'ye bağlanın, konumlarınızı listeleyin, tek bir çağrıyla bir konum oluşturun ve bir yoruma yanıt verin.

1. API anahtarınızı ayarlayın

Listings API geliştirici kontrol panelinde API anahtarları → Yeni anahtar bölümünden anahtarınızı alın. SDK, anahtarı LISTINGSAPI_KEY ortam değişkeninden otomatik olarak okur.

bash
export LISTINGSAPI_KEY="your-api-key"

2. Konumlarınızı listeleyin

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

Beklenen çıktı:

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

Tüm sayfaları otomatik olarak istemek için client.locations.list(first=100).auto_paging_iter() kullanın; cursor ile sayfalamayı takip ettiği için cursor değerlerini elle yönetmeniz gerekmez.

3. Tek çağrıyla bir konum oluşturun

locations.add(), zorunlu alanların her birini anahtar sözcük argümanı olarak alır ve herhangi bir ağ çağrısından önce bunları istemci tarafında doğrular (ad uzunluğu, açıklamanın en az 200 karakter olması, kategori, ülke, şehir); böylece geçersiz bir istek gövdesi, açıklayıcı bir ValidationError hatasıyla hemen reddedilir.

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)

Yayın platformları, açıklamayı işletme kaydının ana metni olarak kullanır; bu nedenle API en az 200 karakter gerektirir. Geçerli sub_category_id değerlerini client.subcategories() üzerinden alın.

Yeni kimlik, TG9jYXRpb246MTY4MDg= gibi bir base64 dizesi olarak döndürülür. SDK'nın konum kimliği kabul ettiği her yerde sayısal kimlikler ve base64 kimlikleri birbirinin yerine kullanılabilir; dolayısıyla client.locations.retrieve(16808) ve client.locations.retrieve("TG9jYXRpb246MTY4MDg=") aynı konumu getirir.

4. Bir yorumu yanıtlayın

Bir konumun yorumlarını listeleyin, ardından yorumun interactionId değerini kullanarak yanıt verin:

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.",  )

Yanıt vermeden önce canRespond değerini kontrol edin ve bir sayfanın boş olmadığını kontrol etmeden asla indeksle öğelerine erişmeyin: boş bir sayfada reviews[0] kullanmak IndexError hatasına neden olur ve kaynak platformun kapattığı bir yorumu yanıtlama işlemi API'de değil, yayın platformunda başarısız olur.

Platform yanıtı reddederse HTTP durum kodu 200 olsa bile SDK, ValidationError hatası verir; success bayraklarını kendiniz kontrol etmeniz gerekmez.

5. Hataları işleyin

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

Geçersiz anahtarlar için SY90005 platform koduyla birlikte HTTP 401 döndürülür; SDK, AuthenticationError hatası verir. Aynı hata kodunun bir 200 gövdesinde gelmesi durumunu da önlem olarak ele alır. İstisna hiyerarşisinin tamamı için Hata işleme bölümüne, HTTP durum matrisi için hata kodları başvurusuna bakın.

Sonraki adımlar