跳转到主要内容
请注意： 我们已在 X API v2 中发布新版的搜索 Post和Post 计数。建议你查看 X API v2 的更新内容。 这些端点已更新，现包含 Post 编辑相关的元数据。了解更多，请参阅 “编辑 Posts” 基础知识页面。 

​
概览

Enterprise 企业版 API 仅在我们的受管访问级别内提供。要使用这些 API，您必须先与我们的企业销售团队开通账户。了解更多请参见此处。 您可以在此处查看所有 X API 的 Post 搜索产品。 有两种企业搜索 API：
  1. 30 天搜索 API 提供过去 30 天的数据。
  2. 全量存档搜索 API 提供对 X 全量数据语料库的完整且即时访问，可追溯至 2006 年 3 月的第一条 Post。
这些 RESTful API 每次请求支持单个查询，长度最多 2,048 个字符。查询使用 PowerTrack 规则语法编写——更多详情请参见规则与筛选。用户可指定任意时间段，精确到分钟。但响应将受限于您指定的 maxResults 与 31 天二者中较小的一个，并包含用于分页到下一组结果的 next 令牌。如果未指定时间参数，API 将返回最近 30 天内的匹配数据。 企业搜索 API 提供低延迟、全保真、基于查询的 Post 存档访问，粒度精确到分钟。Post 数据按时间倒序返回，从与您查询匹配的最新 Post 开始。Post 在发布约 30 秒后即可通过搜索 API 获取。 这些搜索端点提供已编辑 Post 的元数据。自 2022 年 9 月 29 日起创建的所有 Post 对象都包含 Post 编辑元数据，即使该 Post 从未被编辑。每次编辑 Post，都会生成一个新的 Post ID。某条 Post 的编辑历史由一个 Post ID 数组记录，起始于原始 ID。 这些端点将始终返回最近一次编辑以及完整的编辑历史。任何在其 30 分钟编辑窗口之后收集的 Post 都将代表其最终版本。要了解更多关于编辑 Post 元数据的信息，请参阅编辑 Posts 基础知识页面。 请求包含一个 maxResults 参数，用于指定每个 API 响应返回的 Post 最大数量。如果与查询关联的 Post 数量超过该每次响应的最大值，响应中会包含一个 next 令牌。这些 next 令牌可在后续请求中用于遍历与该查询关联的全部 Post。 这些企业搜索 API 提供一个 counts 端点，使用户能够请求与其查询相关的数据量。 

​
请求类型

企业版搜索 API 支持两种类型的请求：

​
搜索请求（data）

向企业版搜索 API 发起的搜索请求，允许你在指定时间范围内每个响应检索最多 500 条结果，并可通过分页获取更多 data。使用 maxResults 参数，你可以为展示场景指定较小的页面大小（便于用户按需请求更多结果），或为大批量数据拉取指定较大的页面大小（最多 500）。data 按时间倒序返回，并在交付时符合合规要求。

​
计数请求（Post 计数）

计数请求用于获取历史活动计数，反映在指定时间范围内与给定查询匹配的活动发生次数。响应本质上会返回一个按天、小时或分钟分桶的计数直方图（默认分桶为_小时_）。需要注意的是，计数结果并不总能反映在 Post 发布后较长时间（7 天以上）才发生的合规事件（例如删除 Post）；因此，计数指标不一定总能与针对相同查询的数据请求结果一致，这是预期的。 计费说明： 向 data 和 counts 端点发起的每个请求——包括分页请求——均计为一次计费请求。因此，如果单个查询存在多页结果，分页访问 X 个结果页将对应计费 X 次请求。

​
可用运算符

企业版搜索 API 支持长度最多为 2,048 个字符的规则。企业版搜索 API 支持以下运算符。详见此处。
基于 Post 内容的匹配：基于目标账号的匹配：Post 属性：地理空间运算符：
* 关键字
* “引用的短语”
* “keyword1 keyword2”~N
* #
* @
* $
* url:
* lang:		* from:
* to:
* retweets_of:		* is:retweet

* has:mentions
* has:hashtags
* has:media
* has:videos
* has:images
* has:links
* has:symbols
* is:verified

* -is:nullcast（仅用于取反的运算符）		* bounding_box:[west_long south_lat east_long north_lat]
* point_radius:[lon lat radius]
* has:geo
* place:
* place_country:
* has:profile_geo
* profile_country:
* profile_region:
* profile_locality:
注意：不要将运算符嵌入/嵌套使用（“#cats”）在搜索 API 中将被解析为 cats。‘lang:’ 运算符以及所有 ‘is:’ 和 ‘has:’ 运算符不能作为独立运算符使用，必须与其他子句组合（例如 @XDevelopers has:links）。 由于分词与匹配机制的限制，搜索 API 可用的运算符集有限。企业版实时与批量历史 API 提供了更多运算符。详情请见此处。 欲了解更多，请参阅运算符入门指南。

​
数据可用性 / 重要日期

在使用 Full-Archive 搜索 API 时，请注意 X 平台自 2006 年以来持续演进。随着新功能不断推出，底层 JSON 对象也新增了元数据。因此，了解搜索运算符所匹配的 Post 属性是何时加入的非常重要。以下是一些关键元数据类别的“诞生”日期。要了解 Post 属性最初何时引入，请参阅本指南。
  • 首条 Post：3/21/2006
  • 首次原生转发（Native Retweets）：11/6/2009
  • 首条地理标注的 Post：11/19/2009
  • 首次为 URL 建立可用于过滤的索引：8/27/2011
  • 增强的 URL 展开元数据（网页标题与描述）：12/1/2014
  • 个人资料地理信息富化元数据及过滤：2/17/2015

​
数据更新与可变性

使用企业搜索 API 时，Post 内的一些数据是可变的，即在初始归档后可以更新或更改。 这些可变数据分为两类：
  • 用户对象元数据：
    • 用户的 @handle（数字 id 永不改变）
    • 个人简介
    • 计数：statuses、followers、friends、favorites、lists
    • 资料所在地
    • 其他信息，例如时区和语言
  • Post 统计数据——即可由用户在平台上的操作改变的任何内容（如下所示）：
    • Favorites 计数
    • Retweet 计数
在大多数情况下，搜索 API 会返回平台上于查询时点（query-time）的数据，而非 Post 生成时的数据。不过，对于使用选择类运算符（例如 from、to、@、is:verified）的查询，可能并非如此。我们的索引会定期更新，且对最近时间范围的数据更新频率更高。因此，在某些情况下，返回的数据可能与 X.com 上当前显示的数据不完全一致，但会与其上次被索引时的数据一致。 请注意，此类不一致仅适用于运算符作用于可变数据的查询。例如按用户名进行筛选，最佳变通方法是对这些查询使用用户的数字 id，而非 @handle。

​
单线程与多线程请求

每位客户在其搜索端点上都有既定的速率限制。Full-Archive 搜索的默认每分钟速率限制为 120 次请求，平均为每秒 2 次查询（QPS）。该平均 QPS 意味着理论上每秒可以向 API 发出 2 个请求。鉴于产品的分页特性，如果某个一年的查询关联了一百万条 Post，并在全年均匀分布，则需要发出 2,000 多个请求（假设 maxResults 为 500）才能获取所有 data。假设每个响应耗时 2 秒，那么通过单线程按顺序/串行拉取全部 data 需要 4,000 秒（或略多于一小时）（使用上一个响应的“next” 令牌以每秒 1 个请求的速度）。不错！ 现在考虑使用 12 个并行线程来获取 data 的情况。假设这一百万条 Post 在一年内均匀分布，你可以将请求拆分为 12 个并行线程（多线程），从而在单个“作业”中更充分地利用每秒速率限制。换句话说，你可以为每个感兴趣的月份各运行一个线程，这样数据检索速度可提升 12 倍（约 6 分钟）。 这个多线程示例同样适用于 counts 端点。比如，如果你想获取两年期间的 Post 计数，你可以发起单线程请求，并以每次回溯 31 天的方式分页获取计数。假设每个响应耗时 2 秒，那么发出 24 次 API 请求并检索完整的计数集大约需要 48 秒。不过，你也可以选择同时发出多个按月的请求。当以每秒 12 个请求的速率发起请求时，完整的计数集大约可在 2 秒内检索完成。

​
重试逻辑

如果你在使用企业版搜索 API 时遇到 503 错误，这通常是暂时性问题，稍后重新发起请求即可恢复。 如果请求连续失败 4 次，且每次失败之间至少间隔 10 分钟，请按以下步骤进行排查：
  • 缩小请求的时间范围后重试；如仍失败，逐步将时间窗口缩小至 6 小时并重试。
  • 如果你通过 OR 将大量检索词连接在一起，请将它们拆分为多条独立规则，并分别重试。
  • 如果规则中包含大量排除条件，请减少规则中的否定项后重试。

​
快速入门

​
开始使用企业版 Search Posts：30-Day API

企业版 Search Posts：30-Day API 可获取过去 30 天内发布的 Post。系统会根据你在请求中指定的查询条件匹配 Post 并返回。查询是一条规则，用于定义返回的 Post 应该包含的内容。在本教程中，我们将以英语搜索来自 X 账号 @XDevelopers 的 Post。 有效负载中的 Post 可以采用 data 格式（提供完整的 Post 负载），或 counts 格式（提供匹配 Post 的数值统计）。我们将使用 cURL 向 data 和 counts 端点发起请求。 你需要准备以下内容：

​
访问 data 端点

data 端点将向我们返回匹配 Post 的完整 Post 负载。我们将使用 from: 和 lang: 运算符来查找来自 @XDevelopers 且为英语的 Post。更多运算符点击此处。
  • cURL
  • cURL example
cURL 是一种使用 URL 语法获取或发送文件的命令行工具。在按需修改以下内容后，将下面的 cURL 请求复制到你的命令行中：
  • Username <USERNAME>，例如 email@domain.com
  • Account name <ACCOUNT-NAME>，例如 john-doe
  • Label <LABEL>，例如 prod
  • fromDate 与 toDate，例如 "fromDate":"201811010000", "toDate":"201811122359"
发送请求后，你将被要求输入密码。
curl -X POST -u<USERNAME> "https://gnip-api.x.com/search/30day/accounts/<ACCOUNT-NAME>/<LABEL>.json" -d '{"query":"from:TwitterDev lang:en","maxResults":"500","fromDate":"<yyyymmddhhmm>","toDate":"<yyyymmddhhmm>"}'

​
Data 端点响应载荷

你从 API 请求得到的响应会以 JSON 格式返回，如下所示。 
{
	"results": [
		{
			"created_at": "Fri Nov 02 17:18:31 +0000 2018",
			"id": 1058408022936977409,
			"id_str": "1058408022936977409",
			"text": "RT @harmophone: \"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relevant conv…",
			"source": "<a href=\"http:\/\/twitter.com\" rel=\"nofollow\">Twitter Web Client<\/a>",
			"truncated": false,
			"in_reply_to_status_id": null,
			"in_reply_to_status_id_str": null,
			"in_reply_to_user_id": null,
			"in_reply_to_user_id_str": null,
			"in_reply_to_screen_name": null,
			"user": {
				"id": 2244994945,
				"id_str": "2244994945",
				"name": "Twitter Dev",
				"screen_name": "TwitterDev",
				"location": "Internet",
				"url": "https:\/\/developer.x.com\/",
				"description": "Your official source for Twitter Platform news, updates & events. Need technical help? Visit https:\/\/devcommunity.com\/ ⌨️ #TapIntoTwitter",
				"translator_type": "null",
				"protected": false,
				"verified": true,
				"followers_count": 503828,
				"friends_count": 1477,
				"listed_count": 1437,
				"favourites_count": 2199,
				"statuses_count": 3380,
				"created_at": "Sat Dec 14 04:35:55 +0000 2013",
				"utc_offset": null,
				"time_zone": null,
				"geo_enabled": true,
				"lang": "en",
				"contributors_enabled": false,
				"is_translator": false,
				"profile_background_color": "null",
				"profile_background_image_url": "null",
				"profile_background_image_url_https": "null",
				"profile_background_tile": null,
				"profile_link_color": "null",
				"profile_sidebar_border_color": "null",
				"profile_sidebar_fill_color": "null",
				"profile_text_color": "null",
				"profile_use_background_image": null,
				"profile_image_url": "null",
				"profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/880136122604507136\/xHrnqf1T_normal.jpg",
				"profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/2244994945\/1498675817",
				"default_profile": false,
				"default_profile_image": false,
				"following": null,
				"follow_request_sent": null,
				"notifications": null
			},
			"geo": null,
			"coordinates": null,
			"place": null,
			"contributors": null,
			"retweeted_status": {
				"created_at": "Tue Oct 30 21:30:25 +0000 2018",
				"id": 1057384253116289025,
				"id_str": "1057384253116289025",
				"text": "\"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relev… https:\/\/t.co\/w46U5TRTzQ",
				"source": "<a href=\"http:\/\/twitter.com\" rel=\"nofollow\">Twitter Web Client<\/a>",
				"truncated": true,
				"in_reply_to_status_id": null,
				"in_reply_to_status_id_str": null,
				"in_reply_to_user_id": null,
				"in_reply_to_user_id_str": null,
				"in_reply_to_screen_name": null,
				"user": {
					"id": 175187944,
					"id_str": "175187944",
					"name": "Tyler Singletary",
					"screen_name": "harmophone",
					"location": "San Francisco, CA",
					"url": "http:\/\/medium.com\/@harmophone",
					"description": "SVP Product at @Tagboard. Did some Data, biz, and product @Klout & for @LithiumTech; @BBI board member; @Insightpool advisor. World's worst whiteboarder.",
					"translator_type": "null",
					"protected": false,
					"verified": false,
					"followers_count": 1982,
					"friends_count": 1877,
					"listed_count": 245,
					"favourites_count": 23743,
					"statuses_count": 12708,
					"created_at": "Thu Aug 05 22:59:29 +0000 2010",
					"utc_offset": null,
					"time_zone": null,
					"geo_enabled": false,
					"lang": "en",
					"contributors_enabled": false,
					"is_translator": false,
					"profile_background_color": "null",
					"profile_background_image_url": "null",
					"profile_background_image_url_https": "null",
					"profile_background_tile": null,
					"profile_link_color": "null",
					"profile_sidebar_border_color": "null",
					"profile_sidebar_fill_color": "null",
					"profile_text_color": "null",
					"profile_use_background_image": null,
					"profile_image_url": "null",
					"profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/719985428632240128\/WYFHcK-m_normal.jpg",
					"profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/175187944\/1398653841",
					"default_profile": false,
					"default_profile_image": false,
					"following": null,
					"follow_request_sent": null,
					"notifications": null
				},
				"geo": null,
				"coordinates": null,
				"place": null,
				"contributors": null,
				"is_quote_status": false,
				"extended_tweet": {
					"full_text": "\"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relevant conversations in real-time and enabling voters to ask questions during debates,”  -- @adamostrow, @TEGNA\nLearn More: https:\/\/t.co\/ivAFtanfje",
					"display_text_range": [
						0,
						259
					],
					"entities": {
						"hashtags": [],
						"urls": [
							{
								"url": "https:\/\/t.co\/ivAFtanfje",
								"expanded_url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4",
								"display_url": "blog.tagboard.com\/twitter-and-ta…",
								"unwound": {
									"url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4",
									"status": 200,
									"title": "Twitter and Tagboard Collaborate to Bring Best Election Content to News Outlets With Tagboard…",
									"description": "By Tyler Singletary, Head of Product, Tagboard"
								},
								"indices": [
									236,
									259
								]
							}
						],
						"user_mentions": [
							{
								"screen_name": "adamostrow",
								"name": "Adam Ostrow",
								"id": 5695942,
								"id_str": "5695942",
								"indices": [
									204,
									215
								]
							},
							{
								"screen_name": "TEGNA",
								"name": "TEGNA",
								"id": 34123003,
								"id_str": "34123003",
								"indices": [
									217,
									223
								]
							}
						],
						"symbols": []
					}
				},
				"quote_count": 0,
				"reply_count": 1,
				"retweet_count": 6,
				"favorite_count": 19,
				"entities": {
					"hashtags": [],
					"urls": [
						{
							"url": "https:\/\/t.co\/w46U5TRTzQ",
							"expanded_url": "https:\/\/twitter.com\/i\/web\/status\/1057384253116289025",
							"display_url": "twitter.com\/i\/web\/status\/1…",
							"indices": [
								117,
								140
							]
						}
					],
					"user_mentions": [],
					"symbols": []
				},
				"favorited": false,
				"retweeted": false,
				"possibly_sensitive": false,
				"filter_level": "low",
				"lang": "en"
			},
			"is_quote_status": false,
			"quote_count": 0,
			"reply_count": 0,
			"retweet_count": 0,
			"favorite_count": 0,
			"entities": {
				"hashtags": [],
				"urls": [],
				"user_mentions": [
					{
						"screen_name": "harmophone",
						"name": "Tyler Singletary",
						"id": 175187944,
						"id_str": "175187944",
						"indices": [
							3,
							14
						]
					}
				],
				"symbols": []
			},
			"favorited": false,
			"retweeted": false,
			"filter_level": "low",
			"lang": "en",
			"matching_rules": [
				{
					"tag": null
				}
			]
		}
	],
	"requestParameters": {
		"maxResults": 100,
		"fromDate": "201811010000",
		"toDate": "201811060000"
	}
}

​
访问 counts 端点

使用 counts 端点，我们将按 day 分组，检索由 @XDevelopers 账号发布的英文 Post 数量。
  • cURL
  • cURL example
cURL 是一款使用 URL 语法获取或发送文件的命令行工具。按以下说明进行替换后，将下面的 cURL 请求复制到命令行中：
  • Username <USERNAME>，例如 email@domain.com
  • Account name <ACCOUNT-NAME>，例如 john-doe
  • Label <LABEL>，例如 prod
  • fromDate 和 toDate，例如 "fromDate":"201811010000", "toDate":"201811122359"
发送请求后，系统会提示你输入密码。
curl -X POST -u<USERNAME> "https://gnip-api.x.com/search/30day/accounts/<ACCOUNT-NAME>/<LABEL>/counts.json" -d '{"query":"from:TwitterDev lang:en","fromDate":"<yyyymmddhhmm>","toDate":"<yyyymmddhhmm>","bucket":"day"}'

​
Counts 端点响应载荷

您从 API 请求中获得的载荷将以 JSON 格式返回，如下所示。 
{
	"results": [
		{
			"timePeriod": "201811010000",
			"count": 0
		},
		{
			"timePeriod": "201811020000",
			"count": 1
		},
		{
			"timePeriod": "201811030000",
			"count": 0
		},
		{
			"timePeriod": "201811040000",
			"count": 0
		},
		{
			"timePeriod": "201811050000",
			"count": 0
		}
	],
	"totalCount": 1,
	"requestParameters": {
		"bucket": "day",
		"fromDate": "201811010000",
		"toDate": "201811060000"
	}
}
干得好！你已成功访问企业版 Search Posts：30-Day API。
参考文章

​
开始使用企业版 Search Posts：Full-Archive API

企业版 Search Posts：Full-Archive API 可提供自 2006 年首条发布以来的所有 Posts。系统会根据你在请求中指定的查询条件匹配 Posts 并返回结果。查询是一条你用来定义返回的 Post 应包含哪些内容的规则。在本教程中，我们将搜索由 X 账号 @XDevelopers 用英文发布的 Posts。 返回负载中的 Posts 可能以 data 格式提供（包含完整的 Post 负载），也可能以 counts 格式提供（包含匹配 Posts 的数值统计数据）。我们将使用 cURL 向 data 和 counts 端点发起请求。 你需要准备以下内容：
  • 企业版账户
  • 你的用户名、密码和账户名称
  • 与你的搜索端点关联的标签（可在 console.gnip.com 查看）

​
访问 data 端点

data 端点将为我们提供匹配 Post 的完整 Post 载荷。我们将使用 from: 和 lang: 运算符来查找来自 @XDevelopers 且为英文的 Post。有关更多运算符 请点击此处。
  • cURL
  • cURL example
cURL 是一款使用 URL 语法获取或发送文件的命令行工具。根据以下项目完成替换后，将下面的 cURL 请求复制到你的命令行中：
  • Username <USERNAME>，例如 email@domain.com
  • Account name <ACCOUNT-NAME>，例如 john-doe
  • Label <LABEL>，例如 prod
  • fromDate 和 toDate 例如 "fromDate":"201802010000", "toDate":"201802282359"
发送请求后，系统会提示你输入密码。
curl -X POST -u<USERNAME> "https://gnip-api.x.com/search/fullarchive/accounts/<ACCOUNT-NAME>/<LABEL>.json" -d '{"query":"from:TwitterDev lang:en","maxResults":"500","fromDate":"<yyyymmddhhmm>","toDate":"<yyyymmddhhmm>"}'
数据端点响应载荷
你从 API 请求中获得的载荷将以 JSON 格式返回，如下所示。 
{
	"results": [
		{
			"created_at": "Fri Nov 02 17:18:31 +0000 2018",
			"id": 1058408022936977409,
			"id_str": "1058408022936977409",
			"text": "RT @harmophone: \"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relevant conv…",
			"source": "<a href=\"http:\/\/twitter.com\" rel=\"nofollow\">Twitter Web Client<\/a>",
			"truncated": false,
			"in_reply_to_status_id": null,
			"in_reply_to_status_id_str": null,
			"in_reply_to_user_id": null,
			"in_reply_to_user_id_str": null,
			"in_reply_to_screen_name": null,
			"user": {
				"id": 2244994945,
				"id_str": "2244994945",
				"name": "Twitter Dev",
				"screen_name": "TwitterDev",
				"location": "Internet",
				"url": "https:\/\/developer.x.com\/",
				"description": "Your official source for Twitter Platform news, updates & events. Need technical help? Visit https:\/\/devcommunity.com\/ ⌨️ #TapIntoTwitter",
				"translator_type": "null",
				"protected": false,
				"verified": true,
				"followers_count": 503828,
				"friends_count": 1477,
				"listed_count": 1437,
				"favourites_count": 2199,
				"statuses_count": 3380,
				"created_at": "Sat Dec 14 04:35:55 +0000 2013",
				"utc_offset": null,
				"time_zone": null,
				"geo_enabled": true,
				"lang": "en",
				"contributors_enabled": false,
				"is_translator": false,
				"profile_background_color": "null",
				"profile_background_image_url": "null",
				"profile_background_image_url_https": "null",
				"profile_background_tile": null,
				"profile_link_color": "null",
				"profile_sidebar_border_color": "null",
				"profile_sidebar_fill_color": "null",
				"profile_text_color": "null",
				"profile_use_background_image": null,
				"profile_image_url": "null",
				"profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/880136122604507136\/xHrnqf1T_normal.jpg",
				"profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/2244994945\/1498675817",
				"default_profile": false,
				"default_profile_image": false,
				"following": null,
				"follow_request_sent": null,
				"notifications": null
			},
			"geo": null,
			"coordinates": null,
			"place": null,
			"contributors": null,
			"retweeted_status": {
				"created_at": "Tue Oct 30 21:30:25 +0000 2018",
				"id": 1057384253116289025,
				"id_str": "1057384253116289025",
				"text": "\"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relev… https:\/\/t.co\/w46U5TRTzQ",
				"source": "<a href=\"http:\/\/twitter.com\" rel=\"nofollow\">Twitter Web Client<\/a>",
				"truncated": true,
				"in_reply_to_status_id": null,
				"in_reply_to_status_id_str": null,
				"in_reply_to_user_id": null,
				"in_reply_to_user_id_str": null,
				"in_reply_to_screen_name": null,
				"user": {
					"id": 175187944,
					"id_str": "175187944",
					"name": "Tyler Singletary",
					"screen_name": "harmophone",
					"location": "San Francisco, CA",
					"url": "http:\/\/medium.com\/@harmophone",
					"description": "SVP Product at @Tagboard. Did some Data, biz, and product @Klout & for @LithiumTech; @BBI board member; @Insightpool advisor. World's worst whiteboarder.",
					"translator_type": "null",
					"protected": false,
					"verified": false,
					"followers_count": 1982,
					"friends_count": 1877,
					"listed_count": 245,
					"favourites_count": 23743,
					"statuses_count": 12708,
					"created_at": "Thu Aug 05 22:59:29 +0000 2010",
					"utc_offset": null,
					"time_zone": null,
					"geo_enabled": false,
					"lang": "en",
					"contributors_enabled": false,
					"is_translator": false,
					"profile_background_color": "null",
					"profile_background_image_url": "null",
					"profile_background_image_url_https": "null",
					"profile_background_tile": null,
					"profile_link_color": "null",
					"profile_sidebar_border_color": "null",
					"profile_sidebar_fill_color": "null",
					"profile_text_color": "null",
					"profile_use_background_image": null,
					"profile_image_url": "null",
					"profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/719985428632240128\/WYFHcK-m_normal.jpg",
					"profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/175187944\/1398653841",
					"default_profile": false,
					"default_profile_image": false,
					"following": null,
					"follow_request_sent": null,
					"notifications": null
				},
				"geo": null,
				"coordinates": null,
				"place": null,
				"contributors": null,
				"is_quote_status": false,
				"extended_tweet": {
					"full_text": "\"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relevant conversations in real-time and enabling voters to ask questions during debates,”  -- @adamostrow, @TEGNA\nLearn More: https:\/\/t.co\/ivAFtanfje",
					"display_text_range": [
						0,
						259
					],
					"entities": {
						"hashtags": [],
						"urls": [
							{
								"url": "https:\/\/t.co\/ivAFtanfje",
								"expanded_url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4",
								"display_url": "blog.tagboard.com\/twitter-and-ta…",
								"unwound": {
									"url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4",
									"status": 200,
									"title": "Twitter and Tagboard Collaborate to Bring Best Election Content to News Outlets With Tagboard…",
									"description": "By Tyler Singletary, Head of Product, Tagboard"
								},
								"indices": [
									236,
									259
								]
							}
						],
						"user_mentions": [
							{
								"screen_name": "adamostrow",
								"name": "Adam Ostrow",
								"id": 5695942,
								"id_str": "5695942",
								"indices": [
									204,
									215
								]
							},
							{
								"screen_name": "TEGNA",
								"name": "TEGNA",
								"id": 34123003,
								"id_str": "34123003",
								"indices": [
									217,
									223
								]
							}
						],
						"symbols": []
					}
				},
				"quote_count": 0,
				"reply_count": 1,
				"retweet_count": 6,
				"favorite_count": 19,
				"entities": {
					"hashtags": [],
					"urls": [
						{
							"url": "https:\/\/t.co\/w46U5TRTzQ",
							"expanded_url": "https:\/\/twitter.com\/i\/web\/status\/1057384253116289025",
							"display_url": "twitter.com\/i\/web\/status\/1…",
							"indices": [
								117,
								140
							]
						}
					],
					"user_mentions": [],
					"symbols": []
				},
				"favorited": false,
				"retweeted": false,
				"possibly_sensitive": false,
				"filter_level": "low",
				"lang": "en"
			},
			"is_quote_status": false,
			"quote_count": 0,
			"reply_count": 0,
			"retweet_count": 0,
			"favorite_count": 0,
			"entities": {
				"hashtags": [],
				"urls": [],
				"user_mentions": [
					{
						"screen_name": "harmophone",
						"name": "Tyler Singletary",
						"id": 175187944,
						"id_str": "175187944",
						"indices": [
							3,
							14
						]
					}
				],
				"symbols": []
			},
			"favorited": false,
			"retweeted": false,
			"filter_level": "low",
			"lang": "en",
			"matching_rules": [
				{
					"tag": null
				}
			]
		}
	],
	"requestParameters": {
		"maxResults": 100,
		"fromDate": "201811010000",
		"toDate": "201811060000"
	}
}

​
访问 counts 端点

借助 counts 端点，我们将按 day 分组，检索 @XDevelopers 账号发布的英文 Post 数量。
  • cURL
  • cURL example
cURL 是一款使用 URL 语法获取或发送文件的命令行工具。请在完成以下替换后，将下面的 cURL 请求复制到命令行中：
  • Username <USERNAME>，例如 email@domain.com
  • Account name <ACCOUNT-NAME>，例如 john-doe
  • Label <LABEL>，例如 prod
  • fromDate 和 toDate，例如 "fromDate":"201802010000", "toDate":"201802282359"
发送请求后，系统会提示你输入密码。
curl -X POST -u<USERNAME> "https://gnip-api.x.com/search/fullarchive/accounts/<ACCOUNT-NAME>/<LABEL>/counts.json" -d '{"query":"from:TwitterDev lang:en","fromDate":"<yyyymmddhhmm>","toDate":"<yyyymmddhhmm>","bucket":"day"}'

​
计数端点的响应载荷

你通过 API 请求获得的载荷将以 JSON 格式返回，如下所示。 
{
	"results": [
		{
			"timePeriod": "201811010000",
			"count": 0
		},
		{
			"timePeriod": "201811020000",
			"count": 1
		},
		{
			"timePeriod": "201811030000",
			"count": 0
		},
		{
			"timePeriod": "201811040000",
			"count": 0
		},
		{
			"timePeriod": "201811050000",
			"count": 0
		}
	],
	"totalCount": 1,
	"requestParameters": {
		"bucket": "day",
		"fromDate": "201811010000",
		"toDate": "201811060000"
	}
}
做得好！你已成功访问企业版 Search Posts: Full-Archive API。
参考文章

​
指南

​
构建搜索查询

​
企业版运算符

以下是 X 企业搜索 API 支持的全部运算符列表：
  • 企业版 30 天搜索 API
  • 企业版 全量存档搜索 API
有关各产品可用运算符的对照比较，请参见此处。
操作符描述
关键字匹配 Post 正文或 URL 中的分词关键字。这是一种分词匹配，即您的关键字字符串将与 Post 正文的已分词文本进行匹配——分词基于标点符号、符号和分隔符 Unicode 基本平面字符。例如，文本为“I like coca-cola”的 Post 将被拆分为以下分词：I, like, coca, cola。这些分词随后将与您规则中使用的关键字字符串进行比较。要匹配包含标点符号（例如，coca-cola）、符号或分隔符字符的字符串，您必须使用下面描述的带引号精确匹配。

**注意：**使用 Search API 时，带重音的字符和特殊字符会被标准化为标准的拉丁字符，这可能会在外国语言中改变含义或返回意外结果：
例如，“音乐”将匹配“music”，反之亦然
例如，常见的短语如”新年快乐！“在西班牙语中，会被索引为”新年快乐”， 这会改变短语的含义。

**注意：**此运算符将匹配帖子中的 URL 和展开 URL。
emoji匹配 Post 正文中的表情符号。表情符号匹配是基于分词的，这意味着您的表情符号将与 Post 正文的分词文本进行匹配——分词基于标点符号、符号/表情符号以及分隔符等 Unicode 基本平面字符。例如，一个文本为“我喜欢”的 Post” 将被拆分为以下标记：I, like,. 这些令牌随后将与您规则中使用的表情符号进行比较。请注意，如果表情符号有变体，您必须使用“引号”将其添加到规则中。
“精确短语匹配”精确短语匹配”匹配帖子正文或 URL 中的分词且有序短语。这是一种分词匹配，即您的关键字字符串将与帖子正文的 分词文本 进行匹配——分词基于标点符号、符号和分隔符的 Unicode 基本平面字符。

**注意：**标点符号不会被分词，而是被视为空白字符。
例如，带引号的“#hashtag”将匹配“hashtag”，但不匹配#hashtag（使用不带引号的#hashtag操作符来匹配实际的hashtag）。
例如，带引号的“cashtag”将匹配“cashtag”，但不会匹配cashtag”将匹配“cashtag”，但不会匹配 cashtag（要匹配实际的 cashtag，请使用不带引号的 cashtag $ 操作符）。
例如，“爱雪”将匹配”#love #snow”exact phrase match”		在推文的正文或 URL 中匹配分词后的有序短语。这是一种基于分词的匹配方式，即您的关键字字符串将与推文正文的令牌化文本进行匹配——分词基于标点符号、符号以及分隔 Unicode 基本平面的字符。

注意： 标点符号不会被分词，而是被视为空白字符。
例如，带引号的“#hashtag”将匹配“hashtag”，但不会匹配 #hashtag（使用不带引号的 hashtag # 操作符来匹配实际的 hashtag）。
例如，带引号的“cashtag”将匹配“cashtag”，但不会匹配cashtag”将匹配“cashtag”，但不会匹配 cashtag（使用不带引号的 cashtag $ 操作符来匹配实际的 cashtag）。
例如，“Love Snow”将匹配“#love #snow”
例如，“#Love #Snow”将匹配“love snow”

注意： 此操作符将在推文中的 URL 和展开 URL 上进行匹配。
例如，“#爱 #雪”将匹配”爱雪”

**注意：**此运算符将同时匹配帖子中的 URL 和展开的 URL。
“keyword1 keyword2”~N通常称为邻近运算符，它会匹配关键词之间相距不超过 N 个标记的 Post。

如果关键字的顺序相反，则它们之间不能相距超过 N-2 个令牌。可以将任意数量的关键字置于引号中。N 不能大于 6。

请注意，此运算符仅在企业版搜索 API。
从：匹配特定用户发布的任何 Post。
该值必须是用户的 X 数字账户 ID 或用户名（不包括 @ 字符）。参见此处或此处有关查找数字 X 账户 ID 的方法。
至：匹配任何回复特定用户的帖子。

该值必须是用户的数字账户 ID 或用户名（不包括 @ 字符）。请参阅此处用于查找数字 X 账号 ID 的方法。
url:在帖子的扩展 URL 上执行分词（关键字/短语）匹配（类似于 url_包含）。包含标点符号或特殊字符的标记和短语应使用双引号括起。例如，url：“/developer”。 虽然通常不推荐，但如果您想匹配特定协议，请用双引号将其括起来：url:“https://developer.x.com”。
**注意：**在使用 PowerTrack 或 Historical PowerTrack 时，此操作符将匹配引用帖子所引用的原始帖子中包含的 URL。例如，如果您的规则包含 url:“developer.x.com”， 并且如果某个 Post 包含该 URL，则该 Post 的任何 Quote Tweets 都会包含在结果中。使用 Search API 时则不然。
#匹配任何带有指定标签的 Post。

此操作符执行精确匹配，而非分词匹配。这意味着规则“2016”将匹配带有精确标签“2016”的帖子，但不会匹配带有标签“2016election”的帖子。

注意：hashtag 操作符依赖于 X’使用 X 的实体提取来匹配 hashtag，而不是从推文主体本身提取 hashtag。参见此处有关 X Entities JSON 属性的更多信息。
@匹配任何提及指定用户名的帖子。
to: 操作符返回 @mention 操作符匹配结果的子集。
$匹配任何包含指定“cashtag”（其标记以“$”开头）的 Post。

请注意，cashtag 操作符依赖于 X’使用 ‘symbols’ 实体提取来匹配 cashtags，而不是尝试从正文本身提取 cashtag。 参见此处有关 X 实体 JSON 属性的更多信息。

请注意，此运算符仅在企业版搜索 API。

转推_of：可用别名: 转推_的_用户：
匹配对指定用户进行转发的 Post。接受用户名和数值型 X 账户 ID（非 Post 状态 ID）。参见这里用于查找数值型 X 账号 id 的方法。
lang:匹配由 X 归类为特定语言的 Post（且仅在该 Post 已被归类的情况下）。请注意，每个 Post 目前只会被归为一种语言，因此将多个语言条件使用 AND 组合不会得到任何结果。

**注意：**如果無法進行語言分類，則結果為 ‘und’（表示未定義）。

下方列表列出了当前支持的语言及其对应的 BCP 47 语言标识符：
阿姆哈拉语: am德语: de马拉雅拉姆语: ml斯洛伐克语: sk
阿拉伯语: ar希腊语: el迪维希语: dv斯洛文尼亚语: sl
亚美尼亚语: hy古吉拉特语: gu马拉地语: mr索拉尼库尔德语: ckb
巴斯克语: eu海地克里奥尔语: ht尼泊尔语: ne西班牙语: es
孟加拉语: bn希伯来语: iw挪威语: no瑞典语: sv
波斯尼亚语: bs印地语: hi奥迪亚语: or他加禄语: tl
保加利亚语: bg拉丁化印地语: hi-Latn旁遮普语: pa泰米尔语: ta
缅甸语: my匈牙利语: hu普什图语: ps泰卢固语: te
克罗地亚语: hr冰岛语: is波斯语: fa泰语: th
加泰罗尼亚语: ca印尼语: in波兰语: pl藏语: bo
捷克语: cs意大利语: it葡萄牙语: pt繁体中文: zh-TW
丹麦语: da日语: ja罗马尼亚语: ro土耳其语: tr
荷兰语: nl卡纳达语: kn俄语: ru乌克兰语: uk
英语: en高棉语: km塞尔维亚语: sr维吾尔语: ug
爱沙尼亚语: et韩语: ko简体中文: zh-CN越南语: vi
芬兰语: fi老挝语: lo信德语: sd威尔士语: cy
法语: fr拉脱维亚语: lv僧伽罗语: si
格鲁吉亚语: ka立陶宛语: lt
place:匹配带有指定位置或 X place ID 标签的 Post（见示例）。多词地点名称（“New York City”“Palo Alto”）应加引号。

**注意：**请参阅公开 API 端点 GET geo/search 了解如何获取 X place ID。

**注意：**此运算符不会匹配转发（Retweets），因为转发的地点附加在原始 Post 上。引用转发（Quote Tweet）也不会匹配其所引用的原始 Post 上附加的地点。
place_country:匹配与被标记的place关联的国家/地区代码与给定 ISO Alpha-2 字符代码一致的 Post。

可在此处查询有效的 ISO 代码：http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

**注意：**此运算符不会匹配转发（Retweets），因为转发的地点附加在原始 Post 上。引用转发（Quote Tweet）也不会匹配其所引用的原始 Post 上附加的地点。
point_radius:[lon lat radius]当存在时，匹配 Post 的精确位置（x, y）；在 X 中，还会匹配“Place”地理多边形，前提是该 Place 完全包含在定义的区域内。

* 支持的半径单位为英里（mi）和公里（km）。
* 半径必须小于 25 mi。
* 经度范围为 ±180。
* 纬度范围为 ±90。
* 所有坐标均为十进制度。
* 规则参数置于方括号内，使用空格分隔。

**注意：**此运算符不会匹配转发（Retweets），因为转发的地点附加在原始 Post 上。引用转发（Quote Tweet）也不会匹配其所引用的原始 Post 上附加的地点。
bounding_box:[west_long south_lat east_long north_lat]可用别名：geo_bounding_box:

当存在时，匹配 Post 的精确位置（long, lat）；在 X 中，还会匹配“Place”地理多边形，前提是该 Place 完全包含在定义的区域内。

* west_long 和 south_lat 表示边界框的西南角，其中 west_long 为该点的经度，south_lat 为该点的纬度。
* east_long 和 north_lat 表示边界框的东北角，其中 east_long 为该点的经度，north_lat 为该点的纬度。
* 边界框的宽度和高度必须小于 25 mi。
* 经度范围为 ±180。
* 纬度范围为 ±90。
* 所有坐标均为十进制度。
* 规则参数置于方括号内，使用空格分隔。
**注意：**此运算符不会匹配转发（Retweets），因为转发的地点附加在原始 Post 上。引用转发（Quote Tweet）也不会匹配其所引用的原始 Post 上附加的地点。
profile_country:对 Profile Geo 增强数据中 “address” 对象的 “countryCode” 字段进行精确匹配。
使用基于 ISO-3166-1-alpha-2 规范的标准化两字母国家/地区代码。为简洁起见，本运算符用于替代对 “address” 对象中 “country” 字段的运算符。
profile_region:匹配 Profile Geo 增强数据中 “address” 对象的 “region” 字段。

这是精确的完整字符串匹配。无需使用反斜杠进行转义。例如，若要匹配包含斜杠的内容，使用 “one/two”，而非 “one/two”。对包含空格或标点的子字符串使用双引号。
profile_locality:匹配 Profile Geo 增强数据中 “address” 对象的 “locality” 字段。

这是精确的完整字符串匹配。无需使用反斜杠进行转义。例如，若要匹配包含斜杠的内容，使用 “one/two”，而非 “one/two”。对包含空格或标点的子字符串使用双引号。
注意： 在使用 Search API 时，is: 和 has: 运算符不能单独使用，必须与其他子句结合使用。例如，@XDeevelopers has:links
has:geo匹配包含 X 提供的帖子特定地理位置数据的帖子。这可以是“geo”纬度-经度坐标，或一个“location”，以 X 的形式“地点”，带有对应的显示名称、地理多边形以及其他字段。



**注意：**在使用 Search API 时，此运算符必须与其他运算符结合使用，这些运算符不’不包括is:或has:.
has:profile_地理可用别名：has:derived_用户_地理

匹配具有任何的帖子个人资料地理位置元数据，无论实际值如何。


**注意：**在使用 Search API 时，必须将此运算符与未包含 is: 或 has: 的其他运算符一同使用’不包括is:或has:has:profile_geo		可用别名：has:derived_user_geo

匹配包含任何 Profile Geo 元数据的推文，无论实际值如何。


**注意：**在使用搜索 API 时，此运算符必须与其他不包含 is: 或 has: 的运算符结合使用。
has:links此运算符匹配消息正文中包含链接的帖子。


**注意：**在使用 Search API 时，此操作符必须与其他 don 的操作符结合使用此操作符匹配帖子正文中包含链接的帖子。


注意： 使用搜索 API 时，此操作符必须与其他不包含 is: 或 has: 的操作符结合使用。不包含is:或has:此运算符匹配正文包含链接的帖子。


注意： 使用搜索 API 时，此运算符必须与其他不包含 is: 或 has: 的运算符结合使用。
is:retweet仅交付匹配规则的明确转推。也可以使用否定形式，从交付中排除匹配规则的转推，从而仅交付原创内容。

此运算符仅查找真正的转推，这些转推使用 X’的转推功能。不使用 X 的转推功能的引用型 Tweet 和经修改的帖子将不会被此运算符匹配’此运算符不会匹配 s retweet 功能。



**注意：**在使用 Search API 时，此操作符必须与其他不包含 is: 或 has: 的操作符结合使用’不包含is:或has:is:retweet		仅返回匹配规则的明确转推。可以否定以排除匹配规则的转推，并仅返回原始内容。

此操作符仅匹配使用 X 转推功能的真实转推。引用推文以及未使用 X 转推功能的修改帖子不会被此操作符匹配。



注意： 使用搜索 API 时，此操作符必须与其他不包含 is: 或 has: 的操作符结合使用。
is:reply一个用于根据帖子是否为对帖子的回复或非回复来过滤帖子的操作符。仅传递匹配规则的明确回复。也可以取反，以从传递中排除匹配规则的回复。

请注意，此运算符仅适用于付费高级版和企业版搜索，在 Sandbox 开发环境中不可用。



**注意：**在使用 Search API 时，此运算符必须与其他运算符结合使用，这些运算符不’不包含is:或has:is:reply		一个用于根据帖子是否为对其他帖子的回复来过滤帖子的操作符。只返回匹配条件的明确回复帖子。也可以使用否定形式排除匹配条件的回复，从而仅返回非回复内容。

请注意，此操作符适用于付费的高级搜索和企业搜索，不适用于 Sandbox 开发环境。



注意： 使用 Search API 时，此操作符必须与其他不包含 is: 或 has: 的操作符结合使用。
is:quote仅返回引用推文，或引用另一个推文的推文，由”是_引述_状态”:true 在 Post 的负载中。也可以否定以排除引用推文。

**注意：**使用搜索 API 时，必须将此运算符与其他不…的运算符配合使用’不包括is:或has:is:quote		返回引用推文，即那些引用其他推文的推文。这些推文通过推文负载中的 “is_quote_status”: true 来标识。也可以使用否定形式来排除引用推文。

**注意：**在使用 Search API 时，此运算符必须与其他不包含 is: 或 has: 的运算符结合使用。
is:已验证仅返回作者被 X 验证的帖子。也可以否定以排除作者被验证的帖子。


**注意：**使用 Search API 时，此运算符必须与其他不包含 is: 或 has: 的运算符结合使用。‘不包含is:或has:is:verified		仅返回来自已由 X 验证作者的帖子。可通过否定来排除已验证作者的帖子。


**注意：**在使用搜索 API 时，此运算符必须与其他不包含 is: 或 has: 的运算符结合使用。
has:mentions匹配提及其他 X 用户的帖子。


**注意：**使用 Search API 时，必须将此运算符与其他不…的运算符结合使用’不包括is:或has:has:mentions		匹配提及其他 X 用户的帖子。


注意： 使用搜索 API 时，此运算符必须与其他不包含 is: 或 has: 的运算符结合使用。
has:hashtags匹配包含标签的帖子。


**注意：**在使用 Search API 时，该运算符必须与其他不…的运算符结合使用’不包括is:或has:匹配包含标签的帖子。


注意： 使用搜索 API 时，此运算符必须与其他不包含 is: 或 has: 的运算符结合使用。
has:media可用别名: has:media_链接

匹配包含由 X 分类的媒体 URL 的帖子。例如，pic.x.com。


**注意：**在使用 Search API 时，此运算符必须与其他不包含 is: 或 has: 的运算符结合使用。‘不包括is:或has:has:media		Available alias: has:media_link

匹配包含 X 托管媒体 URL 的帖子。例如，pic.x.com。

注意： 在使用搜索 API 时，此运算符必须与其他不包含 is: 或 has: 的运算符结合使用。
has:images匹配包含由 X 归类的媒体 URL 的 Post。例如：pic.x.com。


**注意：**在使用 Search API 时，此运算符必须与不包含 is: 或 has: 的其他运算符一起使用’不包含is:或has:。
has:videos可用的别名: has:video_链接

匹配包含原生 X 视频（直接上传到 X）的 Post。不匹配使用 Vine、Periscope 创建的视频，或包含指向其他视频托管网站链接的 Post。


**注意：**在使用搜索 API 时，此运算符必须与不——的其他运算符配合使用’不包括is:或has:。
has:symbols匹配包含股票代号符号（以“”开头，例如”开头，例如 tag）的 Posts。请注意，此运算符仅在企业版搜索 API。


注意在使用 Search API 时，必须将此运算符与不包含 is: 或 has: 的其他运算符一起使用’不包含is:或has:。

​
产品概览

企业版层级的 Full-archive Search 于 2015 年 8 月推出，高级付费层级版本于 2018 年 2 月推出。这些搜索产品使客户能够即时访问任何公开可用的 Post。使用 Full-archive Search，您只需提交一个查询，即可以经典的 RESTful 方式获得响应。Full-archive Search 实现了（最多）每次响应 500 条 Post 的分页，并支持高级付费每分钟最多 60 次请求（rpm）的速率限制、企业版为每分钟 120 次请求。基于这些特性，Full-archive Search 既可快速检索 Post，也可通过并发请求实现大规模检索。 与 Historical PowerTrack 基于磁盘上一组 Post 扁平文件的归档不同，Full-archive Search 的 Post 归档更类似于在线数据库。与所有数据库一样，它支持对其内容进行查询；同时利用索引以实现高性能的数据检索。对于 Full-archive 搜索端点，其查询语言由 PowerTrack Operators 组成，每个 Operator 都对应一个已建立索引的 Post JSON 属性。 同样地，与 Historical PowerTrack 类似，存在与发起查询时点相对应的 Post 属性。例如，如果您今天使用 Search API 访问一条在 2010 年发布的 Post，该用户的个人资料描述、账号“主页”位置、显示名称，以及 Favorites 和 Retweet 计数等 Post 指标都将更新为今天的数值，而不是 2010 年时的数值。 

​
元数据时间线

以下是完整存档搜索端点操作符开始匹配的时间线。在某些情况下，操作符匹配开始的时间远晚于 X 上某种“通信惯例”变得普遍。例如，@Replies 在 2006 年作为用户惯例出现，但直到 2007 年初才成为具有支持性 JSON 的 一流对象 或 事件。因此，在 2006 年匹配 @Replies 需要检查帖子的正文，而不是依赖 to: 和 in_reply_to_status_id: PowerTrack 操作符。 此处提供的信息是使用 Full-Archive Search（数百次搜索的结果）生成的。此时间线并非 100% 完整或精确。如果您发现另一个与您的用例相关的过滤/元数据“诞生日期”基本信息，请告知我们。 请注意，底层搜索索引可能会被重建。因此，这些时间线细节可能会发生变化。

​
2006

  • 3月26日 - lang:. 一个生成搜索索引时回填帖子元数据的示例。
  • 7月13日 - has:mentions 开始匹配。
  • 10月6日 - has:symbols。用于讨论股票符号的 cashtags（或符号）直到2009年初才变得常见。在此之前，大多数用法可能是俚语（例如，cashtags（或符号）直到2009年初才变得常见。在此之前，大多数用法可能是俚语（例如，slang）。
  • 10月26日 - has:links 开始匹配。
  • 11月23日 - has:hashtags 开始匹配。

​
2007

  • 1月30日 - 首个一流 @reply（in_reply_to_user_id），reply_to_status_id: 开始匹配。
  • 8月23日 - 标签作为组织主题和对话的常见约定出现。一周后首次实际使用。

​
2009

  • 5月15日 - is:retweet。请注意，此运算符从官方转推的“beta”版本发布及其“Via @”模式开始匹配。在此 beta 期间，帖子的动词为“post”，原始帖子不包含在负载中。
  • 8月13日 - 官方转推的最终版本发布，采用“RT @”模式，动词设置为“share”，以及包含原始帖子的“retweet_status”属性（从而使 JSON 负载大小大约加倍）。

​
2010

  • 3月6日 - has:geo、bounding_box: 和 point_radius: 地理运算符开始匹配。
  • 8月28日 - has:videos（直到2015年2月，此运算符匹配包含指向特定视频托管网站（如 youtube.com、vimeo.com 和 vivo.com）链接的帖子）。

​
2011

  • 7 月 20 日 - has:media 和 has:images 开始匹配。原生照片于 2010 年 8 月 9 日正式宣布。

​
2014

  • 12 月 3 日 - （大约） 某些 增强的 URL 元数据 带有 HTML 标题和描述开始出现在负载中。增强元数据在 2016 年 5 月更全面地引入。

​
2015

  • 2月10日 - has:videos 开始匹配“原生”X视频。
  • 2月17日 - has:profile_geo、profile_country:、profile_region:、profile_locality: 个人资料地理位置 操作符开始匹配。
  • 2月17日 - place_country: 和 place: 帖子地理位置操作符开始匹配。

​
2016

​
2017

  • 2月22日 - 投票元数据开始以丰富的原生格式提供可用。这些元数据没有相关的 Operators。

​
2022

  • 9月27日 - 自该日期起创建的所有 Post 对象均包含“已编辑 Post”相关的元数据。自该日期起，所有提供 Post 对象的 企业版 端点均已更新以返回此类元数据。所提供的编辑元数据包括 edit_history 和 edit_controls 对象。对于 2022 年 9 月 27 日之前创建的 Posts，将不会返回这些元数据。目前，没有可用的 企业版 Operator 与这些元数据相匹配。要进一步了解编辑 Post 的元数据，请参阅 Edit Posts 基础 页面。

​
2022

  • 9 月 29 日 - 自该日期起创建的所有 Post 对象均提供“已编辑 Post”元数据。自该日期起，所有返回 Post 对象的 企业版 端点均已更新以提供此元数据。提供的编辑元数据包括 edit_history 和 edit_controls 对象。对于 2022 年 9 月 27 日之前创建的 Post，不会返回这些元数据。目前，没有可用的 企业版 运算符与这些元数据相匹配。要了解有关编辑 Post 元数据的更多信息，请参阅 Edit Posts 基础 页面。

​
过滤提示

结合上述时间线信息，在编写 Search APIs 过滤器时，需要考虑许多细节。重点有两点：
  • 某些元数据具有“生效起始”日期，因此过滤器可能产生_假阴性_。这类搜索依赖的 Operators 基于在搜索区间内全部或部分时间并不存在的元数据。比如，如果你使用 has:images Operator 搜索 Post，那么在 2011 年 7 月之前不会有任何匹配。这是因为该 Operator 仅匹配_原生_照片（通过 X 用户界面附加到 Post）。若要获得更完整的照片分享 Post 数据集，针对 2011 年 7 月之前的过滤器需要加入匹配常见图片托管服务 URL 的规则子句。
  • 有些元数据是在 Post 发布到 X_之后_才被回填的。
在创建 PowerTrack 查询时，通常会关注以下几类属性：
  • X Profiles
  • 原创或转发的 Post
  • Post 语言分类
  • 地理标注的 Post
  • 分享链接的媒体
其中一些具有特定产品行为，另一些行为一致。详见下文。

​
X 个人资料

Search API 会提供历史 Post，并在_检索时刻_附带当时的用户个人资料数据。如果你请求一条 2014 年的 Post，用户的个人资料元数据将反映查询时的实际状态。

​
原始 Post 与转发

PowerTrack _is:retweet_ 运算符可用于包含或排除转发。使用该运算符的用户在处理 2009 年 8 月之前的数据时，需要针对转发匹配（或不匹配）采取两种策略。对于 2009 年 8 月之前的数据，需要检查 Post 消息本身，并使用精确短语匹配来查找与“@RT ”模式的匹配（实际上，如果你在筛选 2009 年 5 月至 8 月期间的转发，还应包含 “Via @” 模式）。对于 2009 年 8 月之后的时间段，可以使用 _is:retweet_ 运算符。

​
Post 语言分类

在按 Post 的语言分类进行过滤方面，X 的历史产品存在较大差异。构建 Search 归档时，所有 Post 都被回填了 X 的语言分类。因此，lang: 运算符可用于整个 Post 归档。

​
为 Post 进行地理参照

为 Post 进行地理参照主要有三种方式：
  • Post 文本中的地理提及。 基于 Post 文本中的地理提及进行匹配，尽管通常最具挑战性，因为它依赖于本地知识，但适用于整个 Post 存档。此处是一个 2006 年的地理参照匹配示例，基于“golden gate”过滤器，针对旧金山地区。
  • 用户为 Post 添加的地理标签。 通过搜索 API，自 2010 年 3 月起即可使用部分 Geo Operators 对 Post 进行匹配，另一些自 2015 年 2 月起提供：
    • 2010 年 3 月 6 日：has:geo、bounding_box:、point_radius:
    • 2015 年 2 月 17 日：place_country:、place:
  • 用户在账号资料中设置的“home”位置。 Profile Geo Operators 在 Historical PowerTrack 和 Search APIs 中均可用。对于 Search APIs，这些 Profile Geo 元数据自 2015 年 2 月起可用。对于 Profile Geo 元数据可用之前发布的 Post，可使用 bio_location: 运算符匹配非规范化的用户输入。
2012 年 3 月，引入了扩展 URL 增强功能。在此之前，Post 负载仅包含用户提供的 URL。因此，如果用户包含了短链接，想要匹配目标（已展开的）URL 会比较困难。通过 Search API，这些元数据自 2012 年 3 月起可用。 2016 年 7 月，引入了增强版 URL 增强功能。该版本会在 Post 负载中提供网站的 HTML 标题和描述，并提供用于匹配它们的运算符（Operators）。这些元数据自 2014 年 12 月开始出现。 2016 年 9 月，X 引入了“原生附件”，结尾处的共享链接不再计入 140 个字符的 Post 限制。上述两种 URL 增强仍适用于这些共享链接。 以下是相关 Search 运算符开始生效的时间：
  • 2006 年 10 月 26 日 - has:links
  • 2011 年 7 月 20 日 - has:images 和 has:media
  • 2011 年 8 月 - url:，配合Expanded URLs 增强。最早在 2006 年 9 月，(url:"spotify.com" OR url:gnip OR url:microsoft OR url:google OR url:youtube) 就能匹配 http://x.com/Adam/statuses/16602，尽管在 twitter_entities 和 gnip 对象中没有 urls[] 元数据。“youtube.com” 是一条消息内容的示例，即使没有任何 urls[] 元数据，也能匹配 url:youtube。
  • 2015 年 2 月 10 日 - 原生视频的 has:videos。在 2010/08/28 至 2015/02/10 之间，该运算符会匹配带有指向特定视频托管站点（如 youtube.com、vimeo.com 和 vivo.com）链接的 Posts。
  • 2016 年 5 月 1 日 - 基于Enhanced URLs 增强 的 url_title: 和 url_description:，普遍可用。首批增强 URL 元数据自 2014 年 12 月开始出现。

​
常见问题（FAQ）

​
常见的 Search Post API 问题

counts 端点与 data 端点返回的结果之间存在已知差异。您可能会发现结果不一致，因为 counts 端点是在合规处理之前生成的（因此不会计入已删除的 Post、scrub geo 等），而 data 端点在交付时符合合规要求，并会纳入所有合规事件。
这可能发生的原因有几种，包括：
  1. 你预期看到的 Post 来自受保护的账户
  2. data 端点会纳入所有合规事件（这意味着已删除的 Post、已清除的地理信息等将不会包含在响应中）。
这很可能是由于对我们的高级规则与过滤功能的不当使用造成的。请查看我们的文档此处，并确保你了解构建规则时的各项限制。
是的，包括：我们直接支持的所有库都可以在我们的 xdevplatform GitHub 页面找到：https://github.com/xdevplatform。还有其他第三方库也可能有所帮助；但请注意，其中一些可能无法与我们的高级和企业版产品配合使用。
是的。我们的 data 端点会在达到指定的 maxResults 上限或经过 30 天后进行分页。例如，如果在某个 30 天周期内你有 800 条 Post，你需要发起两次请求才能获取完整结果，因为每次请求最多可返回 500 条 Post（maxResults）。再比如，如果你在第一个月只有 400 条 Post，第二个月有 100 条 Post，你同样需要发起两次请求才能获取完整结果；因为即使第一次请求返回的 Post 少于指定的 maxResults，分页仍会在 30 天后进行。
Post 按时间倒序返回。例如，第一页的结果会显示与查询匹配的最新 Post；随后将通过分页继续返回，直到结果中的发布时间追溯到最初请求的 fromDate 为止。
只有原始的 Post 会计入计费。任何后续编辑将被忽略，不计入你的整体活动计数。企业版
我们的企业版解决方案可按需定制，并提供可预测的定价，以满足您的业务需求。请在此处提交申请以获取更多信息。
  • 请参阅我们的企业版 Search Post APIs 文档此处
  • 有关规则与筛选的实用信息请见此处
  • 有关使用 data 端点的实用信息请见此处
  • 有关使用 counts 端点的实用信息请见此处
  • 可用运算符列表请见此处
请联系你在 X 的客户经理，他们可以协助处理此事。

​
错误排查指南

错误代码 404 - 未找到
  1. 请确保为各个端点使用正确的参数（例如，buckets 字段只能与 counts 端点配合使用，不能用于 data 端点）
  2. 请再次核对 :product、:account_name 和 :label 字段是否正确。您可以在 GNIP Console 中找到您的 :label 字段（仅限企业版客户）。

​
API 参考文档

​
企业搜索 API

共有两种企业搜索 API：
  • 30-Day Search API - 提供过去 30 天内发布的 Tweet。
  • Full-Archive Search API - 提供最早可追溯至 2006 年的 Tweet，起始于 2006 年 3 月发布的第一条 Tweet。
这些搜索 API 采用统一的设计，以下文档同样适用于二者。请注意，对于 2022 年 9 月 29 日起创建的 Tweet，Tweet 对象将包含描述其编辑历史的 Tweet 编辑元数据。更多详情请参见 “Edit Tweets” 基础页面。 以下是集成企业搜索 API 时所需的重要信息：
  • 请求 Tweet 数据与计数的方法
  • 认证
  • 分页
  • API 请求参数与请求示例
  • API 响应 JSON 负载与响应示例
  • HTTP 响应代码
企业 API 提供对 Tweet 存档的低延迟、全保真、基于查询的访问。两种 API 的唯一差异在于可搜索的时间范围：要么是过去 30 天，要么最早可至 2006 年。时间范围可精确到分钟级。Tweet 数据按时间逆序返回，从与你的查询匹配的最新 Tweet 开始。Tweet 在发布后约 30 秒即可通过搜索 API 获取。

​
方法

Enterprise 搜索的基础 URI 为 https://gnip-api.x.com/search/。
方法说明
POST /search/:product/accounts/:account_name/:label检索过去 30 天内与指定 PowerTrack 规则匹配的 Tweet。
POST /search/:product/accounts/:account_name/:label/counts检索过去 30 天内与指定 PowerTrack 规则匹配的 Tweet 数量。
其中：
  • :product 表示你发起请求的搜索端点，可为 30day 或 fullarchive。
  • :account_name 是与你的账户关联的名称（区分大小写），如在 console.gnip.com 上所示。
  • :label 是与你的搜索端点关联的标签（区分大小写），如在 console.gnip.com 上所示。
例如，如果 TwitterDev 账户拥有 30 天搜索产品，且标签为“prod”（production 的缩写），则搜索端点为： 你的完整 Enterprise 搜索 API 端点会显示在 https://console.gnip.com。 下面提供了几个使用名为 curl 的简单 HTTP 工具的请求示例。这些示例使用包含 :product、:account_name 和 :label 的 URL。要使用这些示例，请务必将这些 URL 中的占位符替换为你的详细信息。

​
认证

对企业搜索 API 的所有请求都必须使用 HTTP 基础认证（Basic Authentication），凭据由用于登录你在 https://console.gnip.com 的账号的有效电子邮件地址与密码组成。每个请求都必须在 Authorization 请求头中携带这些凭据。

​
请求/响应行为

使用 fromDate 和 toDate 参数，您可以请求 API 所支持的任意时间段。30-Day 搜索 API 提供最近 31 天内的 Tweet（尽管称为“30-Day”API，但它提供 31 天的数据，以便用户可以发起整月范围的请求）。Full-Archive 搜索 API 提供可追溯到第一条 Tweet（2006 年 3 月 21 日）的结果。然而，单个响应会受限于您指定的 maxResults 或 31 天中较小的那个。如果匹配的 data 或您的时间范围超过您指定的 maxResults 或 31 天，您将收到一个“next”令牌，您应使用它对剩余的指定时间范围进行分页。 例如，假设您使用 Full-Archive 搜索，想要获取 2017 年 1 月 1 日到 2017 年 6 月 30 日期间与您的查询匹配的所有 Tweet。您将在请求中使用 fromDate 和 toDate 参数指定这整整六个月的时间段。搜索 API 将返回第一“页”的 Tweet，其数量与您的 maxResults 参数（默认 100）相匹配。假设还有更多的 Tweet（很可能会有），API 还会提供一个“next”令牌，使您能够请求下一“页”的 data。该过程会重复，直到 API 不再返回“next”令牌。有关更多详细信息，请参见下一节。 在发起 data 和计数请求时，返回的数据往往超过单个响应所能包含的数量。这种情况下，响应会包含一个“next”令牌。该“next”令牌作为根级 JSON 属性提供。只要出现“next”令牌，就表示还有更多数据需要获取，因此你需要继续发起 API 请求。 注意： “next”令牌在 data 请求与计数请求中的行为略有不同。两者的差异在下文说明，并在 API Reference 部分提供了示例响应。
数据分页
对数据的请求通常会产生超出单个响应可返回的数据量。每个数据请求都包含一个参数，用于设置每次请求返回的 Tweet 的最大数量。maxResults 参数的默认值为 100，可设置为 10–500 的范围。如果你的查询匹配的 Tweet 数量超过请求中使用的 maxResults 参数，响应会包含一个 next 令牌（作为根级 JSON 属性）。此 next 令牌用于后续请求，以检索该查询下一部分匹配的 Tweet（即下一“页”）。系统会持续返回 next 令牌，直到到达该查询结果的最后一“页”，此时将不再提供 next 令牌。 要请求下一“页”数据，你必须发起与原始请求完全相同的查询，包括（若使用）query、toDate 和 fromDate 参数，并包含一个 next 请求参数，其值设为前一个响应返回的值。可通过 GET 或 POST 请求使用该机制。但在 GET 请求的情况下，必须对 next 参数进行 URL 编码。 你可以持续传入上一次查询中的 next 元素，直至获取到查询所覆盖时间段内的所有 Tweet。当收到的响应未包含 next 元素时，表示你已到达最后一页，且在指定的查询与时间范围内不再有其他可用数据。
计数分页
“counts” 端点按天、按小时或按分钟提供与查询相关的 Tweet 数量。“counts” API 端点将返回一个带时间戳的计数数组，最多覆盖 31 天的计数字段。如果你请求超过 31 天的计数，将会返回一个 “next” 令牌。与 data 的 “next” 令牌相同，你必须发起与原始请求完全一致的查询，并包含一个 “next” 请求参数，其值为上一次响应返回的值。 除了请求超过 31 天的计数之外，还有另一种会返回 “next” 令牌的情况。对于高量查询，生成计数可能耗时过长，从而触发响应超时。当发生这种情况时，你会收到少于 31 天的计数，但会返回一个 “next” 令牌，以便继续请求完整的计数数据。重要提示： 超时只会返回完整的“桶”（bucket）——因此 2.5 天将产生 2 个完整天数的“桶”。
其他说明
  • 在搜索请求中使用 fromDate 或 toDate 时，您只能获得位于该时间范围内的结果。当到达该时间范围内的最后一组结果时，您将不会收到“next”令牌。
  • “next”元素可与 10–500 范围内任意 maxResults 值搭配使用（默认值为 100）。maxResults 决定每个响应返回的 Tweet 数量，但不会阻止您最终获取全部结果。
  • “next”元素不会过期。使用相同“next”查询的多个请求，无论何时发出，都会收到相同的结果。
  • 使用“next”参数对结果进行分页时，您可能会在查询边界处遇到重复项。您的应用应能够容忍这些情况。

​
数据端点

POST /search/:product/:label
端点模式：
此端点会返回指定查询与时间范围内的data。若未指定时间范围，时间参数将默认取最近 30 天。注意：也可通过使用 GET 请求（而非 POST）来实现同等功能，只需将下述参数编码到 URL 中。
数据请求参数
参数说明是否必需示例值
query相当于一条 PowerTrack 规则，最多可包含 2,048 个字符（对正向和负向子句的数量不设限）。

此参数应包含该 PowerTrack 规则的全部内容，包括所有运算符；规则的任何部分都不应拆分到查询的其他参数中。

注意： 并非所有 PowerTrack 运算符都受支持。受支持的运算符列于此处。		是(snow OR cold OR blizzard) weather
tag可使用标签将规则及其匹配的数据划分为不同的逻辑组。若提供规则标签，该标签将包含在 matching_rules 属性中。

建议为规则标签分配规则专属的 UUID，并在客户端维护所需的映射关系。		否8HYG54ZGTU
fromDate提供 Tweets 的最早 UTC 时间戳（使用全档案搜索可追溯至 2006/3/21）。时间戳粒度为分钟，且为包含式（例如 12:00 包含第 00 分钟）。

已指定： 仅使用 fromDate 而不提供 toDate 参数，将返回从现在起向过去直至 fromDate 的查询结果。

未指定： 若未指定 fromDate，API 将返回从现在起或指定的 toDate（若提供）起往前 30 天内的所有结果。

若 fromDate 与 toDate 参数均未使用，API 将返回最近 30 天内的所有结果，起始于请求发起时间，按时间倒序返回。		否201207220000
toDate提供 Tweets 的最新（最近）UTC 时间戳。时间戳粒度为分钟，且为不包含式（例如 11:59 不包含该小时第 59 分钟）。

已指定： 仅使用 toDate 而不提供 fromDate 参数，将返回 toDate 之前最近 30 天的数据。

未指定： 若未指定 toDate，API 将返回从现在起开始、按时间倒序直至 fromDate 的所有查询结果。

若 fromDate 与 toDate 参数均未使用，API 将返回整个 30 天索引内的所有结果，起始于请求发起时间，按时间倒序返回。		否201208220000
maxResults单个请求可返回的最大搜索结果数。取值在 10 与系统上限（当前为 500）之间。默认情况下，请求响应将返回 100 条结果。否500
next用于获取下一“页”结果的参数，详见此处。该参数的取值直接来自 API 返回的响应，不应修改。否NTcxODIyMDMyODMwMjU1MTA0
其他详细信息
可用时间范围30 天：最近 31 天
完整存档：2006 年 3 月 21 日至今
查询格式等同于一条 PowerTrack 规则，最多可包含 2,048 个字符（正向和负向子句数量不设上限）。

**注意：**并非所有 PowerTrack 运算符均受支持。请参阅可用运算符以获取受支持的运算符列表。
速率限制合作伙伴将在分钟级和秒级两个粒度受到速率限制。每分钟的速率限制将按合同约定因合作伙伴而异。但这些每分钟速率限制并非用于一次性突发。无论您的每分钟速率限制如何，所有合作伙伴对所有 data 和/或计数请求的总量，每秒最多限制为 20 个请求。
合规性通过 Full-Archive Search API 交付的所有 data 在交付时均符合合规要求。
实时可用性在 X 平台生成后的 30 秒内，data 即会进入索引并可用
示例 data 请求与响应
示例 POST 请求
  • 如下所示，POST 请求的请求参数通过 JSON 格式的请求体发送。
  • 要查询的 PowerTrack 规则的所有部分（例如关键词、以及像 bounding_box: 这样的其他运算符）都应放入 ‘query’ 参数中。
  • 不要将规则的各个部分拆分为查询 URL 中的独立参数。
以下是一个用于发起初始 data 请求的 POST（使用 cURL）命令示例： 
    curl -X POST -u<username> "https://gnip-api.x.com/search/:product/accounts/:account_name/:label.json" -d '{"query":"from:twitterDev","maxResults":500,"fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm"}'
如果 API 的 data 响应包含一个“next”令牌，下面展示了一个后续请求：它基于原始请求，并将“next”参数设为提供的令牌。 
    curl -X POST -u<username> "https://gnip-api.x.com/search/:product/accounts/:account_name/:label.json" -d '{"query":"from:twitterDev","maxResults":500,"fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm",
    "next":"NTcxODIyMDMyODMwMjU1MTA0"}'
示例 GET 请求
  • 在 GET 请求中，请求参数会采用标准 URL 编码并附加到 URL 中。
  • 查询的 PowerTrack 规则的所有部分（如关键词、其他运算符，例如 bounding_box:）都应放在 ‘query’ 参数中。
  • 不要在查询 URL 中将规则的各部分拆分为单独的参数。
下面是一个用于发起初始 data 请求的 GET（使用 cURL）命令示例： 
    curl -u<username> "http://gnip-api.x.com/search/:product/accounts/:account_name/:label.json?query=from%3Atwitterdev&maxResults=500&fromDate=yyyymmddhhmm&toDate=yyyymmddhhmm"
示例 data 响应
请注意，对于自 2022 年 9 月 29 日起创建的 Tweet，Tweet 对象将包含描述其编辑历史的 Tweet 编辑元数据。有关更多信息，请参阅 “Edit Tweets” 基础知识页面。 下面是一个 data 查询的示例响应。此示例假设可用的 Tweet 多于 ‘maxResults’，因此提供了一个 ‘next’ 令牌以用于后续请求。若与您的查询关联的 Tweet 不超过 ‘maxResults’，则响应中将不包含 ‘next’ 令牌。 ‘next’ 元素的值会随每次查询变化，应将其视为不透明字符串。响应正文中，‘next’ 元素将如下所示： 
{
    "results":
      [
            {--Tweet 1--},
            {--Tweet 2--},
            ...
            {--Tweet 500--}
      ],
    "next":"NTcxODIyMDMyODMwMjU1MTA0",
    "requestParameters":
      {
        "maxResults":500,
        "fromDate":"201101010000",
        "toDate":"201201010000"
      }
  }
对后续请求的响应可能如下所示（请注意新增的 Tweet 和不同的“next”值）： 
{
      "results":
      [
            {--Tweet 501--},
            {--Tweet 502--},
            ...
            {--Tweet 1000--}
      ],
      "next":"R2hCDbpBFR6eLXGwiRF1cQ",
      "requestParameters":
      {
        "maxResults":500,
        "fromDate":"201101010000",
        "toDate":"201201010000"
      }
  }
您可以继续传入先前查询返回的 ‘next’ 元素，直到获取到查询时间范围内的所有 Tweet 为止。若收到的响应不包含 ‘next’ 元素，则表示您已到达最后一页，且在所选时间范围内没有更多可用的数据。

​
计数接口

/search/:stream/counts
端点模式：
/search/fullarchive/accounts/:account_name/:label/counts.json 此端点返回指定查询的计数（数据量）。如果未指定时间范围，时间参数将默认为过去 30 天。数据量将以带时间戳的数组返回，粒度可为按日、按小时（默认）或按分钟。 注意： 也可通过使用 GET 请求而非 POST 请求来实现此功能，只需将下文所述参数编码到 URL 中即可。
计数请求参数
参数描述是否必需示例值
query相当于一条 PowerTrack 规则，最多 2,048 个字符（正向和负向子句数量不受限制）。

此参数应包含该 PowerTrack 规则的全部内容，包括所有运算符；不要将规则的任何部分拆分到其他查询参数中。

注意： 并非所有 PowerTrack 运算符都受支持。请参阅可用运算符了解受支持的运算符列表。		是(snow OR cold OR blizzard) weather
fromDate提供 Tweet 的最早 UTC 时间戳（可最早回溯至 2006/3/21）。时间戳精确到分钟且为包含（例如 12:00 包含第 00 分钟）。

已指定： 仅提供 fromDate 而不提供 toDate 时，API 将从现在起向前回溯至 fromDate，返回该查询的计数（data 量）。如果 fromDate 早于当前时间 31 天之前，将返回 next 令牌以分页检索。

未指定： 如未指定 fromDate，API 将返回从当前时间起向前 30 天（或若指定了 toDate，则为 toDate 之前 30 天）的计数（data 量）。

如果既未提供 fromDate 也未提供 toDate，API 将返回最近 30 天的计数（data 量），从发起请求时刻起向前回溯。		否201207220000
toDate提供 Tweet 的最新 UTC 时间戳。时间戳精确到分钟且为不包含（例如 11:59 不包含该小时的第 59 分钟）。

已指定： 仅提供 toDate 而不提供 fromDate 时，将返回 toDate 之前 30 天内的最新计数（data 量）。

未指定： 如未指定 toDate，API 将返回从现在起向前至 fromDate 的该查询计数（data 量）。如果 fromDate 早于当前时间 31 天之前，将返回 next 令牌以分页检索。

如果既未提供 fromDate 也未提供 toDate，API 将返回最近 30 天的计数（data 量），从发起请求时刻起向前回溯。		否201208220000
bucket计数数据的时间粒度。可在请求的时间范围内按天、小时或分钟返回计数数据。默认按小时返回。可选值：‘day’、‘hour’、‘minute’否minute
next用于按此处所述获取下一“页”结果。该参数所用的值直接取自 API 的响应，且不应修改。否NTcxODIyMDMyODMwMjU1MTA0
其他详细信息
可用时间范围30 天：过去 31 天
完整存档：2006 年 3 月 21 日至今
查询格式相当于一条 PowerTrack 规则，最长 2,048 个字符。

**注意：**并非所有 PowerTrack 运算符均受支持。请参阅可用运算符获取受支持运算符列表。
速率限制合作伙伴将在分钟级和秒级两个粒度上受到速率限制。每分钟的速率限制将按合同约定，因合作伙伴而异。但这些每分钟速率限制并非用于单次突发使用。无论您的每分钟速率限制如何，所有合作伙伴每秒最多 20 个请求，该上限在所有 data 和/或计数请求间汇总计算。
计数精度通过此端点提供的计数反映实际发生的 Tweet 数量，不包含后续合规事件（删除、地理信息清理）产生的影响。由于用户的合规操作，被计入的某些 Tweet 可能无法通过 data 端点获取。
计数请求和响应示例
示例 POST 请求
  • 在 POST 请求中，请求参数通过 JSON 格式的请求体发送，如下所示。
  • 要查询的 PowerTrack 规则的所有组成部分（例如关键词、以及如 bounding_box: 等其他运算符）都应放入 query 参数中。
  • 请勿将规则的部分拆分为单独参数置于查询 URL 中。
下面是一个用于发起初始计数请求的 POST（使用 cURL）命令示例： 
    curl -X POST -u<username> "https://gnip-api.x.com/search/:product/accounts/:account_name/:label/counts.json" -d '{"query":"TwitterDev","fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm","bucket":"day"}'
如果 API 的计数响应中包含一个“next”令牌，下面是一个后续请求：在原始请求的基础上，将“next”参数设置为提供的令牌。 
    curl -X POST -u<username> "https://gnip-api.x.com/search/:product/accounts/:account_name/:label/counts.json" -d '{"query":"TwitterDev","fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm","bucket":"day",
    "next":"YUcxO87yMDMyODMwMjU1MTA0"}'
示例 GET 请求
  • GET 请求的参数会使用标准 URL 编码并包含在 URL 中
  • 要查询的 PowerTrack 规则的所有组成部分（例如关键字、以及如 bounding_box: 之类的其他运算符）都应放在 query 参数中
  • 不要将规则的部分拆分为查询 URL 中的独立参数
下面是一个用于发起初始计数请求的 GET 示例命令（使用 cURL）： 
    curl -u<username> "http://gnip-api.x.com/search/fullarchive/accounts/:account_name/:label/counts.json?query=TwitterDev&bucket=day&fromDate=yyyymmddhhmm&toDate=yyyymmddhhmm"

​
示例计数响应

以下是对计数（数据量）查询的示例响应。此示例响应包含一个“next”令牌，这表示计数请求的时间范围超过了31天，或者提交的查询关联的数据量足够大，从而触发了部分响应。 “next”元素的值会随每次查询而变化，应将其视为不透明字符串。“next”元素在响应正文中的形式如下： 
    {
      "results": [
        { "timePeriod": "201101010000", "count": 32 },
        { "timePeriod": "201101020000", "count": 45 },
        { "timePeriod": "201101030000", "count": 57 },
        { "timePeriod": "201101040000", "count": 123 },
        { "timePeriod": "201101050000", "count": 134 },
        { "timePeriod": "201101060000", "count": 120 },
        { "timePeriod": "201101070000", "count": 43 },
        { "timePeriod": "201101080000", "count": 65 },
        { "timePeriod": "201101090000", "count": 85 },
        { "timePeriod": "201101100000", "count": 32 },
        { "timePeriod": "201101110000", "count": 23 },
        { "timePeriod": "201101120000", "count": 85 },
        { "timePeriod": "201101130000", "count": 32 },
        { "timePeriod": "201101140000", "count": 95 },
        { "timePeriod": "201101150000", "count": 109 },
        { "timePeriod": "201101160000", "count": 34 },
        { "timePeriod": "201101170000", "count": 74 },
        { "timePeriod": "201101180000", "count": 24 },
        { "timePeriod": "201101190000", "count": 90 },
        { "timePeriod": "201101200000", "count": 85 },
        { "timePeriod": "201101210000", "count": 93 },
        { "timePeriod": "201101220000", "count": 48 },
        { "timePeriod": "201101230000", "count": 37 },
        { "timePeriod": "201101240000", "count": 54 },
        { "timePeriod": "201101250000", "count": 52 },
        { "timePeriod": "201101260000", "count": 84 },
        { "timePeriod": "201101270000", "count": 120 },
        { "timePeriod": "201101280000", "count": 34 },
        { "timePeriod": "201101290000", "count": 83 },
        { "timePeriod": "201101300000", "count": 23 },
        { "timePeriod": "201101310000", "count": 12 }
       ],
      "totalCount":2027,
      "next":"NTcxODIyMDMyODMwMjU1MTA0",
      "requestParameters":
        {
          "bucket":"day",
          "fromDate":"201101010000",
          "toDate":"201201010000"
        }
    }
对后续请求的响应可能如下所示（注意新的计数时间轴以及不同的“next”值）： 
    {
      "results": [
        { "timePeriod": "201102010000", "count": 45 },
        { "timePeriod": "201102020000", "count": 76 },
         ....
        { "timePeriod": "201103030000", "count": 13 }
     ],
     "totalCount":3288,
     "next":"WE79fnakFanyMDMyODMwMjU1MTA0",
     "requestParameters":
        {
          "bucket":"day",
          "fromDate":"201101010000",
          "toDate":"201201010000"
        }
    }
在查询的时间范围内，您可以持续传入上一次查询返回的 ‘next’ 元素，直到获取到该时间段内的所有计数。收到不包含 ‘next’ 元素的响应时，表示您已到达最后一页，且在该时间范围内不再有更多计数。

​
HTTP 响应代码

状态文本描述
200OK请求成功。JSON 响应将类似如下：
400Bad Request通常因请求中包含无效的 JSON，或请求未发送任何 JSON 负载而返回此响应。
401Unauthorized因凭证无效导致 HTTP 认证失败。请使用你的凭证登录 console.gnip.com，确认在请求中正确使用。
404Not Found在请求发送到的 URL 未找到资源，可能是因为 URL 不正确。
422Unprocessable Entity因查询参数无效而返回，例如无效的 PowerTrack 规则。
429Unknown Code你的应用已超出连接请求的限制。相应的 JSON 消息将类似如下：
500Internal Server Error服务器端发生错误。请使用指数退避策略重试请求。
502Proxy Error服务器端发生错误。请使用指数退避策略重试请求。
503Service Unavailable服务器端发生错误。请使用指数退避策略重试请求。