在地生活服務廣告端對端透過 API 查詢商家狀態

用途

Google 地圖預訂 API 提供兩種方法，可透過程式輔助方式，針對各種整合或 Local Services Ads 廣告空間，擷取個別商家的狀態。

Merchant Status API 的用途：

• 強化現有的客戶關係管理工具，向客戶展示他們的商品目錄在 Google 上的呈現方式。
• 建立資訊主頁，以追蹤商家的商品目錄狀態和比對狀態。
• 以程式輔助方式擷取商家的相符和可預訂狀態，並修正任何不正確的資訊，以改善資料品質。

商家狀態包含哪些內容

MerchantStatus 包含下列資訊：

• 商家廣告空間狀態：適用於預訂和/或等候名單商家。
• 商家比對狀態：包含已比對的商家資訊
• (僅限 Google 在地生活服務廣告) 比對成功的商家服務供應商：包含客戶 ID 和服務類別。
• 用來說明商家在 Google 上的顯示方式。

查詢單一商家的狀態

您可以使用 inventory.partners.merchants.getStatus 取得單一商家的狀態：

GET https://mapsbooking.googleapis.com/v1alpha/inventory/partners/{partnerId}/merchants/{merchantId}/status

以下是 Python 程式碼範例 (如需其他語言的範例，請參閱這裡)：

from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import service_account

credentials = service_account.Credentials.from_service_account_file(
    './your_key.json')
scoped_credentials = credentials.with_scopes(
    ['https://www.googleapis.com/auth/mapsbooking'])
authed_session = AuthorizedSession(scoped_credentials)

response = authed_session.get('https://partnerdev-mapsbooking.googleapis.com' +
    '/v1alpha/inventory/partners/123456789/merchants/001/status')

MerchantStatus 回應範例如下：

  {
    "name": "partners/123456789/merchants/001/status",
    "merchantName": "Foo Bar Restaurant",
    "inputGeoInfo": {
      "unstructured_address": "123 Foo Bar Street, Mountain View"
    },
    "processingStatus": "COMPLETED",
    "bookingStatus": {
      "hasValidFutureInventory": true
    },
    "waitlistStatus": {
      "hasValidWaitlistService": true
    }
    "geoMatch": {
      "name": "Foo Bar Restaurant",
      "formattedAddress": "123 Foo Bar St, Mountain View, CA 94043",
      "placeId": "ChIAAAAAAAAABBBBBBBB"
    },
    "directUrls": [
      {
        "type": "BOOKING",
        "url": "https://reserve-partnerdev.sandbox.google.com/maps/reserve/v/dine/m/Nwaaaaa"
      },
      {
        "type": "WAITLIST",
        "url": "https://reserve-partnerdev.sandbox.google.com/maps/reserve/v/wait/c/iDbbbbb"
      }
    ]
  }

大量擷取商家狀態

您可以使用 inventory.partners.merchants.status.list 擷取所有商家或符合特定商品目錄/比對條件的商家群組狀態。舉例來說，您可以發出以下呼叫，取得所有擁有有效預約商品目錄的不相符商家：

GET https://mapsbooking.googleapis.com/v1alpha/inventory/partners/{partnerId}/merchants/status?pageSize=50&bookingInventoryStatusRestrict=HAS_VALID_FUTURE_INVENTORY&geoMatchRestrict=GEO_UNMATCHED

回應範例如下所示：

  {
    "merchantStatuses": [
      {
        "name": "partners/123456789/merchants/002/status",
        "merchantName": "Bar Foo Restaurant",
        "inputGeoInfo": {
          "unstructured_address": "234 Bar Foo Street, Mountain View"
        },
        "processingStatus": "COMPLETED",
        "bookingStatus": {
          "hasValidFutureInventory": true
        },
        "waitlistStatus": {},
      },
      ...
      {
        "name": "partners/123456789/merchants/080/status",
        "merchantName": "Baz Restaurant",
        "inputGeoInfo": {
          "unstructured_address": "345 Baz Street, Mountain View"
        },
        "processingStatus": "COMPLETED",
        "bookingStatus": {
          "hasValidFutureInventory": true
        },
        "waitlistStatus": {
          "hasValidWaitlistService": true
        },
      },
    ],
    "nextPageToken": "AAABBBB"
  }

這個回應會包含 50 個符合篩選條件的 MerchantStatus，並依 merchant_id 排序。回應也包含分頁符記 (如果不是最後一頁)，可用於查詢下一頁。

請注意：篩選條件應在所有頁面上保持一致。

最佳做法

由於商家狀態在大多數情況下不會經常變更，因此建議您將擷取的結果快取，並定期 (例如每隔幾小時) 透過新查詢擷取這些結果。如果每秒要求數量過高，Actions Center 可能會限制您的查詢。