Listings APIListings API
登入

選擇整合方式

根據您應用程式的架構與整合需求，比較 REST API、Python 和 Node SDK、MCP 伺服器及 webhook。

所有整合方式都使用相同的 API 金鑰與基礎 URL：https://listingsapi.com/api/v4。您可以使用 REST API 或 SDK 傳送 API 請求、使用 webhook 接收事件驅動的更新，以及透過 MCP 伺服器在 AI 代理程式的協助下完成整合。

1. 選擇呼叫 API 的方式

REST API。使用 REST API，透過 HTTP 直接存取所有端點。您的應用程式必須解析回應、處理兩種分頁方式，並檢查 errors[] 陣列是否包含 API 錯誤。

Python SDK。使用 pip install listingsapi 安裝 Python SDK。SDK 透過 client.locations 和 client.reviews 等介面提供資源類別。它會使用 auto_paging_iter() 處理游標分頁、重試傳回 429 或 5xx 回應的請求，並在傳送 API 請求之前，於 locations.add() 中驗證地點承載資料。請參閱 Python SDK。

Node SDK。使用 npm install listingsapi-js 安裝 Node SDK。它需要 Node.js 18 或更新版本，包含 TypeScript 型別定義，且沒有執行階段相依套件。SDK 方法直接提供於用戶端實例上，例如 client.fetchAllLocations()。設定 fetchAll: true，即可在單一回應中擷取所有分頁結果。數字 ID 會在傳送 API 請求之前自動以 Base64 編碼。請參閱 Node SDK。

MCP 伺服器。使用 Streamable HTTP，將 Claude、ChatGPT、Cursor 和 Gemini 等 AI 用戶端連線至位於 https://listingsapi.com/mcp 的 ListingsAPI MCP 伺服器。無須在本機安裝 MCP 伺服器。此伺服器提供的工具可用於搜尋 ListingsAPI 文件、探索 REST 端點，以及執行支援的 API 操作。驗證使用 API 金鑰或 OAuth。開啟 /dashboard/mcp，即可查看用戶端設定、可用的 MCP 工具，以及各工具所需的 API 金鑰權限等級。透過 MCP 連結 AI 代理程式。

Webhook。搭配 REST API、SDK 或 MCP 伺服器使用 webhook，以接收事件驅動的更新。當地點、商家資訊、評論或貼文發生變更時，ListingsAPI 會向您帳戶所設定的 webhook URL 傳送 HTTP POST 請求。這讓您的應用程式能夠處理變更，無須輪詢 API 以取得更新。請參閱 Webhook 概覽。

2. 瞭解驗證模型

REST API 和 SDK 使用 API 金鑰驗證請求。請使用 API 驗證配置，在 HTTP Authorization 請求標頭中傳入金鑰：

Authorization: API <YOUR_API_KEY>

API 金鑰具有 Read（讀取）或 Write（寫入）存取權限。Read 金鑰可存取讀取操作，包括查詢與報表。建立或更新資源的操作需要 Write 金鑰。向寫入端點傳送 Read 金鑰時，端點會傳回 HTTP 400，並附上錯誤碼 SY90016。

API 金鑰的作用範圍限於單一帳戶。使用同一帳戶的金鑰發出的請求，會共用該帳戶層級的速率限制配額。

MCP 伺服器也支援 OAuth 驗證。MCP 用戶端可以透過瀏覽器使用 OAuth 進行驗證，無須提供 API 金鑰。REST API 和 SDK 請求則使用 Authorization 標頭進行驗證。設定詳細資訊請參閱驗證文件。

3. 瞭解分頁模式

REST 清單端點使用游標式或位移式分頁。SDK 會將這些分頁模式抽象化。

游標式端點接受 first 和 after。結果透過 edges[].node 傳回，而 pageInfo.endCursor 會提供下一次請求所需的游標。

位移式端點接受 page 和 perPage。結果會在 records[] 中傳回，而 pageInfo.totalRecords 會回報可用記錄的總數。

類型參數承載資料使用項目
游標first, afteredges[].node, pageInfo.endCursor, pageInfo.hasNextPage地點、地點搜尋、評論
位移page, perPagerecords[], pageInfo.totalRecords, pageInfo.totalPages已連結帳戶、建議、貼文、重複項目彙總
無一般陣列國家、子類別、方案網站、單一地點的相片

以下範例使用三種整合方式執行相同的地點清單查詢。cURL 實作需要應用程式直接解析 API 回應結構。

List locations
curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY" # Read data.allLocations.edges[].node, then pass# data.allLocations.pageInfo.endCursor back as ?after= for the next page.

所有整合方式的 API 錯誤都會在 errors[] 陣列中傳回，每則錯誤訊息都會以 SY 錯誤碼作為前綴。寫入請求可能傳回 HTTP 200 並包含 success: false，因此必須先檢查回應主體，才能將操作視為成功。

當帳戶超過其速率限制時，API 會傳回 HTTP 429，並附上 Retry-After 標頭。Launch 方案每分鐘最多支援 10 次請求。詳情請參閱錯誤碼和速率限制文件。

4. 選擇 webhook 或輪詢

當您的應用程式需要按固定排程取得資源狀態，例如每晚同步所有地點，或所需事件不支援 webhook 時，請使用輪詢。當您的應用程式需要在變更發生時立即處理，例如收到新評論、商家資訊狀態變更或 Google 貼文遭拒時，請使用 webhook。

在 /dashboard/webhooks 為每個帳戶設定一個 webhook URL。每個 webhook 請求都包含 X-ListingsAPI-Signature 標頭，格式如下：

X-ListingsAPI-Signature: sha256=<base64 HMAC>

webhook 端點必須在 5 秒內傳回 2xx 回應。傳送失敗後不會重試。

使用 webhook 事件作為觸發條件，從 API 擷取目前的資源狀態。由於 webhook 傳送失敗後不會重試，請執行排程核對程序，以偵測可能遺漏的更新。實作範例請參閱使用 webhook 回應事件。

5. 快速比較

選項最適合驗證方式是否自動處理分頁？延伸閱讀
REST所有端點，以及您偏好的技術組合與 HTTP 用戶端API 金鑰標頭否，您需要自行依游標或頁碼取得後續結果開始使用
Python SDK後端工作、資料管線、指令碼來自 LISTINGSAPI_KEY 的 API 金鑰是，透過 SyncPage 和 auto_paging_iter()Python SDK
Node SDKTypeScript 服務、無伺服器運算、儀表板來自 LISTINGSAPI_KEY 的 API 金鑰是，透過 fetchAll: trueNode SDK
MCPClaude、Cursor 和其他 AI 助理API 金鑰或 OAuth是，工具會傳回完整結果/dashboard/mcp
Webhook在數秒內回應變更每次傳送都附有 HMAC 簽章不適用，每次傳送一個事件Webhook 概覽

後續步驟