Listings APIListings API
登录

地点

通过 client.locations 列出、创建、更新、归档、搜索和检索地点。

所有地点方法都位于 client.locations 下。使用这些方法之前，请安装 SDK 并配置您的密钥；请参阅安装和快速入门。

地点 ID

接受 location_id 参数的方法既支持数字 ID（16808），也支持其 base64 编码形式（"TG9jYXRpb246MTY4MDg="）。SDK 会自动对数字 ID 进行编码，因此这 2 种形式可以互换使用：

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_isostr由 2 个字母组成的国家 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

归档 1 个或多个地点。

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 商家资料分析