Listings APIListings API
登入

新增地點

使用發布平台所需的欄位建立地點、處理驗證錯誤，並確認地點已排入提交佇列。

商家資訊、評論、貼文和分析資料都以地點 ID 為索引。POST /api/v4/locations 會建立地點，並為您方案中的每個發布平台各排入一筆商家資訊。

1. 準備必填欄位

有 10 個必填欄位。服務區域型商家也必須傳送完整地址：使用 hideAddress: true 時，ListingsAPI 會儲存地址，但不會將地址提交至發布平台。發布平台會將省略的選填欄位顯示為空白，因此請傳送您擁有的所有資料。

欄位必填備註
name是2 至 150 個字元。
description是至少 200 個字元（SY10005）。
countryIso是支援國家的 2 字母代碼（SY10036）。
city是當該國家的 hasCity 為 true 時必填（SY10126）。若其值為 false，您傳送的城市會被捨棄。
subCategoryId是子類別清單中的數值型 databaseId。
street是5 至 100 個字元（SY10011）。
stateIso是當該國家的 stateRequired 為 true 時必填，且必須是該國家 states 中的其中一個值（SY10010）。若 stateRequired 為 false，請省略此欄位。
postalCode否此欄位為選填，但只要該國家的 hasPostalCode 為 true，就請傳送。您傳送的值必須符合該國家的格式（SY10014）。
phone是依據該國家進行驗證（SY10015）。
bizUrl是會以網站網址發布。部分發布平台會拒絕沒有網站網址的商家資訊。
storeId否您自己的門市代碼，在整個帳戶內必須唯一。您可以使用此代碼再次尋找地點，無須儲存我們的 ID。
businessHours否一週中的每一天各有一筆項目。格式請參閱更新地點。

2. 建立地點

POST /api/v4/locations 接收 JSON 請求主體中 input 物件內的欄位。Python SDK 方法 locations.add() 會以關鍵字引數接收相同欄位，並在傳送請求前驗證必填欄位。Node SDK 方法 createLocation() 則直接接收 camelCase 物件。

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",    "storeId": "ACME-NYC-001",    "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 farms. Open for lunch and dinner seven days a week, with takeout and delivery available.",    "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": "11:00am", "end": "10:00pm" }] },      { "day": "TUESDAY",   "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "THURSDAY",  "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "FRIDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "11:00pm" }] },      { "day": "SATURDAY",  "type": "OPEN",   "slots": [{ "start": "12:00pm", "end": "11:00pm" }] },      { "day": "SUNDAY",    "type": "CLOSED", "slots": [] }    ]  }}'

3. 閱讀回應

建立成功時會回傳 success: true，並在 data.createLocation.location 中回傳新地點。請保留這兩個識別碼：id 是後續每次寫入所需的 base64 值，而 databaseId 是儀表板和 webhook 承載資料中顯示的數值。

JSON
{  "data": {    "createLocation": {      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME-NYC-001",        "name": "Acme Kitchen",        "city": "New York",        "stateIso": "NY",        "countryIso": "US",        "status": "PENDING"      }    }  }}

地點進行驗證並排入佇列期間，status 為 PENDING。狀態會自行往下更新，您不需要再呼叫 API。

4. 處理驗證錯誤

建立作業可能在兩個環節失敗。請求格式錯誤或金鑰無效時，會回傳 4xx，其中包含頂層 errors 陣列。若請求格式正確，但有欄位遭 API 拒絕，則會回傳 200，其中包含 success: false，並在 data.createLocation.errors 中提供問題詳情，因此請檢查每次寫入的回應主體，而不只是狀態碼。

JSON
{  "data": {    "createLocation": {      "success": false,      "errors": [        {          "code": "SY10005",          "message": "SY10005: description must be at least 200 characters",          "path": ["input", "description"]        }      ],      "location": null    }  }}

兩個 SDK 都會在失敗時拋出例外。Python 的 locations.add() 會在本機檢查必填欄位，並在傳送請求前拋出 ValidationError。當 API 拒絕輸入時，Node 的 createLocation() 會拋出 ValidationError，這就是上方範例未檢查成功旗標的原因。

您最常遇到的代碼：

代碼原因修正方式
SY10005缺少描述，或描述少於 200 個字元。撰寫更完整的描述。
SY10011缺少 street，或其長度少於 5 個字元。傳送 street。
SY10010缺少 stateIso，或其值對該國家無效。傳送從國家端點取得的州代碼。
SY10036countryIso 不是支援的國家。使用從國家端點取得的代碼。
SY10126該國家要求提供 city，但未提供。傳送 city。
SY90016此金鑰僅具有 Read 權限。使用 Write 金鑰。

5. 確認提交程序已開始

建立地點後，系統會為您方案中的每個發布平台各排入一筆商家資訊。每筆商家資訊的初始狀態為 AVAILABLE 或 IN_PROGRESS，發布平台接受後，狀態就會變更為 SYNCED，並附有 listingUrl。

Listing status
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI5MA==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

設定 webhook 後，就不需要輪詢。記錄存在時會觸發 profile.created 事件，而各發布平台的狀態變更時，都會觸發 listing.submission 事件。

後續步驟