入门

创建您的账户,添加付款方式,获取 API 密钥,并首次调用 Listings API。

本指南介绍如何创建账户、获取您的第一个 API 密钥,以及向 Listings API 发起请求。

1. 创建您的账户

在定价页面选择套餐以打开注册表单,然后填写您的名字、姓氏、工作邮箱和公司。已有账户?请直接登录。

2. 添加付款方式

提交表单后,我们会将您转到支付服务提供商的页面,以添加付款卡。您的免费试用会立即开始,并在试用结束后转为您选择的套餐,因此如果您不希望被扣费,请在试用结束前取消。定价常见问题列出了当前试用时长和套餐限额。

3. 设置密码并登录

结账完成后,我们会通过电子邮件向您发送链接,用于设置密码并激活账户。设置密码后,请使用邮箱和密码登录,或者选择 Email me a sign-in link(通过邮件向我发送登录链接),以接收一次性免密登录链接。

4. 获取您的 API 密钥

创建账户时,系统会自动签发您的第一个 API 密钥,您可以在控制台的 API Keys 下找到它。要创建另一个密钥,请选择 New key(新建密钥),为其命名,并选择访问级别(Read(读取)或 Write(写入))。

5. 发起您的第一个请求

每个请求都需使用 Authorization 请求头进行身份验证,其值为字面字符串 API (注意末尾的空格),后接您的密钥:

Request
curl https://listingsapi.com/api/v4/locations \  -H "Authorization: API $LISTINGSAPI_KEY"

响应采用嵌套结构,而非直接返回数组:结果位于 data.allLocations 下,每条记录都是一个 edges[].node,pageInfo 包含分页游标和总数。

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "countryIso": "US"          }        }      ],      "pageInfo": {        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "hasNextPage": false,        "total": 1      }    }  }}

要获取下一页,请在 pageInfo.hasNextPage 为 true 时,将 pageInfo.endCursor 作为 ?after=… 传回;如果某一页返回的 edges 数组为空,也应停止。每个 edge 还包含自己的 cursor,最后一个 edge 的 cursor 就是该页的 endCursor,因此这两个值都可以用作 ?after=。

并非所有列表端点都使用相同的分页方式

上面的 edges / node / pageInfo 结构采用 Relay 游标分页方式,它只是以下 3 种分页方式之一:

  • 游标分页(first、after → edges[].node,以及包含 endCursor / hasNextPage 的 pageInfo):地点、地点搜索和评价端点(单个地点的互动和账户内的汇总)。
  • 偏移量分页(page、perPage → records 数组,以及包含 totalRecords、totalPages、hasNextPage、hasPreviousPage 的 pageInfo):已连接的账户、连接建议、单个地点的帖子、单个地点的批量帖子,以及整个账户内的重复商家信息汇总。
  • 普通数组,完全不分页:目录端点(子类别、国家和州、套餐站点)以及单个地点的照片。

编写分页循环之前,请查看该端点文档页上的响应示例;对偏移量分页端点使用游标循环,会读取根本不存在的 edges 键。

后续步骤

  • 沙盒单日通行证:试用地点和商家信息功能,无需提供银行卡。您或您的 AI 代理均可开通。
  • 身份验证:API 密钥请求头和密钥轮换。
  • 错误代码:HTTP 状态码和错误响应结构。
  • SDK:提供类型定义的 Python 和 Node 客户端。