跳转到主要内容

​
构建用于搜索 Post 的查询

搜索端点通过 GET 请求接受单一查询，并返回与该查询匹配的一组历史 Post。查询由用于匹配多种 Post 属性的操作符组成。 

​
目录

​
构建查询

​
查询限制

你的查询限制取决于所使用的访问级别。 如果你拥有基础或免费访问权限，对于“最近搜索”端点，查询最长为 512 个字符。 如果你拥有免费访问权限，对于“完整存档搜索”端点，查询最长为 1,024 个字符。 

​
运算符可用性

虽然大多数运算符对所有开发者均可用，但也有一些仅限特定访问级别使用。我们在运算符列表表格中使用以下标签标示各运算符对应的访问级别：
  • 核心运算符： 在使用任何Project时可用。
  • 高级运算符： 在使用具有特定访问级别的 Project 时可用

​
运算符类型：独立版与需连词

独立版运算符 可以单独使用，也可以与任何其他运算符（包括需要连词的运算符）一起使用。 例如，下面的查询可用，因为它使用了独立版的 #hashtag 运算符： #xapiv2 需连词 运算符不能在查询中单独使用；只有在查询中至少包含一个独立版运算符时才能使用。因为单独使用这些运算符范围过于宽泛，会匹配到数量极其庞大的 Post。 例如，以下查询不受支持，因为它们只包含需连词运算符： has:media has:links OR is:retweet 如果我们加入一个独立版运算符，比如短语 "X data"，该查询就能正常运行。 "X data" has:mentions (has:media OR has:links)

​
布尔运算符与分组

如果你想在单个查询中串联多个运算符，可以使用以下工具：
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 时匹配。一个常见的查询子句是 -is:retweet，它不会匹配 Retweet，因此只匹配原始 Post、Quote Tweets 和回复。所有运算符都可以取反，但取反的运算符不能单独使用。
分组你可以使用括号将运算符分组。比如，(grumpy cat) OR (#meme has:images) 将返回包含术语 grumpy 和 cat 的 Post，或包含图片且带有话题标签 #meme 的 Post。注意先应用 AND，再应用 OR。
关于取反的说明 运算符 -is:nullcast 必须始终以取反形式使用。 取反的运算符不能单独使用。 不要对一组用括号分组的运算符整体取反。请分别对每个运算符取反。例如，与其使用 skiing -(snow OR day OR noschool)，建议使用 skiing -snow -day -noschool。 

​
运算顺序

当同时使用 AND 和 OR 时，查询将按照以下顺序进行解析。
  1. 先处理由 AND 逻辑连接的运算符
  2. 再处理由 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)

​
标点、变音符号与大小写敏感性

如果你在关键字或话题标签的查询中使用带重音或变音符号的字符，它将匹配包含带这些重音和变音符号的术语，以及使用普通字符的术语的 Post 文本。例如，包含关键字 Diacrítica 或话题标签 #cumpleaños 的查询，将会匹配 Diacrítica 或 #cumpleaños，也会匹配不带重音 í 或西班牙语字母 ñ 的 Diacritica 或 #cumpleanos。 带重音或变音符号的字符与普通字符同等处理，且不会被视为词边界。例如，包含关键字 cumpleaños 的查询，只会匹配包含单词 cumpleaños 的活动，不会匹配包含 cumplea、cumplean 或 os 的活动。 所有运算符都以不区分大小写的方式进行评估。例如，查询 cat 将匹配包含以下任意形式的 Posts：cat、CAT、Cat。 过滤流 的匹配行为与 Search Posts 不同。在构建过滤流规则时，请注意，包含重音和变音符号的关键字和话题标签只会匹配同样包含该重音和变音符号的术语，不会匹配使用普通字符的术语。 例如，包含关键字 Diacrítica 或话题标签 #cumpleaños 的过滤流规则，只会匹配术语 Diacrítica 和 #cumpleaños，不会匹配不带重音 í 或西班牙语字母 ñ 的 Diacritica 或 #cumpleanos

​
具体性与效率

当你开始构建查询时，请牢记以下要点。
  • 在查询中使用宽泛的、独立的运算符（例如单个关键词或#hashtag）通常不建议，因为这很可能会匹配到海量的 Post。构建更为严谨的查询将得到更为具体的匹配 Post 集合，并有望减少你为寻找有价值洞见而需要从负载中剔除的噪音。 
    • 例如，如果你的查询只是关键词 happy，你很可能每天会获得 200,000 - 300,000 条 Post。
    • 添加更多条件运算符会缩小搜索结果范围，例如 (happy OR happiness) place_country:GB -birthday -is:retweet
  • 编写高效的查询还有助于遵守查询字符长度限制。字符统计包含整个查询字符串，包括空格和运算符。
    • 例如，以下查询长度为 59 个字符：(happy OR happiness) place_country:GB -birthday -is:retweet

​
引用 Tweet 的匹配行为

使用 Search Posts 端点时，操作符不会匹配被引用的原始 Post 的内容，只会匹配该 Quote Tweet 中包含的内容。 但请注意，filtered stream 会同时匹配被引用的原始 Post 的内容以及该 Quote Tweet 的内容。

​
迭代构建查询

请尽早并反复测试你的查询
第一次就让查询返回“正确”的结果并不常见。X 上的内容极为庞杂，许多细节起初可能并不明显，而上述查询语法也可能不易与您期望的搜索精准匹配。在构建查询时，定期进行测试至关重要。 在本节中，我们将从以下查询开始，并根据测试过程中得到的结果进行调整： happy OR happiness
使用结果来缩小查询范围
在测试查询时，你应当浏览返回的 Posts，查看它们是否包含你期望获取的 data。先从宽泛的查询和更大范围的 Post 匹配开始，这样可以先审查结果，再收紧查询以过滤掉不需要的结果。   当我们测试示例查询时，注意到获得了多种不同语言的 Posts。在这种情况下，我们只想接收英文的 Posts，因此将添加 lang: 运算符： (happy OR happiness) lang:en 测试返回了许多祝别人生日快乐的 Posts，所以我们将添加 -birthday 作为取反关键词运算符。我们还只想接收原创的 Posts，因此添加了取反的 -is:retweet 运算符： (happy OR happiness) lang:en -birthday -is:retweet
在需要的情况下扩大匹配范围
如果你发现未收到预期的data，并且确认存在应该返回的Posts，则可能需要通过移除会过滤掉目标data的运算符来放宽查询范围。 在我们的示例中，我们注意到个人时间线上还有其他表达我们所寻找情绪的Posts，但未出现在测试结果中。为确保更高的覆盖率，我们将添加关键词 excited 和 elated。 (happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet X 上的趋势变化很快。维护查询应是一个持续的过程。如果你计划长期使用某个查询，建议定期查看你接收到的 data，判断是否需要调整。 在我们的示例中，我们注意到开始收到一些祝人们“节日快乐”的 Post。由于我们不希望这些 Post 出现在结果中，我们将添加一个取反的 -holidays 关键词。 (happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays

​
将查询添加到你的请求中

要将查询添加到你的请求中，必须使用 query 参数。与任何查询参数一样，请确保对你编写的查询进行 HTTP 编码。 下面是一个使用 cURL 命令的示例，其中还包含 tweet.fields 和 max_results 参数。如果你想使用此命令，请务必将 $BEARER_TOKEN 替换为你自己的 Bearer Token： 
curl https://api.x.com/2/tweets/search/recent?query=cat%20has%3Amedia%20-grumpy&tweet.fields=created_at&max_results=100 -H "Authorization: Bearer $BEARER_TOKEN"

​
查询示例

​
追踪自然灾害

以下查询将匹配来自气象机构和监测站、讨论 2017 年袭击休斯敦的飓风 Harvey 的原始 Post。 以下是不进行 HTTP 编码时的查询： 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 参数以及最近搜索 URI 的查询： https://api.x.com/2/tweets/search/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。 下面是不进行 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 编码、查询参数以及 recent search URI 的示例： https://api.x.com/2/tweets/search/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/search/recent?query=%23nowplaying%20(horrible%20OR%20worst%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 注解相关的 Posts

此规则用于搜索包含宠物图片但不是猫的原始 Posts，且该 Post 的识别语言为日语。为此，我们使用了 context: 运算符来利用 Post annotation 功能。我们首先使用 Post lookup 端点和 tweet.fields=context_annotations fields 参数，来确定在查询中需要使用哪些 domain.entity ID：
  • 与猫相关的 Posts 会返回 domain 66（Interests and Hobbies 类别）以及 entity 852262932607926273（Cats）。
  • 与宠物相关的 Posts 会返回 domain 65（Interests and Hobbies Vertical）以及 entity 852262932607926273（Pets）。
以下是不进行 HTTP 编码时的查询： context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja 下面是带有 HTTP 编码、查询参数以及近期搜索 URI 的查询示例： https://api.x.com/2/tweets/search/recent?query=context%3A65.852262932607926273%20-context%3A66.852262932607926273%20-is%3Aretweet%20has%3Aimages%20lang%3Aja 尝试使用 query builder tool 获取更多支持。