地點

依使用順序介紹所有地點端點，每個端點均附有 cURL、Python 和 Node 範例，涵蓋列出、搜尋、依 id 和門市代碼查詢、建立、更新、封存及相片管理。

商家資訊、評論、貼文和分析資料皆以地點 ID 作為索引鍵。地點資源共有 13 個端點：4 個用於尋找地點的讀取端點、4 個用於建立、變更和封存地點的寫入端點，以及 5 個用於管理相片的端點。Read（讀取）金鑰可用於讀取端點。每個 POST 都需要 Write（寫入）金鑰；使用 Read 金鑰呼叫寫入端點時，端點會傳回 HTTP 400，並附上 SY90016。

本指南中的每個 id 都是 base64 編碼的 Relay id，例如 TG9jYXRpb246MTgwMDI4OQ==（解碼後為 Location:1800289）。兩個 SDK 也都接受數字形式的 databaseId，並會為您編碼。

端點一覽

方法	路徑	功能	參考文件
`GET`	`/locations`	分頁瀏覽所有地點，從最新的開始。	列出所有地點
`GET`	`/locations/search`	依關鍵字搜尋名稱、地址和商店 id，以尋找地點。	搜尋地點
`GET`	`/locations-by-ids`	依一批 base64 編碼的 id 取得完整記錄。	依 ID 取得地點
`GET`	`/locations-by-store-codes`	依您自己的門市代碼取得完整記錄。	依門市代碼取得地點
`POST`	`/locations`	建立地點，並將其加入提交佇列。	建立地點
`POST`	`/locations/update`	變更單一地點的任何可寫入欄位。	更新地點
`POST`	`/locations/archive`	排定在計費週期結束時封存地點。	封存地點
`POST`	`/locations/cancel_archive`	將已排定封存的地點恢復為使用中狀態。	取消排定的封存
`POST`	`/locations/photos`	透過 URL 附加標誌、封面或相簿相片。	上傳相片
`GET`	`/locations/photos/requests/{requestId}`	輪詢已加入佇列的大量上傳作業。	檢查大量上傳狀態
`GET`	`/locations/{locationId}/photos`	列出地點的所有媒體檔案。	取得相片
`POST`	`/locations/photos/star`	為其他相片加上或移除星號。	為相片加上星號
`POST`	`/locations/photos/remove`	解除其他相片的附加關係。	移除相片

列出所有地點

GET /locations 會分頁列出帳戶中的所有地點，從最新的開始。它採用游標連線：edges[].node 包含各筆記錄，而 pageInfo.endCursor 則作為下一頁的 after 參數值。使用此端點可將整個帳戶的資料同步至您自己的系統。

參數

名稱	位置	必填	備註
`first`	query	否	向後翻頁時每頁的筆數。預設為 50。與 `after` 搭配使用。
`after`	query	否	上一頁的 `pageInfo.endCursor`。
`last`	query	否	往回翻頁時每頁的筆數。與 `before` 搭配使用。
`before`	query	否	您往回翻頁前所在頁面中，第一個 edge 的 `cursor`。`pageInfo` 沒有 `startCursor`。
`filter`	query	否	以 JSON 編碼的物件，用於在伺服器端縮小結果範圍，例如依核准狀態篩選。兩個 SDK 的列出方法都不接受此參數；若要取得篩選後的部分資料，請呼叫 REST。

List

curl "https://listingsapi.com/api/v4/locations?first=50" \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "storeId": null,            "approved": "APPROVED",            "archived": false,            "archivalScheduledAt": null,            "city": "Austin",            "stateIso": "TX",            "countryIso": "US",            "subCategoryId": 1432,            "planName": "Launch",            "placeActionLinks": [],            "discoveredPlaceActionLinks": []          }        }      ],      "pageInfo": {        "hasNextPage": false,        "hasPreviousPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "total": 1      }    }  }}

讀取 pageInfo.hasNextPage，並在其值為 false 時停止。該頁的筆數為 pageInfo.total。節點的 id 是其他所有端點所需的識別碼。

搜尋地點

GET /locations/search 會以關鍵字比對地點名稱、街道地址、城市和商店 id。它採用游標連線，edges[].node 和 pageInfo.endCursor 的結構與列出端點相同。您可將它用於輸入時即顯示建議的選擇器，或在建立商店前確認商店是否已存在。

參數

名稱	位置	必填	備註
`query`	query	否	搜尋關鍵字。省略此參數即可分頁瀏覽所有地點，不進行篩選。
`first`	query	否	每頁筆數。預設為 50。
`after`	query	否	上一頁的 `pageInfo.endCursor`。
`filter`	query	否	以 JSON 編碼的篩選物件，與列出端點相同。

兩個 SDK 也都接受 fields 清單，將比對範圍限制在特定欄位，例如僅比對 name。

curl "https://listingsapi.com/api/v4/locations/search?query=Jenny&first=10" \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "searchLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "storeId": null,            "street": "600 Congress Ave, Suite 200",            "city": "Austin",            "approved": "APPROVED",            "archived": false          }        }      ],      "pageInfo": {        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "hasNextPage": false,        "hasPreviousPage": false,        "total": 1      }    }  }}

空的 edges 陣列表示沒有符合的結果。節點包含完整地址、類別和 approved 狀態，因此每筆結果都不需要再次查詢。

依 ID 取得地點

GET /locations-by-ids 可在一次呼叫中傳回一批 base64 ID 對應的完整記錄，比逐一呼叫每個地點所需的請求更少。啟用中與已封存的地點都能查得。它會傳回一般陣列，而非游標連線。您可用它取得 webhook 承載資料或您自己資料庫中各個 ID 對應的完整資料。

參數

名稱	傳入位置	必填	備註
`ids`	query	是	以 JSON 編碼的 base64 ID 陣列。請對整個值進行 URL 編碼；`curl -G --data-urlencode` 會為您完成這項處理。

By ids

curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ==","TG9jYXRpb246MTgwMDI5MA=="]' \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "getLocationsByIds": [      {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "storeId": null,        "name": "Jenny Home",        "archived": false,        "archivedAt": null,        "city": "Austin",        "stateIso": "TX",        "countryIso": "US",        "subCategoryId": 1432,        "businessHours": [],        "locationPhotos": [],        "placeActionLinks": [],        "discoveredPlaceActionLinks": []      }    ]  }}

您帳戶中不存在的 ID 會直接略過，不會引發錯誤。請比較傳回的數量與您送出的數量，以找出過期的 ID。

依門市代碼取得地點

GET /locations-by-store-codes 提供反向查詢：它會依您自己的門市代碼查出完整記錄。它會傳回一般陣列。如果您的 POS 或加盟店名冊以門市代碼作為地點的索引鍵，而您從未儲存我們的 ID，即可使用此功能。

參數

名稱	傳入位置	必填	備註
`storeCodes`	query	是	以 JSON 編碼的門市代碼字串陣列。請對整個值進行 URL 編碼。

By store codes

curl -G https://listingsapi.com/api/v4/locations-by-store-codes \--data-urlencode 'storeCodes=["ACME01","ACME02"]' \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "getLocationsByStoreCodes": [      {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "storeId": "ACME01",        "name": "Jenny Home",        "archived": false,        "city": "Austin",        "countryIso": "US",        "planName": "Launch"      }    ]  }}

請使用每個物件的 storeId，對應回您名冊中的項目。找不到相符項目的代碼不會出現在結果中。只有在建立或更新時設定了 storeId，地點才會有門市代碼。

建立地點

POST /locations 會建立地點，並將其加入佇列，準備提交至您方案中的每個發布平台；若您傳入 enabledSiteIds 欄位，則只會提交至該欄位指定的發布平台。所有欄位都放在 input 之下。共有 10 個必填欄位，其餘為選填，您省略的欄位在發布平台上會顯示為空白。

參數

名稱	傳入位置	必填	備註
`input.name`	body	是	商家名稱，2 至 150 個字元。
`input.description`	body	是	至少 200 個字元（`SY10005`）。發布平台會將其用作商家資訊的文案。
`input.countryIso`	body	是	支援的國家代碼（`SY10036`）。取自國家。
`input.city`	body	是	當該國家的 `hasCity` 為 `true` 時，此欄位為必填（`SY10126`）。若其值為 `false`，您送出的城市資料會被捨棄。
`input.subCategoryId`	body	是	取自子類別的數值型 `databaseId`。
`input.street`	body	是	5 至 100 個字元（`SY10011`）。
`input.stateIso`	body	是	當該國家的 `stateRequired` 為 `true` 時，此欄位為必填，且必須是該國家的 `states` 之一（`SY10010`）。當 `stateRequired` 為 `false` 時，請省略此欄位。
`input.phone`	body	是	依據該國家進行驗證（`SY10015`）。
`input.postalCode`	body	否	此欄位為選填，但只要該國家的 `hasPostalCode` 為 `true`，就請送出此欄位。您送出的值必須符合該國家的格式（`SY10014`）。
`input.bizUrl`	body	是	會發布為網站網址。部分發布平台會拒絕沒有網站網址的商家資訊。
`input.storeId`	body	否	您自己的門市代碼，在整個帳戶內必須唯一。
`input.businessHours`	body	否	7 筆 `{ day, type, slots }` 項目。`type` 為 `OPEN` 或 `CLOSED`；公休日的 `slots` 為空。
`input.placeActionLinks`	body	否	Google 操作連結：`placeActionType`、`uri`，以及選填的 `isPreferred`。建立時不需要 `action`。請參閱地點操作連結。
`input.enabledSiteIds`	body	否	發布至您方案中的部分網站。ID 取自方案網站。
`input.clientMutationId`	body	否	會原樣傳回，以便建立關聯。無法防止重複寫入。

另外還有參考頁面列出的選填欄位：Google GCID 類別、社群網址、座標、擁有者聯絡資訊、付款方式、服務區域等。

Create

curl -X POST https://listingsapi.com/api/v4/locations \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "name": "Acme Kitchen",    "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby growers. Our dining room seats forty, takeout and delivery run until close, and the bar pours regional wine and beer on tap.",    "storeId": "ACME01",    "street": "123 Jump Street",    "city": "New York",    "stateIso": "NY",    "postalCode": "10013",    "countryIso": "US",    "phone": "6443859313",    "bizUrl": "https://acmekitchen.example.com",    "subCategoryId": 1432,    "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": [] }    ],    "placeActionLinks": [      { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true }    ]  }}'

JSON

{  "data": {    "createLocation": {      "clientMutationId": null,      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME01",        "name": "Acme Kitchen",        "city": "New York",        "countryIso": "US",        "status": "PENDING",        "placeActionLinks": [          { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true, "name": null, "submissionStatus": null }        ],        "discoveredPlaceActionLinks": []      }    }  }}

請保留這兩個 ID：base64 格式的 id 是後續每次寫入所需的值，而 databaseId 則是您在儀表板和 webhook 中看到的數字。status 的初始值為 PENDING，之後會持續更新，無須再次呼叫 API。地點操作連結的 name 和 submissionStatus 會維持為 null，直到該連結同步至 Google。Python 的 locations.add() 會在本機驗證必填欄位，並在發出任何網路呼叫之前拋出 ValidationError；locations.create(input) 則接受原始的 camelCase dict。

更新地點

POST /locations/update 採用部分更新：input.id 是唯一的必填欄位，只有您傳送的欄位會變更。同一個呼叫可用來修正電話號碼或重寫每週時間表。Python 的 locations.update() 和 Node 的 updateLocation() 都接受一個 camelCase 物件。

參數

名稱	所在位置	必填	備註
`input.id`	body	是	地點的 base64 id。欄位是 `id`，不是 `locationId`。
`input.phone`、`input.bizUrl`、`input.name`、地址欄位	body	否	建立呼叫中的任何可寫入欄位。
`input.businessHours`	body	否	請傳送全部 7 天的資料；僅包含一週中部分天數的資料會遭到拒絕。如需覆寫假日時間，請加入帶有 `specialDate` 的 `day: "SPECIAL"` 項目，並與每週時間表一併傳送，絕不可取代每週時間表。
`input.moreHours`	body	否	外送等次要時間表，每個時間表皆為 `{ hoursTypeId, moreHour }`。此處不包含 `specialDate`。
`input.temporarilyClosed`	body	否	`true` 會在地點暫停營業期間停止發布營業時間。
`input.primaryGbpSiteCategoryId`, `input.additionalGbpSiteCategoryIds`	body	否	以 GCID 表示的 Google 類別，例如 `gcid:restaurant`。請一併傳送 `countryIso`。
`input.placeActionLinks`	body	否	附加／新增或更新：每個項目的 `action` 可設為 `add`（預設值）或 `delete`。您未提及的連結會保持不變。
`input.submissionDisabledSiteIds`	body	否	要從提交作業中排除的網站 id。

另可包含參考頁面列出的選填欄位。

Update

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",    "primaryGbpSiteCategoryId": "gcid:restaurant",    "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": [] }    ]  }}'

JSON

{  "data": {    "updateLocation": {      "clientMutationId": null,      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "name": "Jenny Home",        "phone": "5125550199",        "status": "APPROVED",        "placeActionLinks": [          { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "name": null, "submissionStatus": null }        ],        "discoveredPlaceActionLinks": []      }    }  }}

回應會傳回更新後的地點，讓您確認新值已套用。每次更新都會傳回該地點目前完整的 placeActionLinks 集合。若要變更連結的 URL，請在同一個請求中，針對舊連結傳送 delete，並針對新連結傳送 add。

封存地點

POST /locations/archive 會排定封存一個或多個地點。封存不會立即生效：每個地點都會進入 ARCHIVE_SCHEDULED 狀態，在目前的計費週期結束前持續上線並計費，並於下一張帳單產生時封存。您可以使用此功能批次停用已結束營業的分店。

參數

名稱	所在位置	必填	備註
`input.locationIds`	body	是	要封存的地點之 base64 id 陣列。
`input.clientMutationId`	body	否	原樣傳回。不會防止重複寫入。

`result[].status`	意義
`ARCHIVE_SCHEDULED`	已加入佇列。地點會持續上線並計費，直到計費週期結束。
`ARCHIVED`	已在先前的呼叫或週期中封存。

取消已排定的封存

POST /locations/cancel_archive 會將處於 ARCHIVE_SCHEDULED 狀態的地點恢復為 ACTIVE，並繼續計費。此呼叫僅在計費週期尚未結束時有效；地點一旦完全封存，此呼叫就會針對該地點傳回 404。

參數

名稱	所在位置	必填	備註
`input.locationIds`	body	是	目前處於 `ARCHIVE_SCHEDULED` 狀態的地點之 base64 id 陣列。
`input.clientMutationId`	body	否	原樣傳回。

Cancel archive

curl -X POST https://listingsapi.com/api/v4/locations/cancel_archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="] } }'

JSON

{  "data": {    "cancelLocationsArchive": {      "clientMutationId": null,      "bulkEditTaskId": null,      "errors": null,      "success": null,      "result": [        { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ACTIVE", "success": true, "errors": null }      ]    }  }}

每個 result[] 項目都會確認該地點已恢復為 ACTIVE。兩個 SDK 都需要額外提供兩個位置引數，分別為選取類型和 changedBy 識別碼，並會將這些引數與 locationIds 一併傳送；REST 請求主體只需要 id。

將相片上傳至地點

POST /locations/photos 會透過公開 URL 附加圖片：由您託管圖片，API 會擷取並儲存圖片。一個地點可保留 1 張 LOGO、1 張 COVER，以及任意數量的 ADDITIONAL 相片。重新上傳標誌或封面會取代現有圖片。

參數

名稱	所在位置	必填	備註
`input.locationId`	body	是	地點的 base64 id。
`input.photos`	body	是	圖片物件陣列；不得為空。
`input.photos[].photo`	body	是	可公開存取的 JPEG 或 PNG 圖片 URL。欄位是 `photo`，不是 `url`。
`input.photos[].type`	body	否	`LOGO`、`COVER` 或 `ADDITIONAL`。預設為額外相片。
`input.photos[].starred`	body	否	在相片上傳時將其標上星號。僅適用於額外相片，每個地點最多 4 張。
`input.photos[].source`	body	否	記錄圖片來源的自由文字標籤。

Upload

curl -X POST https://listingsapi.com/api/v4/locations/photos \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photos": [      { "photo": "https://cdn.example.com/jenny-home/logo.png", "type": "LOGO" },      { "photo": "https://cdn.example.com/jenny-home/storefront.jpg", "type": "ADDITIONAL" }    ]  }}'

JSON

{  "data": {    "addLocationPhotos": {      "clientMutationId": null,      "success": true,      "request": {},      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "databaseId": 5878931, "type": "LOGO", "starred": false,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.png" },        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "databaseId": 5878932, "type": "ADDITIONAL", "starred": false,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/ef4ffb12.jpg" }      ],      "errors": null    }  }}

請保留每張相片的 id；標星與移除端點都需要此值。這是小批次直接回傳時的格式。大批次則會加入佇列：傳回的 photos 為空，且會設定 request.requestId，您需使用該 id 輪詢下一個端點。門檻由伺服器端設定，因此請根據是否存在 request.requestId 決定處理分支。

檢查大量相片上傳狀態

GET /locations/photos/requests/{requestId} 會輪詢已排入佇列的上傳作業，直到作業結束，然後回報每張圖片的結果。您可以用它來更新進度列，並明確顯示哪些檔案遭到拒絕及其原因。

參數

名稱	所在位置	必填	備註
`requestId`	path	是	已排入佇列的上傳回應中，`request.requestId` 所提供的 UUID。請僅輪詢近期上傳所傳回的 id。

Upload status

curl https://listingsapi.com/api/v4/locations/photos/requests/e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "getLocationPhotosUploadStatus": {      "requestId": "e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a",      "status": "SUCCESS",      "photos": [        { "mediaId": "TWVkaWFGaWxlOjkxODI3", "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "SUCCESS", "errorMessage": null },        { "mediaId": null, "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ERROR", "errorMessage": "Image dimensions below the minimum 250x250." }      ]    }  }}

作業 `status`	意義
`PROCESSING`	仍在處理中。請在幾秒後再次輪詢。
`SUCCESS`	處理已完成。個別相片仍可能處理失敗，因此請查看 `photos[].status` 和 `photos[].errorMessage`。
`ERROR`	作業本身失敗。請檢查 `photos[].errorMessage`。

作業狀態只表示處理已完成，不代表每張圖片都已成功上傳。每次輪詢之間請間隔幾秒；在此處密集循環輪詢，很快就會觸發 429。

取得地點的相片

GET /locations/{locationId}/photos 會以單純的陣列傳回地點上的所有媒體檔案：標誌、封面及其他圖片，每個檔案都包含其公開的 url、thumbnailUrl、類別、starred 旗標，以及整個存續期間的 viewsCount。請在上傳前呼叫此端點，確認哪個欄位尚未有圖片，並收集供加上星號及移除呼叫使用的 id。

參數

名稱	所在位置	必填	備註
`locationId`	path	是	base64 id。也接受原始數字形式的 `databaseId`。若值不屬於這兩種形式，則會傳回 HTTP 200，並在 `errors` 中包含 `SY90002: Invalid Id`。

List photos

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/photos \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "mediaFilesOfLocation": [      { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "categoryName": "Logo", "categoryId": "4", "fileType": "image", "starred": false, "viewsCount": 0,        "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.jpg",        "thumbnailUrl": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/thumbnail_f47d62a6.jpg" },      { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "categoryName": "Additional", "categoryId": "12", "fileType": "image", "starred": true, "viewsCount": 143,        "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/ef4ffb12.jpg",        "thumbnailUrl": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/thumbnail_ef4ffb12.jpg" }    ]  }}

categoryName 為 Logo、Cover 或 Additional。格狀檢視請使用 thumbnailUrl，完整尺寸檢視請使用 url。沒有媒體的地點會傳回空陣列，而非錯誤。

為地點相片加上星號

POST /locations/photos/star 會標記其他相片，讓支援精選圖片的發布平台優先展示這些相片。只有 ADDITIONAL 相片可以加上星號，每個地點最多 4 張。取消星號的方式相同：由請求主體中的 starred 旗標決定執行哪項操作。

參數

名稱	所在位置	必填	備註
`input.locationId`	body	是	地點的 base64 id。
`input.photoIds`	body	是	取得相片或上傳回應中的媒體 id。
`input.starred`	body	是	`true` 表示加上星號，`false` 表示取消星號。操作由此旗標決定，而非路徑；`/star` 和 `/unstar` 的行為相同。

Star

curl -X POST https://listingsapi.com/api/v4/locations/photos/star \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photoIds": ["TWVkaWFGaWxlOjU4Nzg5MzI="],    "starred": true  }}'

JSON

{  "data": {    "starUnstarLocationPhotos": {      "success": true,      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "databaseId": 5878932, "type": "ADDITIONAL", "starred": true }      ],      "error": null    }  }}

這兩個路徑的回應鍵都是 starUnstarLocationPhotos，其中包含單一 error，而非 errors 陣列。第五張加上星號的相片會使整個呼叫失敗，並傳回 SY15012；檢查時計算的數量包含已加上星號的相片，以及本次請求中的相片。

從地點移除相片

POST /locations/photos/remove 會依媒體 id 解除其他相片與地點的關聯。您可以用它來移除過時的店面圖片，或復原有誤的大量匯入。只有 ADDITIONAL 相片可以移除；若要替換標誌或封面，請使用對應的 type 上傳新圖片。

參數

名稱	所在位置	必填	備註
`input.locationId`	body	是	地點的 base64 id。
`input.photoIds`	body	是	要解除關聯的媒體 id，取自取得相片或上傳回應。

Remove

curl -X POST https://listingsapi.com/api/v4/locations/photos/remove \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photoIds": ["TWVkaWFGaWxlOjU4Nzg5MzI="]  }}'

JSON

{  "data": {    "removeLocationPhotos": {      "clientMutationId": null,      "removedCount": 1,      "errors": null    }  }}

removedCount 會回報實際解除關聯的檔案數，因此，若 0 且 errors: null，就表示這些 id 都未與此地點建立關聯。移除操作會解除檔案的關聯，但不一定會將其從您的媒體庫中徹底刪除。

您會遇到的錯誤

代碼	意義	修正方式
`SY10005`	建立時缺少 `description`，或其長度少於 200 個字元。	請撰寫更完整的描述。
`SY10011`	缺少 `street`，或其長度少於 5 個字元。	請傳送 `street`。
`SY10010`	缺少 `stateIso`，或其值不適用於該國家。	請傳送國家中的州別代碼。
`SY10036`	`countryIso` 不是支援的國家。	請使用國家中的代碼。
`SY10126`	該國家要求提供 `city`，但未提供。	請傳送 `city`。
`SY15012`	地點上加上星號的相片超過 4 張。	請先取消其中一張相片的星號，或從上傳請求中移除 `starred`。
`SY90002`	相片路徑中的 id 無效。	請傳入 base64 id 或純數字，不要使用其他形式。
`SY90016`	寫入操作使用了 Read 金鑰。	請使用 Write 金鑰。
HTTP `404`	對已不再處於 `ARCHIVE_SCHEDULED` 狀態的地點取消封存。	地點已完全封存；請改用重新啟用流程。
HTTP `429`	已超過速率限制。	請等待 `Retry-After`。請參閱速率限制。

寫入操作也可能傳回 HTTP 200，並包含 success: false，詳細資訊則位於 data.<operation>.errors。完整清單請參閱錯誤代碼。

後續步驟

新增地點、更新地點、上傳地點相片及尋找並封存地點：運用這些端點的任務指南。
查詢國家與類別：建立時所需的 countryIso、stateIso 及 subCategoryId 值。
地點操作連結：建立與更新時使用的 Google 操作按鈕完整模型。
地點：資源總覽頁面，以及 Python 和 Node 的 SDK 參考文件。
相片方法有各自的 SDK 頁面：Python 相片和 Node 相片。