Listings APIListings API
登入

發出您的第一個 API 呼叫

進行驗證、列出您的地點、了解回應結構、逐頁瀏覽結果，並了解 ID 的運作方式。

本指南假設您已有帳戶，並已依照入門指南取得 API 金鑰。每個請求都會呼叫位於 https://listingsapi.com 的正式環境 API，因此使用一般 API 金鑰進行寫入呼叫會變更實際資料。若要試用 API 而不影響實際發布平台，請使用免費沙箱單日通行證。

1. 設定您的 API 金鑰

從儀表板的 API 金鑰複製金鑰，並在您的 shell 中執行一次以下指令，將其匯出為環境變數：

bash
export LISTINGSAPI_KEY="your-api-key"

金鑰具有存取權限等級。Read（讀取）金鑰可用於這些指南中的所有查詢和報表。建立或更新任何內容、回覆評論或發布貼文，都需要 Write（寫入）金鑰。將 Read 金鑰傳送至寫入端點時，端點會傳回 HTTP 400，並附上錯誤代碼 SY90016。

2. 列出您的地點

其他端點會透過 ID 參照地點，因此請先列出您現有的地點。REST 的 Authorization 標頭使用 API 驗證方案，後面接一個空格和您的 API 金鑰：Authorization: API <YOUR_API_KEY>。

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

3. 讀取回應

REST API 會傳回巢狀結構的回應，而非單純的陣列。操作名稱位於 data 下，清單結果以包含 edges 的 connection 結構傳回，而每個 edge 都包含一個 node：

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "approved": "APPROVED",            "subCategoryName": "Restaurants"          }        }      ],      "pageInfo": {        "hasNextPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ=="      }    }  }}

Python SDK 會傳回可迭代的物件分頁。Node SDK 會傳回 locations 和 pageInfo。直接呼叫 REST API 時，請讀取 data.allLocations.edges[].node。

4. 逐頁讀取結果

地點和評論的清單端點使用游標分頁。請使用 first 請求一頁資料，再將 pageInfo.endCursor 作為 after 傳入，以取得下一頁。SDK 可以為您讀取所有分頁。

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

並非所有端點都使用這種分頁方式。已連結帳戶、重複商家資訊彙總和貼文使用 page、perPage 以及 records 陣列。各指南都會說明其端點使用的分頁格式。

5. 2 種 ID

每筆記錄都有 2 個識別碼。id 是 base64 字串，例如 TG9jYXRpb246MTgwMDI4OQ==，解碼後為 Location:1800289。databaseId 則是單純的數字，也就是 1800289。

請儲存 base64 格式的 id。每個寫入端點都要求使用 base64 編碼的 ID，webhook 酬載中傳回的也是這些值。許多在路徑中接受地點參數的讀取端點也接受原始數字，而這 2 個 SDK 都接受任一格式，並會為您編碼。

6. 錯誤與速率限制

失敗的回應會傳回對應的 HTTP 狀態，並附上 errors 陣列。訊息開頭會加上 SY 錯誤代碼，代碼清單列於錯誤代碼：

JSON
{  "data": { "allLocations": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

速率限制依方案而定，並分別按每分鐘、每小時及每日計算。Launch 方案每分鐘允許 10 次請求。超過限制時，API 會傳回 429，並附上 Retry-After 標頭；請等待該標頭指定的秒數，不要立即重試。SDK 會拋出 RateLimitError，並提供相同的值。完整說明請參閱速率限制。

後續步驟