如何获取 X 全球趋势推文

趋势词只能告诉你“现在大家在聊什么”，但不能告诉你这个话题是谁带起来、哪些帖子正在扩散、互动是否来自自然讨论还是推广内容。做监控、选题或市场研究时，真正可用的是推文对象，而不是一串热搜词。

TwexAPI 的 Global Trending Tweets 流程更适合按采集链路来理解：先用国家、主题和内容标签端点取得官方支持的筛选项，再拉取某个细分范围里的趋势推文。这样参数不会靠猜，返回数据也能直接进入告警、BI 看板、LLM 摘要或社交研究流程。

这类结果应该被当作带筛选条件的趋势上下文，而不是“全站所有讨论”的完整记录。每次抓取都要保存 country、topic、content、count 和时间，后续分析才知道数据来自哪个范围。

接口链路

先发现可用筛选项，再请求趋势推文对象。实际开发时按下面顺序调用接口，不要手写不存在的国家、主题或内容标签：

所有请求都使用 Bearer Token：

Authorization: Bearer <your_token>

官方接口文档：

• Get Global Trending Countries
• Get Global Trending Topics
• Get Global Trending Contents
• Get Global Trending Tweets

Global Trending Tweets API

最终取数端点是 /twitter/global-trending/tweets。它只强制要求 country；当你已经选择主题或内容标签时，再传 topic、content 缩小范围；count 控制返回数量，范围是 1 到 100，默认 20。

如果只是做国家级趋势观察，可以只传 country。如果要监控娱乐、金融、体育或活动话题，先从 topics 和 contents 取出白名单值，再调用这个端点，后续排查会少很多。

GET https://api.twexapi.io/twitter/global-trending/tweets?country=Japan&topic=Entertainment&content=Music&count=50

Authorization: Bearer <your_token>

查询参数

建议缓存 countries 和 topics，刷新频率按业务新鲜度设置，比如每小时或每天一次。contents 依赖所选的 country + topic，适合在用户切换筛选条件时，或调度任务新增细分范围时再获取。

JavaScript 与 Python 示例

下面的示例适合做服务端采集脚本的起点：先读取筛选项，再选择 country + topic + content，最后调用 /tweets。生产环境里请把 Token 放在服务端环境变量中，不要暴露到浏览器客户端。

响应结构

/twitter/global-trending/tweets 返回标准响应对象：顶层包含 code、msg 和 data，其中 data 是推文数组。建议同时保存原始 JSON 和一份规范化后的表结构，方便后续字段变化时重新解析。

1{
2  "code": 200,
3  "msg": "success",
4  "data": [
5    {
6      "tweet_id": "1803006263529541838",
7      "text": "Example trending tweet text",
8      "created_at_datetime": "2024-06-17T03:51:48.000Z",
9      "lang": "en",
10      "favorite_count": 123,
11      "retweet_count": 45,
12      "reply_count": 12,
13      "quote_count": 3,
14      "view_count": "10000",
15      "is_paid_promotion": false,
16      "hashtags": ["AI"],
17      "cashtags": ["$TSLA"],
18      "urls": ["https://example.com"],
19      "media": [],
20      "user": {
21        "id": "1717001045992251392",
22        "name": "Example User",
23        "screen_name": "example"
24      }
25    }
26  ]
27}

常用字段可以按用途分组：

构建趋势推文监控器

趋势推文监控器的核心，是把同一组 country + topic + content 定时抓取、去重、评分并写入告警或看板。一个实用版本通常分成四层：

1. 发现层：定时同步 countries 与 topics，保存可选项。
2. 筛选层：根据业务关注的国家、主题和内容标签生成请求队列。
3. 采集层：调用 /tweets，把 tweet_id 作为幂等键写入数据库。
4. 分析层：计算热度分、语言分布、媒体占比、品牌提及和异常增长。

下面是一个简单的热度评分函数：

function trendingScore(tweet) {
  const likes = Number(tweet.favorite_count || 0);
  const reposts = Number(tweet.retweet_count || 0);
  const replies = Number(tweet.reply_count || 0);
  const quotes = Number(tweet.quote_count || 0);
  const views = Number(tweet.view_count || 0);

  return likes + reposts * 2 + replies * 1.5 + quotes * 2.5 + Math.log10(views + 1) * 10;
}

如果你要做实时告警，把同一个 country + topic + content 的结果按时间窗口保存，并把 country、topic、content、count、fetched_at 写到每条记录旁边。这样你可以比较最近两次抓取的新增推文数、平均互动量、Top 作者变化和推广内容占比。

错误处理建议

把参数、鉴权和空结果分开处理，不要把所有失败都当成网络错误重试。实现时重点处理三类问题：

• 422 参数错误：通常是 country、topic 或 content 没有使用官方返回的可用值。先调用选项端点，不要手写不存在的标签。
• 401/403 鉴权错误：检查 Bearer Token 是否过期、是否带了 Authorization 请求头、是否误把 Token 放进客户端代码。
• 空结果：某些国家、主题或内容标签组合可能暂时没有趋势推文。把空数组视为正常状态，而不是系统错误。

count 建议在客户端或服务端都做一次保护，限制在 1 到 100 之间，避免用户输入导致无效请求。

适合放在哪些流程里

它适合放进那些需要知道“是谁推动了趋势”而不只是“趋势词是什么”的系统。常见场景包括：

• 新闻与舆情监控：看清某个国家级话题是被哪些推文带起来的，而不只是知道话题存在。
• 品牌与竞品追踪：观察产品、公司或行业词如何出现在趋势讨论中。
• 内容选题：把高热度推文交给编辑或 LLM 摘要系统，提炼值得跟进的角度。
• 投放与活动分析：结合 is_paid_promotion 和互动指标，区分自然讨论与商业信号。
• 金融与加密监控：跨地区追踪 cashtags、项目名、交易所和政策相关讨论。

落地注意事项

上线前要先固定数据边界和防错规则，尤其是筛选项白名单、去重键和抓取上下文。

1. 先缓存 countries 与 topics，再按需查询 contents。
2. 用 tweet_id 去重，避免重复写入同一条趋势推文。
3. 保存原始 JSON，后续字段变化时可以重新解析。
4. 为每次请求记录 country、topic、content、count 和抓取时间。
5. 对用户生成的筛选条件做白名单校验，只允许官方选项端点返回的值。

小结

把 Global Trending Tweets 当成一条采集链路，而不是单个 API 调用：先发现有效筛选项，再抓取推文对象，用 tweet_id 去重，并为每次抓取保存 country、topic、content、count 和时间。这样后续才能按国家、主题、内容标签、作者、媒体、语言、互动和推广信号做对比。

建议先从一个国家和一个主题开始。等字段、评分规则和告警阈值都能帮上忙，再把调度任务扩展到更多细分范围。