Listings APIListings API
Oturum aç

Konumlar

client.locations aracılığıyla konumları listeleyin, oluşturun, güncelleyin, arşivleyin, arayın ve alın.

Tüm konum metotları client.locations altında yer alır. Bunları kullanmadan önce SDK'yı yükleyin ve anahtarınızı yapılandırın; Kurulum ve Hızlı başlangıç bölümlerine bakın.

Konum ID'leri

location_id alan metotlar, sayısal bir ID'yi (16808) veya bunun base64 ile kodlanmış karşılığını ("TG9jYXRpb246MTY4MDg=") kabul eder. SDK, sayısal ID'leri otomatik olarak kodladığı için her iki biçim de birbirinin yerine kullanılabilir:

Python
# These are equivalentclient.locations.retrieve(16808)client.locations.retrieve("TG9jYXRpb246MTY4MDg=")

locations.add

Tüm zorunlu alanları adlandırılmış argüman olarak ileterek tek çağrıda bir konum oluşturun. Konum oluşturmak için önerilen yöntem budur. SDK, API'nin oluşturma gereksinimlerini istemci tarafında doğrular ve herhangi bir ağ çağrısından önce ValidationError istisnasını oluşturur; böylece geçersiz bir veri yükü, açık bir mesajla hemen hata verir.

Python
client.locations.add(    *,    name: str,    description: str,    sub_category_id: int,    country_iso: str,    city: str | None = None,    street: str | None = None,    state_iso: str | None = None,    postal_code: str | None = None,    phone: str | None = None,    website: str | None = None,    store_id: str | None = None,    hide_address: bool | None = None,    business_hours: list[dict] | None = None,    service_area: dict | None = None,    place_action_links: list[dict] | None = None,    enabled_site_ids: list[int] | None = None,    additional_fields: dict | None = None,) -> APIObject
ArgümanTürAçıklama
namestrİşletme adı, 2-150 karakter. Zorunlu.
descriptionstrİşletme açıklaması, en az 200 karakter. Yayın platformları bunu işletme kaydının ana metni olarak kullanır. Zorunlu.
sub_category_idintBirincil alt kategori ID'si. Geçerli ID'ler için client.subcategories() kullanın. Zorunlu.
country_isostrİki harfli ISO ülke kodu. Desteklenen ülkeler için client.countries() kullanın. Zorunlu.
citystrŞehir. Şehir düzeyinde adresleme kullanan ülkelerde zorunludur; yalnızca hide_address=True koşulunu sağlayan hizmet bölgesi işletmeleri için bu alanı atlayın.
streetstrSokak adresi.
state_isostrEyalet veya bölgenin ISO kodu.
postal_codestrPosta kodu veya ZIP kodu.
phonestrÜlkeye göre doğrulanan birincil telefon numarası.
websitestrİşletmenin web sitesi URL'si.
store_idstrBenzersiz mağaza kodunuz; hesap genelinde benzersiz olmalıdır.
hide_addressboolSokak adresini gizleyin (hizmet bölgesi işletmeleri).
business_hourslist[dict]Haftalık çalışma saatleri, e.g. [{"day": "MONDAY", "slots": [...]}].
service_areadictHizmet bölgesi yapılandırması: {businessType, regionCode, placeInfos}.
place_action_linkslist[dict]Google işlem bağlantıları, e.g. [{"placeActionType": "APPOINTMENT", "uri": "https://...", "isPreferred": True}].
enabled_site_idslist[int]Planınızdaki sitelerin yalnızca bir kısmını kullanmak istediğinizde, bu konumun yayımlanacağı sitelerin ID'leri. ID'ler için client.plan_sites() kullanın.
additional_fieldsdictVeri yüküne olduğu gibi eklenen ilave camelCase alanları.

İstemci tarafındaki doğrulama kontrolleri: name 2-150 karakter olmalı, description en az 200 karakter olmalı, sub_category_id ve country_iso bulunmalı ve hide_address=True koşulu sağlanmadıkça city bulunmalıdır.

Dönüş değeri, oluşturma veri yüküdür: .location yeni konumu içerir. Başarı bayraklarını hiçbir zaman kontrol etmeniz gerekmez; API veri yükünü reddettiğinde SDK, ValidationError istisnasını oluşturur.

Python
result = client.locations.add(  name="Acme Dental",  description=(      "Acme Dental is a family-owned dental practice offering general, "      "cosmetic, and pediatric dentistry in the heart of New York. Our "      "team provides cleanings, fillings, crowns, whitening, and same-day "      "emergency care in a modern, comfortable office with weekend hours "      "and easy online booking for new and returning patients."  ),  sub_category_id=1432,  country_iso="US",  city="New York",  street="123 Jump Street",  state_iso="NY",  postal_code="10013",  phone="6443859313",  website="https://acmedental.example.com",  store_id="NYC-001",  place_action_links=[      {"placeActionType": "APPOINTMENT", "uri": "https://acmedental.example.com/book", "isPreferred": True},  ],  enabled_site_ids=[1, 24, 87],)print("Created:", result.location.id, result.location.name)

locations.list

Konumları imleç tabanlı sayfalama ile listeleyin. Bir SyncPage döndürür.

Python
client.locations.list(    *,    first: int | None = None,    after: str | None = None,    before: str | None = None,    last: int | None = None,) -> SyncPage
Python
# First page of 25page = client.locations.list(first=25)for loc in page:  print(loc.name, loc.city) # Next page manuallyif page.has_more:  page2 = page.next_page() # Auto-paginate all locationsfor loc in client.locations.list(first=100).auto_paging_iter():  print(loc.name)

locations.retrieve

ID ile tek bir konum alın. ID mevcut değilse NotFoundError istisnasını oluşturur.

Python
client.locations.retrieve(location_id: str | int) -> APIObject
Python
loc = client.locations.retrieve(16808)print(loc.name, loc.street, loc.city)

locations.list_by_ids

Bir ID listesi (sayısal veya base64) kullanarak tek çağrıda birden fazla konum alın.

Python
client.locations.list_by_ids(location_ids: list[str | int]) -> list[APIObject]
Python
locs = client.locations.list_by_ids([16808, 16809, "TG9jYXRpb246MTQwMjQ="])for loc in locs:  print(loc.id, loc.name)

locations.list_by_store_codes

Verilen mağaza kodlarıyla eşleşen konumları alın.

Python
client.locations.list_by_store_codes(store_codes: list[str]) -> list[APIObject]
Python
locs = client.locations.list_by_store_codes(["SF-001", "NYC-042"])for loc in locs:  print(loc.storeId, loc.name)

locations.search

Ad, adres veya mağaza ID'si alanlarında anahtar kelimeyle konum arayın. Bir SyncPage döndürür.

Python
client.locations.search(    query: str,    *,    fields: list[str] | None = None,    first: int | None = None,    after: str | None = None,    before: str | None = None,    last: int | None = None,) -> SyncPage
Python
# Search all fieldspage = client.locations.search("downtown dental", first=10) # Restrict to name onlypage = client.locations.search("Acme Dental", fields=["name"], first=10) for loc in page:  print(loc.name, loc.city)

locations.create

camelCase alan adlarını içeren ham bir girdi dict'inden konum oluşturun. Adlandırılmış argümanlar ve istemci tarafında doğrulama için locations.add kullanmayı tercih edin; elinizde zaten bir camelCase veri yükü varsa create kullanın.

Python
client.locations.create(input: dict) -> APIObject

API'nin zorunlu tuttuğu alanlar: name, description (en az 200 karakter), subCategoryId, countryIso ve city (şehir düzeyinde adresleme kullanan ülkeler için).

Python
result = client.locations.create({  "name": "Acme Dental Brooklyn",  "description": (      "Acme Dental Brooklyn is a family-owned dental practice offering "      "general, cosmetic, and pediatric dentistry. Our team provides "      "cleanings, fillings, crowns, whitening, and same-day emergency "      "care in a modern, comfortable office with weekend hours and easy "      "online booking for new and returning patients across Brooklyn."  ),  "subCategoryId": 1432,  "countryIso": "US",  "city": "Brooklyn",  "street": "88 Court St",  "stateIso": "NY",  "postalCode": "11201",  "phone": "6443859314",  "storeId": "NYC-002",})print("Created:", result.location.id)

locations.update

Bir konumu güncelleyin. id ile birlikte değiştirmek istediğiniz alanları (camelCase) iletin. id sayısal veya base64 biçiminde olabilir; SDK bunu otomatik olarak kodlar.

Python
client.locations.update(input: dict) -> APIObject
Python
result = client.locations.update({  "id": 16808,  "phone": "6443859399",  "street": "125 Jump Street",})print("Updated:", result.location.id)

locations.archive

Bir veya daha fazla konumu arşivleyin.

Python
client.locations.archive(location_ids: list[str | int]) -> APIObject
Python
result = client.locations.archive([16808, 16809])print(result.to_dict())

locations.cancel_archive

Planlanmış bir arşivleme işlemini iptal edin.

Python
client.locations.cancel_archive(    location_ids: list[str | int],    selection_type: str,    changed_by: str,) -> APIObject
Python
client.locations.cancel_archive(  [16808],  selection_type="manual",  changed_by="admin@example.com",)

Ayrıca bkz.