选择集成方式

根据您的应用架构和集成要求，比较 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 可在单次响应中获取所有分页结果。发送 API 请求之前，数字 ID 会自动进行 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。 将 webhook 与 REST API、SDK 或 MCP 服务器结合使用，以接收事件驱动的更新。当地点、商家信息、评价或帖子发生变化时，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`, `after`	`edges[].node`, `pageInfo.endCursor`, `pageInfo.hasNextPage`	地点、地点搜索、评价
偏移量	`page`, `perPage`	`records[]`, `pageInfo.totalRecords`, `pageInfo.totalPages`	已连接账户、建议、帖子、重复项汇总
无		普通数组	国家／地区、子类别、套餐站点、某个地点的照片

以下示例使用 3 种集成方式执行相同的地点列表查询操作。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 为每个账户配置 1 个 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 SDK	TypeScript 服务、无服务器应用、控制台	来自 `LISTINGSAPI_KEY` 的 API 密钥	是，`fetchAll: true`	Node SDK
MCP	Claude、Cursor 和其他 AI 助手	API 密钥或 OAuth	是，工具会返回完整结果	`/dashboard/mcp`
Webhook	在数秒内响应变更	每次投递都附带 HMAC 签名	不适用，每次投递包含 1 个事件	Webhook 概述

后续步骤

添加地点：使用您所选的方式执行首次写入调用。
通过 webhook 响应事件：搭建可验证签名的接收端。
Python SDK和Node SDK：安装、配置并阅读方法表。
身份验证、速率限制和错误代码：所有方式共用的 3 份参考文档。