Listings APIListings API
登入

地點

透過 client.locations 列出、建立、更新、封存、搜尋及擷取地點。

所有地點方法都位於 client.locations 下。使用前，請先安裝 SDK 並設定您的金鑰；請參閱安裝和快速入門。

地點 ID

接受 location_id 的方法可使用數字 ID（16808）或其 base64 編碼形式（"TG9jYXRpb246MTY4MDg="）。SDK 會自動將數字 ID 編碼，因此這兩種形式可互換使用：

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

locations.add

將所有必填欄位以關鍵字引數傳入，即可透過一次呼叫建立地點。這是建議的地點建立方式。SDK 會在用戶端驗證資料是否符合 API 的建立要求，並在發出任何網路呼叫前引發 ValidationError，因此無效的酬載會立即失敗，並提供明確的訊息。

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
引數型別說明
namestr商家名稱，2-150 個字元。必填。
descriptionstr商家描述，至少 200 個字元。發布平台會將其作為商家資訊的主要文案。必填。
sub_category_idint主要子類別 ID。使用 client.subcategories() 取得有效的 ID。必填。
country_isostr2 個字母的國家 ISO 代碼。使用 client.countries() 取得支援的國家。必填。
citystr城市。對於地址包含城市層級的國家，此欄位為必填；只有設定了 hide_address=True 的服務區域商家可以省略。
streetstr街道地址。
state_isostr州或地區 ISO 代碼。
postal_codestr郵遞區號或 ZIP 代碼。
phonestr主要電話號碼，會依國家驗證。
websitestr商家網站 URL。
store_idstr您的商店唯一代碼；在整個帳戶內必須唯一。
hide_addressbool隱藏街道地址（適用於服務區域商家）。
business_hourslist[dict]每週營業時間，e.g。[{"day": "MONDAY", "slots": [...]}]。
service_areadict服務區域設定：{businessType, regionCode, placeInfos}。
place_action_linkslist[dict]Google 動作連結，e.g。[{"placeActionType": "APPOINTMENT", "uri": "https://...", "isPreferred": True}]。
enabled_site_idslist[int]若只想將此地點發布至方案中的部分網站，請指定這些網站的 ID。使用 client.plan_sites() 取得 ID。
additional_fieldsdict額外的 camelCase 欄位，會原樣合併至酬載。

用戶端驗證會檢查：name 為 2-150 個字元、description 至少有 200 個字元、已提供 sub_category_id 和 country_iso，且除非符合 hide_address=True，否則必須提供 city。

回傳值為建立操作的酬載：.location 包含新地點。您不需要檢查成功旗標；當 API 拒絕酬載時，SDK 會引發 ValidationError。

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

使用游標分頁列出地點。回傳 SyncPage。

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 取得單一地點。若 ID 不存在，則引發 NotFoundError。

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

透過一次呼叫，依 ID 清單（數字或 base64）取得多個地點。

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

取得符合指定商店代碼的地點。

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

以關鍵字搜尋地點的名稱、地址或商店 ID。回傳 SyncPage。

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 欄位名稱的原始輸入 dict 建立地點。建議優先使用 locations.add，以便使用關鍵字引數和用戶端驗證；若您已有 camelCase 酬載，則使用 create。

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

API 要求的必填欄位：name、description（至少 200 個字元）、subCategoryId、countryIso 和 city（適用於地址包含城市層級的國家）。

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

更新地點。傳入 id 及任何要變更的欄位（camelCase）。id 可以是數字或 base64；SDK 會自動將其編碼。

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

封存一個或多個地點。

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

locations.cancel_archive

取消已排程的封存作業。

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

另請參閱

  • 貼文：發布公告、活動和優惠
  • 商家資訊：檢查各地點的同步狀態
  • 評論：列出並回覆評論
  • 分析：Google、Bing、Facebook 商家檔案分析