构建 query（查询）
query（查询）限制 您的 query（查询）会因所使用的访问级别而受到限制。 如果您拥有 Pro 访问权限，单个 query（查询）最长可达 512 个字符。 如果您拥有 Enterprise 访问权限，请联系您的客户经理。 运算符可用性 尽管大多数运算符对所有开发者均可用，但有些仅限已获批 Enterprise 访问权限的用户使用。我们在运算符列表表格中使用以下标签标注各运算符对应的可用访问级别：- Core 运算符：使用任何Project时均可用。
- Advanced 运算符：在具有 Enterprise 访问权限的 Project 中可用。
运算符类型：可独立使用与需搭配使用
可独立使用的运算符 可以单独使用，或与任何其他运算符（包括那些需要搭配使用的运算符）一同使用。 例如，下面的 query（查询）可以正常运行，因为它使用了可独立使用的 #hashtag 运算符： #xapiv2 需搭配使用的运算符 不能在 query（查询）中单独出现；只有当 query（查询）中至少包含一个可独立使用的运算符时才能使用。原因是单独使用这些运算符范围过于宽泛，可能匹配到数量极其庞大的 Post。 例如，以下 query（查询）不受支持，因为它们只包含需搭配使用的运算符： has:media has:links OR is:retweet 如果我们加入一个可独立使用的运算符，例如短语 “X data”，该 query（查询）就能正常运行。 “X data” has:mentions (has:media OR has:links)布尔运算符与分组
如果你希望在单个 query 中串联多个运算符，可以使用以下工具：| AND 逻辑 | 连续运算符之间以空格分隔将产生布尔 “AND” 逻辑，即仅当同时满足两个条件时才会匹配 Post。例如，snow day #NoSchool 将匹配包含术语 snow、day 以及话题标签 #NoSchool 的 Post。 |
| OR 逻辑 | 连续运算符之间以 OR 连接将产生 OR 逻辑，即只要满足任一条件就会匹配 Post。例如，指定 grumpy OR cat OR #meme 将匹配任何至少包含术语 grumpy 或 cat，或话题标签 #meme 的 Post。 |
| NOT 逻辑，取反 | 在关键字（或任何运算符）前添加短横线（-）可将其取反（NOT）。例如，cat #meme -grumpy 将匹配包含话题标签 #meme 且包含术语 cat 的 Post，但前提是它们不包含术语 grumpy。一个常见的 query 子句是 -is:retweet，它不会匹配转发，因此只匹配原始 Post、Quote Tweets 和回复。所有运算符都可取反，但被取反的运算符不能单独使用。 |
| 分组 | 你可以使用括号将运算符分组。例如，(grumpy cat) OR (#meme has:images) 将返回包含术语 grumpy 和 cat 的 Post，或包含话题标签 #meme 且带图片的 Post。注意，先应用 AND，再应用 OR。 |
- 先合并由 AND 逻辑连接的运算符
- 然后应用由 OR 逻辑连接的运算符
- apple OR iphone ipad 将被评估为 apple OR (iphone ipad)
- ipad iphone OR android 将被评估为 (iphone ipad) OR android
- (apple OR iphone) ipad
- iphone (ipad OR android)
- 通常不建议在你的 query 中使用宽泛的、独立的运算符（例如单个关键词或#hashtag），因为这很可能会匹配到海量的 Posts。构建更严谨的 query 将得到更具体的一组匹配 Posts，并有望提高 Post 计数的准确性，帮助你获得更有价值的洞察。
- 例如，如果你的 query 只是关键词 happy，你每天可能会得到 200,000–300,000 条 Posts。
- 添加更多条件运算符会缩小结果范围，例如 (happy OR happiness) place_country:GB -birthday -is:retweet
- 编写高效的查询还有助于遵守 query 的字符长度限制。字符计数包含整个 query 字符串，包括空格和运算符。
- 例如，下面的 query 长度为 59 个字符：(happy OR happiness) place_country:GB -birthday -is:retweet
将 query 添加到您的请求中
要将 query 添加到请求中，您必须使用 query 参数。与任何查询参数一样，必须确保对已编写的 query 进行 HTTP 编码。 下面是使用 cURL 命令的示例。若要使用该命令，请务必将 $BEARER_TOKEN 替换为您自己的 Bearer Token：查询示例
跟踪自然灾害 以下 query（查询）用于匹配来自气象机构和监测站、讨论 2017 年袭击休斯顿的飓风 Harvey 的原始 Post。 下面是不带 HTTP 编码的 query（查询）示例： has:geo (from:NWSNHC OR from:NHC_Atlantic OR from:NWSHouston OR from:NWSSanAntonio OR from:USGS_TexasRain OR from:USGS_TexasFlood OR from:JeffLindner1) -is:retweet 下面是带有 HTTP 编码、query（查询）参数以及近期 Post 计数 URI 的示例： https://api.x.com/2/tweets/counts/recent?query=-is%3Aretweet%20has%3Ageo%20(from%3ANWSNHC%20OR%20from%3ANHC\_Atlantic%20OR%20from%3ANWSHouston%20OR%20from%3ANWSSanAntonio%20OR%20from%3AUSGS\_TexasRain%20OR%20from%3AUSGS_TexasFlood%20OR%20from%3AJeffLindner1) 分析会话的情感倾向 下面这条规则可用于更好地理解围绕话题标签 #nowplaying 展开的会话情感，但范围仅限于在北美发布的 Post。 下面是两个不同的 query（查询）——一个用于正向，一个用于负向——在不带 HTTP 编码时的示例： #nowplaying (happy OR exciting OR excited OR favorite OR fav OR amazing OR lovely OR incredible) (place_country:US OR place_country:MX OR place_country:CA) -horrible -worst -sucks -bad -disappointing #nowplaying (horrible OR worst OR sucks OR bad OR disappointing) (place_country:US OR place_country:MX OR place_country:CA) -happy -exciting -excited -favorite -fav -amazing -lovely -incredible 下面是带有 HTTP 编码、query（查询）参数以及近期 Post 计数 URI 的示例： https://api.x.com/2/tweets/counts/recent?query=%23nowplaying%20(happy%20OR%20exciting%20OR%20excited%20OR%20favorite%20OR%20fav%20OR%20amazing%20OR%20lovely%20OR%20incredible)%20(place\_country%3AUS%20OR%20place\_country%3AMX%20OR%20place_country%3ACA)%20-horrible%20-worst%20-sucks%20-bad%20-disappointing https://api.x.com/2/tweets/counts/recent?query=%23nowplaying%20(horrible%20OR%20worst%20OR%20sucks%20OR%20bad%20OR%20disappointing)%20(place\_country%3AUS%20OR%20place\_country%3AMX%20OR%20place_country%3ACA)%20-happy%20-exciting%20-excited%20-favorite%20-fav%20-amazing%20-lovely%20-incredible 查找与特定 Post 注解相关的 Post 此规则用于筛选包含宠物（非猫）图片的原始 Post，且该 Post 的语言被识别为日语。为此，我们使用了 context: 运算符来利用Post 注解功能。我们首先使用Post 查询 endpoint，并通过 tweet.fields=context_annotations fields 参数来确定在 query（查询）中需要使用的 domain.entity ID：- 与猫相关的 Post 会返回 domain 66（Interests and Hobbies 类别），其 entity 为 852262932607926273（Cats）。
- 与宠物相关的 Post 会返回 domain 65（Interests and Hobbies Vertical），其 entity 为 852262932607926273（Pets）。
运算符
| 操作符 | 类型 | 可用性 | 描述 |
|---|---|---|---|
keyword | 独立 | Core | 匹配 Post 正文中的关键词。这是一种分词匹配，意味着您的关键词字符串将与 Post 正文的分词文本进行匹配。分词会根据标点符号、符号和 Unicode 基本平面分隔符字符来分割单词。例如，包含文本”I like coca-cola”的 Post 将被分割为以下词元：I、like、coca、cola。然后将这些词元与您查询中使用的关键词字符串进行比较。要匹配包含标点符号（例如 coca-cola）、符号或分隔符字符的字符串，您必须将关键词用双引号括起来。示例：pepsi OR cola OR "coca cola" |
emoji | 独立 | Core | 匹配 Post 正文中的表情符号。与关键词类似，表情符号是分词匹配，意味着您的表情符号将与 Post 正文的分词文本进行匹配。请注意，如果表情符号有变体，您必须将其用双引号括起来才能添加到查询中。示例：(😃 OR 😡) 😬 |
"exact phrase match" | 独立 | Core | 匹配 Post 正文中的确切短语。示例：("X API" OR #v2) -"recent counts" |
# | 独立 | Core | 匹配包含已识别话题标签的任何 Post，如果话题标签是 Post 中的已识别实体。此操作符执行精确匹配，而非分词匹配，意味着规则 #thanku 将匹配包含确切话题标签 #thanku 的 Post，但不会匹配包含话题标签 #thankunext 的 Post。示例：#thankunext #fanart OR @arianagrande |
@ | 独立 | Core | 匹配提及给定用户名的任何 Post，如果用户名是已识别实体（包括 @ 字符）。示例：(@XDevelopers OR @API) -@X |
$ | 独立 | Advanced | 匹配包含指定”股票标签”的任何 Post（其中词元的前导字符是”"字符）。请注意，股票标签操作符依赖于 X 的"符号"实体提取来匹配股票标签，而不是尝试从正文本身提取股票标签。示例：`twtr OR @XDevelopers -$fb` |
from: | 独立 | Core | 匹配来自特定用户的任何 Post。值可以是用户名（不包括 @ 字符）或用户的数字用户 ID。每个 from: 操作符只能传递一个用户名/ID。示例：from:XDevelopers OR from:API -from:X |
to: | 独立 | Core | 匹配回复特定用户的任何 Post。值可以是用户名（不包括 @ 字符）或用户的数字用户 ID。每个 to: 操作符只能传递一个用户名/ID。示例：to:XDevelopers OR to:API -to:X |
url: | 独立 | Core | 对 Post 的任何有效格式 URL 执行分词匹配。此操作符可以匹配 url 或 expanded_url fields 的内容。例如，包含”You should check out X Developer Labs: https://t.co/c0A36SWil4"的 Post（短 URL 重定向到 https://developer.x.com）将匹配以下两个规则：`from:XDevelopers url:“https://developer.x.com”` 和 from:XDevelopers url:"https://t.co"。包含标点符号或特殊字符的词元和短语应该用双引号括起来。 |
retweets_of: | 独立 | Core | 匹配指定用户的转发 Post。值可以是用户名（不包括 @ 字符）或用户的数字用户 ID。每个 retweets_of: 操作符只能传递一个用户名/ID。示例：retweets_of:XDevelopers OR retweets_of:API |
context: | 独立 | Core | 匹配具有特定域 id/实体 id 对的 Post。每个 context: 操作符只能传递一个域/实体。示例：context:domain_id.entity_id。您可以使用 OR 操作符组合多个域/实体：(context:47.113922 9372198469633 OR context:11.1088514520308342784) |
entity: | 独立 | Core | 匹配具有特定实体字符串值的 Post。您只能传递一个 entity: 操作符。示例：entity:"string declaration of entity/place"。请注意，这仅适用于最近搜索。 |
conversation_id: | 独立 | Core | 匹配共享相同 conversation_id 的 Post。conversation_id 设置为开始对话的 Post 的 Post ID。当发布对 Post 的回复时，甚至是对回复的回复，conversation_id 都会添加到其 JSON 负载中。每个 conversation_id: 操作符只能传递一个对话 ID。示例：conversation_id:1334987486343299072 (from:XDevelopers OR from:API) |
list: | 独立 | Advanced | 匹配由指定 List 成员用户发布的 Post。例如，如果 @XDevelopers 和 @API 是 List 123 的成员，并且您在查询中包含 list:123，您的响应将仅包含这些账户发布的 Post。您可以通过使用 List 查找 endpoint 找到 List ID。示例：list:123 |
place: | 独立 | Advanced | 匹配标记有指定位置或 X 地点 ID 的 Post。多词地点名称（“New York City”、“Palo Alto”）应该用引号括起来。每个 place: 操作符只能传递一个地点。注意：有关如何获取 X 地点 ID，请参阅 GET geo/search Standard v1.1 endpoint。示例：place:"new york city" OR place:seattle OR place:fd70c22040963ac7 |
place_country: | 独立 | Advanced | 匹配与标记地点/位置关联的国家代码与给定 ISO alpha-2 字符代码匹配的 Post。您可以在维基百科上找到有效 ISO 代码列表。每个 place_country: 操作符只能传递一个 ISO 代码。示例：place_country:US OR place_country:MX OR place_country:CA |
point_radius: | 独立 | Advanced | 当存在时，匹配 Post 的 place.geo.coordinates 对象，在 X 中，匹配地点地理多边形，其中地点多边形完全包含在定义区域内。point_radius:[longitude latitude radius]。支持的半径单位是英里（mi）和公里（km）。半径必须小于 25 英里。经度范围为 ±180。纬度范围为 ±90。所有坐标均为十进制度。规则参数包含在方括号内，用空格分隔。示例：point_radius:[2.355128 48.861118 16km] OR point_radius:[-41.287336 174.761070 20mi] |
bounding_box: | 独立 | Advanced | 当存在时，匹配 Post 的 place.geo.coordinates 对象，在 X 中，匹配地点地理多边形，其中地点多边形完全包含在定义区域内。bounding_box:[west_long south_lat east_long north_lat]。边界框的宽度和高度必须小于 25 英里。经度范围为 ±180。纬度范围为 ±90。所有坐标均为十进制度。规则参数包含在方括号内，用空格分隔。示例：bounding_box:[-105.301758 39.964069 -105.178505 40.09455] |
is:retweet | 需要连接 | Core | 匹配符合其余指定规则的转发。此操作符仅查找真正的转发（例如，使用转发按钮生成的转发）。引用 Tweet 不会被此操作符匹配。示例：data @XDevelopers -is:retweet |
is:reply | 需要连接 | Core | 仅传递匹配规则的明确回复。也可以否定以排除匹配查询的回复。注意：此操作符也适用于过滤的流 endpoint。与过滤的流一起使用时，此操作符匹配对原始 Post 的回复、引用 Post 中的回复以及转发中的回复。示例：from:XDevelopers is:reply |
is:quote | 需要连接 | Core | 返回所有引用 Tweet，也称为带评论的 Post。示例："sentiment analysis" is:quote |
is:verified | 需要连接词 | 核心 | 仅返回作者已通过 X 认证的 Post。示例：#nowplaying is:verified |
-is:nullcast | 需要连接词 | 高级 | 移除仅为在 ads.x.com 上推广而创建的、具有 "source":"Twitter for Advertisers (legacy)" 或 "source":"Twitter for Advertisers" 的 Post。此操作符必须使用否定形式。有关 Nullcasted Post 的更多信息，请参阅我们的 Post 可用性页面。示例："mobile games" -is:nullcast |
has:hashtags | 需要连接词 | 核心 | 匹配包含至少一个话题标签的 Post。示例：from:XDevelopers -has:hashtags |
has:cashtags | 需要连接词 | 高级 | 匹配包含股票标签符号（带有前导 ‘' 字符，例如 `tag）的 Post。示例：#stonks has:cashtags` |
has:links | 需要连接词 | 核心 | 此操作符匹配在 Post 正文中包含链接和媒体的 Post。示例：from:XDevelopers announcement has:links |
has:mentions | 需要连接词 | 核心 | 匹配提及其他 X 用户的 Post。示例：#nowplaying has:mentions |
has:media | 需要连接词 | 核心 | 匹配包含媒体对象（如照片、GIF 或视频）的 Post，由 X 判定。此操作符不会匹配使用 Periscope 创建的媒体，或包含其他媒体托管网站链接的 Post。示例：(kittens OR puppies) has:media |
has:images | 需要连接词 | 核心 | 匹配包含可识别图像 URL 的 Post。示例：#meme has:images |
has:videos | 需要连接词 | 核心 | 匹配包含原生 X 视频（直接上传到 X）的 Post。此操作符不会匹配使用 Periscope 创建的视频，或包含其他视频托管网站链接的 Post。示例：#icebucketchallenge has:videos |
has:geo | 需要连接词 | 高级 | 匹配具有 X 用户提供的 Post 特定地理位置数据的 Post。这可以是 X 地点形式的位置，包含相应的显示名称、地理多边形和其他字段，或在极少数情况下，是地理经纬度坐标。注意：匹配地点（Post 地理位置）的操作符仅包含来自原始 Post 的匹配结果。转发不包含任何地点数据。示例：recommend #paris has:geo -bakery |
lang: | 需要连接词 | 核心 | 匹配已被 X 分类为特定语言的 Post（当且仅当该 Post 已被分类时）。需要注意的是，每个 Post 目前仅被分类为一种语言，因此对多种语言进行 AND 操作将不会产生任何结果。每个 lang: 操作符只能传递一个 BCP 47 语言标识符。注意：如果无法进行语言分类，提供的结果是 ‘und’（表示未定义）。示例：recommend #paris lang:en |
| 阿姆哈拉语: 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 | 乌尔都语: ur |
| 爱沙尼亚语: et | 韩语: ko | 简体中文: zh-CN | 维吾尔语: ug |
| 芬兰语: fi | 老挝语: lo | 信德语: sd | 越南语: vi |
| 法语: fr | 拉脱维亚语: lv | 僧伽罗语: si | 威尔士语: cy |
| 格鲁吉亚语: ka | 立陶宛语: lt |