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

すべての必須フィールドをキーワード引数として指定し、1 回の呼び出しで拠点を作成します。拠点の作成には、この方法を推奨します。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 です。有効な ID は client.subcategories() で確認してください。必須です。
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 です。ID は client.plan_sites() で確認してください。
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 を指定して 1 つの拠点を取得します。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）のリストを指定し、1 回の呼び出しで複数の拠点を取得します。

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 のプロフィール分析