Listings APIListings API
登入

更新地點的詳細資料與營業時間

變更聯絡資料、發布包含單次覆寫設定的完整每週營業時間表、標記暫時停業、設定 Google 類別，並讀回變更結果。

POST /locations/update 會執行部分更新。所有欄位都放在 input 下，input.id 是唯一的必填欄位，省略的欄位會保留目前的值。以下各節只會變更 JSON 請求主體。

1. 更新電話與網站

傳送 id 以及要變更的欄位。發布平台會將 bizUrl 發布為網站網址。Python SDK 的 locations.update() 接受使用 camelCase 鍵的 dict，Node SDK 的 updateLocation() 則接受相同的物件。

Phone and website
curl -X POST https://listingsapi.com/api/v4/locations/update \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "phone": "5125550199",    "bizUrl": "https://acmekitchen.example.com"  }}'
JSON
{  "data": {    "updateLocation": {      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "name": "Jenny Home",        "phone": "5125550199",        "status": "APPROVED"      }    }  }}

驗證失敗時仍會回傳 HTTP 200，並附上 success: false，原因則放在 data.updateLocation.errors 中，因此請檢查 success，而非狀態碼。這種情況下，兩個 SDK 都會拋出 ValidationError。

2. 設定每週營業時間

businessHours 是一個陣列，一週中的每一天各有一個項目。請務必傳送全部七個項目，並使用 type: "CLOSED" 和空的 slots 陣列標記休息日，不要省略該日。同一天內的時段不得重疊。

欄位值備註
dayMONDAY 至 SUNDAY，或 SPECIALSPECIAL 是針對 specialDate 中指定日期的單次覆寫設定。
typeOPEN 或 CLOSED非營業日請搭配使用 CLOSED 與 slots: []。
slots[].start, slots[].end09:00am, 05:00pm使用附有 am 或 pm 的 12 小時制時間。若分段營業，每天可設定多個時段。
specialDateYYYY-MM-DD僅用於 SPECIAL 項目，必須與一週七天的項目一併傳送，絕不可取代這些項目。
moreHours[]hoursTypeId, moreHour[]外送或得來速等次要營業時間表。moreHour 使用相同的 day、type、slots 結構，且不含 specialDate。
Weekly hours
curl -X POST https://listingsapi.com/api/v4/locations/update \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "businessHours": [      { "day": "MONDAY",    "type": "OPEN",   "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "TUESDAY",   "type": "OPEN",   "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN",   "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "THURSDAY",  "type": "OPEN",   "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "FRIDAY",    "type": "OPEN",   "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "SATURDAY",  "type": "OPEN",   "slots": [{ "start": "10:00am", "end": "02:00pm" }] },      { "day": "SUNDAY",    "type": "CLOSED", "slots": [] }    ]  }}'

若要設定假日，請在同一個陣列中附加一個 SPECIAL 項目。此項目只會覆寫該日期的設定，不會變更每週的固定營業時間：

JSON
{ "day": "SPECIAL", "type": "CLOSED", "specialDate": "2026-12-25", "slots": [] }

3. 標記暫時停業或隱藏地址

temporarilyClosed: true 會將商家標記為停業，並停止發布其營業時間。將其設為 false 即可恢復營業。對於服務區域商家，請設定 hideAddress: true：ListingsAPI 會在地點資料中保留地址，但不會將地址提交至發布平台。

Temporary closure
curl -X POST https://listingsapi.com/api/v4/locations/update \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "id": "TG9jYXRpb246MTgwMDI4OQ==", "temporarilyClosed": true } }'

4. 設定 Google 類別

Google Business Profile 有自己的類別分類系統，與數字形式的 subCategoryId 不同。primaryGbpSiteCategoryId 接受 GCID，例如 gcid:restaurant，而 additionalGbpSiteCategoryIds 則接受更多 GCID。兩者都會根據 countryIso 解析，因此請在同一次呼叫中傳送國家。

Google categories
curl -X POST https://listingsapi.com/api/v4/locations/update \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "countryIso": "US",    "primaryGbpSiteCategoryId": "gcid:restaurant",    "additionalGbpSiteCategoryIds": ["gcid:pizza_restaurant", "gcid:italian_restaurant"]  }}'

請勿將這些欄位與 additionalCategoryIds 混淆，後者接受來自子類別端點的整數 databaseId 值。請參閱查詢國家、州與類別。

5. 讀回地點資料

GET /locations-by-ids 會回傳一個或多個 base64 ID 對應的完整記錄，這些 ID 以 JSON 陣列形式透過 ids 查詢參數傳入。請將 phone、businessHours 和 temporarilyClosed 與您傳送的內容比較。

Verify
curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ=="]' \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getLocationsByIds": [      {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "name": "Jenny Home",        "phone": "5125550199",        "hideAddress": false,        "temporarilyClosed": true      }    ]  }}

您帳戶中不存在的 ID 會從陣列中排除，且不會產生錯誤，因此請比較回傳的數量與您請求的數量。

若已設定 webhook，就會觸發 profile.updated 事件。此事件經過防抖動（debounce）處理，每個地點每 60 秒只傳送一次，並在首次觸發時立即傳送：該時段內的後續編輯會合併處理，而 changed_fields 僅描述啟動該時段的那次編輯。請在收到事件時讀回地點資料，並在該時段結束後再次讀回。

後續步驟