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

​

简介

Search Posts 端点 在 v2 世界中可根据你构建的搜索查询，返回与你感兴趣主题相关的 Posts。对于 v2 的搜索 Posts，我们提供两种端点：近期搜索，向所有已获批准账号的开发者开放，可搜索最多七天内的 Posts；以及全量归档搜索，仅向获批参加 Academic Research product track 的研究人员开放，可在整个归档中搜索可追溯至 2006 年 3 月的 Posts。

你可以在我们的 搜索概览页面 查看完整的搜索功能。

这些搜索 Posts 端点满足了学术研究者最常见的用例之一，他们可能将其用于纵向研究，或分析既往的主题或事件。

本教程为希望使用全量归档搜索端点来检索 X 公共 data 完整历史记录的研究人员提供分步指南。它还将演示构建数据集的不同方式，例如检索带地理标签的 Posts，以及如何对某个查询的可用 Posts 进行分页检索。

​

先决条件

目前，此端点仅作为 Academic Research 产品路径 的一部分提供。 要使用此端点，您必须先 申请访问权限。 了解更多关于 该路径的申请流程与要求 的信息。

​

将应用连接到学术项目

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

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

或者你可以创建一个新应用，为其命名并点击完成，将新应用连接到你的 Academic Project。

这样你将获得 API 密钥和 Bearer Token，随后可用于连接到 full-archive search 端点。

请注意

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

​

连接到完整归档搜索端点

下面的 cURL 命令演示了如何从 @XDevelopers 账号获取历史 Post。将 $BEARER_TOKEN 替换为你自己的 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 运算符，查询可写为 (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 运算符配合使用，因此你的查询可以是 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'

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

​

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

使用完整归档搜索端点时，默认返回过去 30 天的 Posts。若要获取早于 30 天的 Posts，可以在 API 调用中使用 start_time 和 end_time 参数。这些参数必须使用有效的 RFC3339 日期与时间格式，例如 2020-12-21T13:00:00.00Z。因此，如果你想获取 XDevelopers 账号在 2020 年 12 月发布的所有 Posts，你的 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'

​

获取带地理标记的历史 Posts

带地理标记的 Posts 指的是关联了地理信息（如城市、州/省、国家等）的 Posts。

​

使用 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'
--hbasheader 'Authorization: Bearer XXXXX'

上方通过 ISO alpha-2 字符代码指定国家/地区。有效的 ISO 代码可在此处查看。

​

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

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

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

因此，要获取下一批可用的 Posts，请从该 meta 对象中取出 next_token 的值，并在对完整归档搜索端点的 API 调用中，将其作为 next_token 传入，如下所示（你将使用自己的 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）端点。请记住，完整归档搜索端点会计入你的总体 Post 上限，也就是你每月可通过 X API 在每个 Project 下获取的 Post 数量。因此，在对结果进行分页时，请注意你的代码逻辑，确保不会无意间耗尽你的 Post 上限。

以下是一些在使用完整归档搜索端点时可供参考的资源。我们期待你的反馈。如对该端点有任何问题，请通过 @XDevelopers 或我们的 社区论坛 与我们联系。

​

其他资源

• 完整归档搜索端点 API 参考 Full-archive search endpoint API reference
• 学习如何构建搜索查询的基础知识 Learn the basics of building a search query