應用情境
Google Maps Booking API 提供兩種方法，可用於透過程式輔助從各種 Actions Center 整合服務或在地生活服務廣告商品目錄，擷取個別商家的狀態。
Merchant Status API 的用途：
- 強化現有的客戶關係管理工具，向客戶展示他們的庫存產品在 Actions Center 平台上的顯示方式。
- 建立資訊主頁以追蹤商家的商品目錄狀態和比對狀態。
- 以程式輔助方式擷取商家的比對和可預訂狀態，並修正任何錯誤資訊來改善資料品質。
商家狀態包含哪些資訊
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 可能會限制查詢作業。