Listings APIListings API
登入

地點操作連結

透過 Listings API 管理地點的 Google 操作按鈕（訂餐、外送、外帶、訂位、預約）。

地點操作連結是 Google 在商家檔案上顯示的操作按鈕：線上訂餐、外送服務、預訂座位、預約服務等。Listings API 將這些連結納入地點管理，因此您可以透過原本使用的 建立和 更新端點設定這些連結，並透過每個地點讀取端點讀取這些連結。

建立和更新時，都可在 input 中傳入 placeActionLinks 陣列。每個元素如下：

欄位型別必填說明
placeActionTypeenum是下列有效類型之一。
uristring是目的地 URL。
isPreferredboolean否將此連結標記為其類型的首選連結。每種類型最多只能有一個首選連結。
actionstring否add（預設值）或 delete。僅在更新時使用。
namestring否連結的識別碼，會在連結同步至 Google 後由讀取端點傳回。寫入時為選填；若已有此識別碼，請一併傳入，以最精確地指定某個已儲存的連結。

有效的 placeActionType 值：

Code
APPOINTMENT   ONLINE_APPOINTMENT   DINING_RESERVATIONFOOD_ORDERING   FOOD_DELIVERY   FOOD_TAKEOUT   SHOP_ONLINE

連結的比對方式（用於編輯／刪除）：若有 name，則依此比對，否則依 placeActionType + uri 比對。若您已透過讀取取得 name，請一併傳入，以獲得最精確的比對結果。尚未同步至 Google 的新增連結沒有 name，因此會依 placeActionType + uri 比對。

操作

寫入模式為附加／新增或更新，而非取代。更新時，只有您指定的連結會受到影響；您未包含的連結會維持不變。

操作用途比對方式
add新增連結，或直接更新已儲存連結的 uri／isPreferred。若有 name，則依此比對，否則依 placeActionType + uri 比對
delete移除已儲存的連結，並將從 Google 移除該連結的作業加入佇列。若有 name，則依此比對，否則依 placeActionType + uri 比對

若要變更連結的 URL，請在同一個請求中移除舊連結並新增新連結（請參閱變更連結的 URL）。

有兩種方式可以為地點填入操作連結，並讓這些連結與 Google 保持同步。

流程 1：先在 Google 中建立，再連結

  1. 商家直接在其 Google Business Profile中設定地點操作連結。
  2. 將該 Google Business Profile地點連結至 Listings API。
  3. 連結帳戶時，Listings API 會從 Google 擷取目前的連結，並納入該地點的受管理連結集合。您不需要透過 API 重新輸入這些連結。

流程 2：先在 Listings API 中建立，再連結

  1. 在 Listings API 中建立地點時一併加入其地點操作連結（建立地點），或稍後再新增這些連結（更新地點）。
  2. 連結至 Google Business Profile時，Listings API 會擷取目前的連結，並將其合併至受管理連結集合：
    • 可明確比對的連結會加入受管理連結集合；
    • Google 中任何無法自動合併的連結（或只是尚未納入受管理連結集合的連結），都會顯示在 discoveredPlaceActionLinks 下，供您檢視。
  3. 每次提交至 Google 時，Listings API 都會重新檢查目前的連結。任何直接在 Google Business Profile中發現、且尚未由 Listings API 管理的新連結，都會加入 discoveredPlaceActionLinks。

已發現的連結是指存在於商家的 Google Business Profile中，但未由 Listings API 管理的地點操作連結。這些連結會透過上述流程匯入（連結帳戶時找到的額外連結，或後續提交時找到的新連結），並由每個讀取端點在 discoveredPlaceActionLinks 下（結構與 placeActionLinks 相同）與您管理的連結分開傳回：清單、依 ID、依商店代碼及搜尋。

JSON
{  "id": "TG9jYXRpb246MTgwMTAyMQ==",  "placeActionLinks": [ /* links you already manage */ ],  "discoveredPlaceActionLinks": [    {      "placeActionType": "APPOINTMENT",      "uri": "https://book.example.com",      "isPreferred": false,      "name": "locations/1944.../placeActionLinks/abc123",      "providerType": "MERCHANT",      "isEditable": true    }  ]}

若要開始管理已發現的連結，請使用 action: "add" 將其傳送至更新地點，呼叫方式與新增任何連結相同（以 placeActionType + uri 識別）。其他連結不受影響。

Shell
curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "APPOINTMENT", "uri": "https://book.example.com", "isPreferred": false, "action": "add" }      ]    }  }'

完成後，該連結會顯示在 placeActionLinks 下，並從 discoveredPlaceActionLinks 中移除。您未接管的已發現連結會繼續列在清單中（如果之後從 Google 消失，也會自動從清單移除）；您無須採取任何動作。

範例

每次更新都會傳回該地點完整且最新的 placeActionLinks 集合（反映此次變更）。剛完成寫入時，連結的 name 和 submissionStatus 皆為 null；待連結同步至 Google 後，這些欄位才會填入值。

Shell
curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "action": "add" }      ]    }  }'

變更 URL 就是在同一個請求中移除舊連結，並新增新連結。如果舊連結已同步至 Google，請在 delete 中包含其 name，以取得最精確的比對結果；否則會使用 placeActionType + uri。

Shell
curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com",     "name": "<link-name-if-synced>", "action": "delete" },        { "placeActionType": "FOOD_ORDERING", "uri": "https://new-order.example.com", "isPreferred": true, "action": "add" }      ]    }  }'

若只要變更 isPreferred（URL 不變），請使用 action: "add" 和新值重新傳送該連結。

Shell
curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_DELIVERY", "uri": "https://deliver.example.com", "name": "<link-name-if-synced>", "action": "delete" }      ]    }  }'

建立時，每個連結都是新的，因此 action 預設為 add。

Shell
curl -X POST 'https://listingsapi.com/api/v4/locations' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "name": "Acme Dental",      "description": "<business description, minimum 200 characters>",      "countryIso": "US",      "city": "New York",      "subCategoryId": 1432,      "placeActionLinks": [        { "placeActionType": "APPOINTMENT", "uri": "https://book.acmedental.example.com", "isPreferred": true },        { "placeActionType": "ONLINE_APPOINTMENT", "uri": "https://virtual.acmedental.example.com" }      ]    }  }'

注意事項

  • 每種類型最多只能有一個首選連結。
  • 連結的 submissionStatus 反映最近一次同步至 Google 的狀態（success、failed 等），並附有人類可讀的 submissionMessage。
  • Google 僅會將地點操作連結套用至已驗證的地點。