入门
创建您的账户,添加付款方式,获取 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 (注意末尾的空格),后接您的密钥:
curl https://listingsapi.com/api/v4/locations \ -H "Authorization: API $LISTINGSAPI_KEY"响应采用嵌套结构,而非直接返回数组:结果位于 data.allLocations 下,每条记录都是一个 edges[].node,pageInfo 包含分页游标和总数。
{ "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 键。