應用情境
Google Maps Booking API 提供兩種方法,可用於透過程式輔助從各種整合服務或在地生活服務廣告商品目錄中擷取個別商家的狀態。
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 可能會限制查詢作業。