使用 v2 全量归档搜索 endpoint 获取历史 Post

​

简介

v2 环境中的 Search Posts endpoint 使你能够基于你编写的搜索 query（查询）获取与你感兴趣主题相关的 Posts。我们在 v2 的 Search Posts 中提供两个不同的 endpoint：recent search，适用于所有获批账户的开发者，可搜索最多追溯至七天前的 Posts；以及 full-archive search，仅向获批加入 Academic Research product track 的研究人员开放，可在整个存档中搜索可追溯至 2006 年 3 月的 Posts。

你可以在我们的 search overview page 查看完整的搜索能力。

这些 Search Posts endpoint 满足了学术研究者最常见的用例之一：他们可能将其用于纵向研究，或对既往主题或事件进行分析。

本教程为希望使用 full-archive search endpoint 搜索公共 X data 全量历史的研究人员提供分步指南。同时还将演示构建数据集的不同方法，例如检索带地理标签的 Posts，以及如何对某个 query 的可用 Posts 进行分页。

​

先决条件

目前，此 endpoint 仅作为 Academic Research 产品轨道 的一部分提供。 要使用此 endpoint，您必须 申请访问权限。 进一步了解 该轨道的申请流程与要求。

​

将 App 连接到学术项目

在你获准加入 Academic Research 产品通道后，你会在 开发者门户中看到你的 Academic Project。在 “Projects and Apps”部分，点击“Add App”，将你的 X App连接到该 Project。

接着，你可以选择一个现有的 App 并将其连接到你的 Project（如下所示）。

或者，你也可以创建一个新的 App，命名后点击完成，将该 App 连接到你的 Academic Project。

完成后，你将获得 API 密钥和 OAuth 2.0 Bearer Token，之后可用它们连接到 full-archive search endpoint。

请注意

上述截图中的密钥已隐藏，但在你自己的开发者门户中， 你将能够看到 API Key、API Secret Key 和 Bearer Token 的实际值。请保存这些密钥和 Bearer Token，因为在调用 full-archive search endpoint 时需要用到它们。

​

连接到完整归档搜索 endpoint

下面的 cURL 命令演示如何从 @XDevelopers 账号获取历史 Post。将 $BEARER_TOKEN 替换为你自己的 OAuth 2.0 Bearer Token，将完整请求粘贴到终端中，然后按下 Enter 键。

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers' --header 'Authorization: Bearer $BEARER_TOKEN'

你将会看到响应的 JSON。

默认情况下，只返回最近的 10 条 Post。若希望每次请求返回超过 10 条 Post，可使用 max_results 参数，并将其设置为每次请求最多 500 条 Post，如下所示：

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

​

构建查询

如上面的示例调用所示，使用 query 参数可以指定要检索的 data。举例来说，如果您想获取所有包含单词“covid”或“coronavirus”的 Post，可以在括号内使用 OR 运算符，您的 query（查询）可以为 (covid OR coronavirus)，因此您的 API 调用将如下所示：

curl --request GET 'https://api.x.com/2/tweets/search/all?query=(covid%20OR%20coronavirus)&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

同样，如果你想获取所有包含单词“covid19”且不是转发的 Post，可以将 is:retweet 运算符与逻辑非（用 - 表示）一起使用，因此你的 query（查询）可以是 covid19 -is:retweet，而你的 API 调用将是：

curl --request GET 'https://api.x.com/2/tweets/search/all?query=covid19%20-is:retweet&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

请查看 本指南以获取完整的运算符列表 这些运算符适用于完整归档搜索 endpoint。

​

使用 start_time 和 end_time 参数获取历史 Post

使用全量归档搜索 endpoint 时，默认返回过去 30 天内的 Post。若要获取早于 30 天的 Post，可在 API 调用中指定 start_time 和 end_time 参数。这些参数必须使用有效的 RFC3339 日期时间格式，例如 2020-12-21T13:00:00.00Z。因此，如果你想获取 XDevelopers 账号在 2020 年 12 月的所有 Post，你的 API 调用将为：

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:XDevelopers&start_time=2020-12-01T00:00:00.00Z&end_time=2021-01-01T00:00:00.00Z' --header 'Authorization: Bearer $BEARER_TOKEN'

​

获取带地理标签的历史 Post

带地理标签的 Post 是指关联了地理信息的 Post，例如城市、州/省、国家等。

​

使用 has:geo 运算符

如果您想获取包含地理数据的 Post，可以使用 has:geo 运算符。 例如，以下 cURL 请求将仅返回 @XDevelopers 账号发布的、包含地理数据的 Post：

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20has:geo' --header
'Authorization: Bearer $BEARER_TOKEN'

​

使用 place_country 运算符

同样地，你可以使用 place_country 运算符将包含地理数据的 Post 限定在特定国家。下面的 cURL 命令将获取来自美国、由 @XDevelopers 账号发布的所有 Post：

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20place_country:US'
--header 'Authorization: Bearer XXXXX'

上方使用 ISO alpha-2 字母代码指定国家/地区。可在此处查阅有效的 ISO 代码。

​

使用 next_token 获取超过 500 条历史 Post

如上所述，默认情况下，对完整归档搜索 endpoint 的单次请求最多只能获取 500 条 Post。如果你的 query 匹配的 Post 超过 500 条，你的 JSON 响应中会包含一个 next_token，你可以将其附加到后续的 API 调用中，以获取该 query 的下一批可用 Post。该 next_token 位于 JSON 响应的 meta 对象中，类似如下：

{ "newest_id": "12345678...", "oldest_id": "12345678...", "result_count": 500,
"nebashxt_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }

因此，要获取下一批可用的 Post，请从该 meta 对象中取出 next_token 的值，并在对完整归档搜索 endpoint 的 API 调用中将其作为 next_token 传入，如下所示（请使用你自己的 OAuth 2.0 Bearer Token，以及你在上一次 API 调用中获得的 next_token 值）。

curl --request GET
'https://api.x.com/2/tweets/search/all?max_results=500&query=covid&next_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
--header 'Authorization: Bearer $BEARER_TOKEN'

通过这种方式，您可以持续检查是否存在可用的 next_token；如果尚未达到计划收集的 Post 数量，则可在每次请求时使用新的 next_token 继续调用 full-archive endpoint。请注意，full-archive search endpoint 会计入您的总体 Post 上限，也就是说，它会计入您每个 Project 每月可从 X API 获取的 Posts 数量。因此，在对结果进行分页时请留意代码逻辑，避免无意间耗尽您的 Post 上限。

以下是一些在使用 full-archive search endpoint 时可供参考的资源。我们非常期待您的反馈。若对此 endpoint 有任何问题，请通过 @XDevelopers 或我们的 community forums 与我们联系。

​

其他资源

• 完整归档搜索 endpoint API 参考
• 搜索 query 构建基础入门