Listings APIListings API
登入

查詢國家、州與類別

在建立地點之前，取得支援的國家與州代碼、查出商家類別對應的數字 id，並查看您的方案涵蓋哪些發布平台。

建立地點需要三項必須從 API 取得的值：API 接受的 countryIso 和 stateIso、數字 subCategoryId，以及在您想限制發布平台時所需的方案內網站 id。這些值由三個目錄端點提供，三者皆傳回一般陣列，且不分頁。

1. 列出國家與州代碼

GET /countries 會傳回所有支援的國家，以及各國的 ISO 代碼、hasCity 旗標和 states 陣列。建立和更新時，iso 的值用於填入 countryIso 和 stateIso。Python SDK 透過 client.countries() 提供此功能，Node SDK 則透過 client.fetchCountries() 提供。

Countries
curl https://listingsapi.com/api/v4/countries \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "supportedCountries": [      {        "databaseId": 13,        "iso": "AU",        "name": "Australia",        "hasCity": true,        "states": [          { "id": "139", "iso": "VIC", "name": "Victoria" },          { "id": "142", "iso": "NSW", "name": "New South Wales" }        ]      },      {        "databaseId": 17,        "iso": "BE",        "name": "Belgium",        "hasCity": true,        "states": []      }    ]  }}

hasCity: true 表示建立時必須提供 city；若為 false，您傳送的城市會被捨棄。stateRequired: true 表示必須提供 stateIso，且其值必須是該國的 states 之一；若為 false，請省略此欄位。hasPostalCode: true 表示該國使用郵遞區號，因此請隨地址一併傳送 postalCode。國家端點 說明了各個旗標。

2. 尋找類別 id

GET /sub-categories 會傳回完整的類別目錄。您作為 subCategoryId 傳送的值是整數 databaseId，而非 base64 id。例如，餐廳類別的值是 1432。請在您自己的程式碼中依名稱篩選清單；伺服器端沒有搜尋參數。

Find a category
curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.subcategories[] | select(.name | test("restaurant"; "i")) | {databaseId, name, primary}'
JSON
{  "data": {    "subcategories": [      {        "databaseId": 1432,        "id": "U3ViQ2F0ZWdvcnk6MTQzMg==",        "key": "restaurants",        "name": "Restaurants",        "primary": true      }    ]  }}
欄位用途
databaseId作為 subCategoryId 傳送的整數，或放在 additionalCategoryIds 中，以指定最多 9 個次要類別。
name用於在選擇器中顯示及進行比對的易讀標籤。
key名稱的 URL 友善 slug，重新命名後仍維持不變。
primary該類別是否可作為地點的主要子類別。請僅為 subCategoryId 選擇 true 項目。

3. 查看您的方案涵蓋哪些發布平台

GET /plan-sites 會列出您方案中的所有發布平台，以及各平台的數字 id、url、接受的國家和支援 hideAddress 的國家。這些 id 是建立時 enabledSiteIds 和更新時 submissionDisabledSiteIds 唯一有效的值。請依地點所在的國家篩選，讓您只提供會接受該地點的發布平台。

Plan sites
curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.planSites[] | select(.supportedCountries | index("US")) | {id, name, url}'
JSON
{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 2,        "name": "Yelp",        "url": "yelp.com",        "supportedCountries": ["US", "CA", "GB", "DE", "FR"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "GB"]      }    ]  }}

此處的兩個國家陣列皆已截短；實際回應可能會為每個網站列出 50 個以上的代碼。若為服務區域商家，也請檢查 hideAddressSupportedCountries，因為接受該國家的發布平台仍可能拒絕沒有街道地址的商家資訊。

4. 快取這些查詢結果

這三個目錄很少變動，且皆不分頁，因此請在啟動時各擷取一次，存放於記憶體或小型資料表中，並定期重新整理。每次建立時都在流程中呼叫這些端點，會消耗速率限制額度，卻不會傳回新資料；以 Launch 方案而言，這會占用您每分鐘 10 次請求額度中的 3 次。

目錄大小重新整理時機
國家數十個國家、數百個州不需頻繁重新整理。每天一次已綽綽有餘。
子類別約 6,000 筆每天，或建立操作因未知的 subCategoryId 而失敗時。
方案內網站數十個發布平台方案變更時，因為此清單的範圍取決於您的方案。

為子類別建立小寫 name 到 databaseId 的對應表，並為國家建立 countryIso 到 states 的對應表。在呼叫建立操作之前，請根據快取驗證地址，讓您的應用程式能在送出請求之前，偵測到不支援的 countryIso（SY10036）或缺少的 city（SY10126）。

後續步驟