API（数据）

什么是 API？

API 是 Application Programming Interface 的缩写，是一组规则或协议，允许不同的软件程序交换数据并相互交互。

在 Listly 中，当您想将提取的数据存储到自己的数据库或与 Google Sheets 集成时，可以使用此功能。

提示 如何与 Google Sheets 集成

参考：在 Google Sheets 中导入采集的数据（API 集成）

快速入门

➡️ 选择所需的数据提取结果 ➡️ 点击 API 按钮 ➡️（首次使用）生成令牌 ➡️ 获取 API 令牌和 API URL

---

如何查看 API URL

LISTLY API 可以被视为将提取的数据传送到您想要位置的数据管道。如下所示，每个数据结果页面都有一个 API 按钮，点击它会显示指向该结果的 API URL。访问该 URL 会显示与 Excel 中相同的数据。使用此功能，您可以与 Google Sheets 集成，或编写额外代码将数据放入您自己的数据库。

首次使用 API 按钮的用户会看到如下所示的令牌生成界面。一键生成令牌，返回结果页面，再次点击 API 按钮。

如果您已经配置过，可以在账户设置中查看您的 API 令牌。

---

API URL 类型

主要有 2 种 API URL 类型：

• Latest API：仅显示最新成功提取的数据。

• Log API：显示历次提取的所有数据。

您可以在单次提取和批量提取结果页面上同时使用 Latest 和 Log API。使用下方步骤查看如何检查每种类型。

1

Single Latest 数据

• 单次提取最新数据：在结果中选择 latest 然后查看 API

2

Single Log 数据

• 单次提取日志数据：在结果中选择 log 然后查看 API

3

Group Latest 数据

• 批量提取最新数据：在 Group API 中查看

4

Group Log 数据

• 批量提取日志数据：在日志列表中查看 → 选择所需的日志数据 → 在 Group API 中查看

Latest API 响应消息是 {"message": "Warning! Do not use this API endpoint..."}

当网页设计发生更改时会出现此消息。数据提取仍然正常工作，但这是网页已更改的警告。使用调度器功能进行自动采集时可能会出现此情况。

原则上，我们建议从 LISTLY 扩展程序重新提取。由于网页设计已更改，创建新的参考点从长远来看更好。提取新数据以创建新的起点，重新应用调度器设置，之后您就可以再次稳定使用 Latest API。

如果您想忽略警告并按原样使用现有数据，请使用上述消息中"api_endpoint"区域显示的地址。此时会显示最新提取的数据，"api_endpoint"中显示的地址是现有 API 地址加上忽略警告的选项（&ignore_warning=y）。

API 端点介绍

所有 API URL 都可以在数据提取结果页面上查看，如图所示。

类型	URI	方法
Single (Latest)	www.listly.io/api/single?key=<singlekey>	GET
	显示最新数据。用于接收调度器自动提取的最新数据。
Single (Log)	www.listly.io/api/single/data?key=<datakey>	GET
	显示所有日志数据。用于一次性导入和查看所有累积数据。
Group (Latest)	www.listly.io/api/group?key=<groupkey>	GET
	显示最新批量数据。
Group (Log)	www.listly.io/api/group/data?key=<datakey>	GET
	显示包含所选数据的批次组中的所有数据。每次累积新的批量数据时，批次号增加 1。

API 参数介绍

Single (Latest) 数据 API

www.listly.io/api/single?key=<singlekey>&selected=1&arrange=y&href=n&file=csv

Single (Log) 数据 API

www.listly.io/api/single?key=<datakey>&selected=1&arrange=y&href=n&stack=vertical&file=csv

<datakey> 指向用户复制 API URL 时打开的数据结果。根据该数据中选择的标签页，从 Latest 或 Log 数据中获取相同的数据。

名称	类型	值	默认值	描述
selected	int	1, 2, 3...	1	所选标签页的位置。 1 表示第 1 个，2 表示第 2 个。
arrange	string	y, n	y	数据自动排序选项。 y 自动排序。 n 不自动排序，按从左侧开始出现的顺序输出。
href	string	y, n	n	超链接包含选项。 y 包含超链接。 n 不包含超链接。
stack	string	vertical, horizontal	vertical	数据堆叠方式。 vertical 从上到下垂直堆叠。 horizontal 从左到右水平堆叠。
file	string	csv, json	json	数据输出格式。
from	datetime	2020-11-01T00:00		可以按日期时间限制数据范围。 from 是起始点。 表示为 %Y-%m-%dT%H:%M。
to	datetime	2020-11-11T23:59		可以按日期时间限制数据范围。 to 是结束点。 表示为 %Y-%m-%dT%H:%M。

提示 如果上述说明不够清楚，请尝试直接在实际 API URL 中更改选项值。您可以立即看到它是如何变化的。

---

代码示例

Python 代码模板

download_template.py

import requests
import csv

API_URL = "API URL"    # 输入采集数据的 'API URL'
API_TOKEN = "API Token"     # 输入您账户发放的 'API Token'
headers = { "Authorization": API_TOKEN }

# 加载采集的数据
response = requests.get(url=API_URL, headers=headers)
content = response.content

# 保存为 CSV 文件
"""
如果 API URL 加载的文件格式是 JSON 而不是 CSV，
您需要使用不同的代码来处理
"""
with open('./result.csv', 'wb') as f:
    f.write(content)

Python 代码实际示例

download_example.py

import requests
import csv

API_URL = "https://www.listly.io/api/single?key=CmKQ625S&selected=1&arrange=y&href=n&file=csv"
API_TOKEN = "BC1Sx370Yows25RxaBMuRxTuMKw3Aq0Ks"
headers = { "Authorization": API_TOKEN }

response = requests.get(url=API_URL, headers=headers)
content = response.content

with open('./result.csv', 'wb') as f:
    f.write(content)