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. 两种 ID

每条记录都有两个标识符。id 是一个 base64 字符串，例如 TG9jYXRpb246MTgwMDI4OQ==，解码后为 Location:1800289。databaseId 是未编码的数字，即 1800289。

请存储 base64 格式的 id。每个写入端点都要求使用 base64 编码的 ID，webhook 载荷中返回的也是这些值。许多在路径中接收地点的读取端点也接受原始数字，两个 SDK 都接受这两种形式，并会为您完成编码。

6. 错误和速率限制

失败响应会返回相应的 HTTP 状态码，并附带一个 errors 数组。消息以 SY 错误代码为前缀，具体代码列在错误代码中：

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

速率限制因套餐而异，分别按分钟、小时和天计数。Launch 允许每分钟发送 10 个请求。超出限制时，API 会返回 429，并附带 Retry-After 响应头；请等待该响应头指定的秒数后再重试，不要立即重试。SDK 会抛出 RateLimitError，并提供相同的值。完整说明请参阅速率限制。

后续步骤