如何按国家获取 X 热门话题

热门话题适合快速了解 X 在某个地区正在突出展示什么。它不是完整的舆情数据，也不应该单独当作长期情绪判断。它的价值在于即时性：帮助看板、新闻团队、内容团队和告警系统发现当前正在移动的话题。

TwexAPI 通过 GET /twitter/{country}/trending 提供这个能力。使用 worldwide 获取默认全球趋势，或使用支持的国家 slug，例如 united-states、japan、united-kingdom。

API 端点

GET https://api.twexapi.io/twitter/{country}/trending

Authorization: Bearer <your_token>

路径参数：

参数	说明
`country`	`worldwide` 或支持的国家 slug，例如 `united-states`、`japan`、`france`、`india`、`brazil`

请求示例：

curl --request GET \
  --url https://api.twexapi.io/twitter/united-states/trending \
  --header 'Authorization: Bearer <your_token>'

其他地区也使用同一端点：

/twitter/worldwide/trending
/twitter/japan/trending
/twitter/united-kingdom/trending
/twitter/brazil/trending

应保存哪些字段

响应使用 TwexAPI 标准结构，包含 code、msg 和 data。data 中的条目代表所选国家当前的趋势列表。

如果要做可复盘分析，请保存快照，而不是只读取最新响应：

字段	为什么重要
`country`	支持地区对比
`fetched_at`	把易变的趋势列表变成时间序列
`name`	人可读的话题文本
`query` / `url`	方便跳转搜索或后续采集
`tweet_volume`	可用时有参考价值，但可能为空或近似
raw item	保留以后可能需要的字段

趋势变化很快。如果没有 fetched_at，单条趋势记录很快就失去上下文。

Python 快照脚本

下面的脚本获取一个国家的趋势，并追加写入 JSONL 文件。每一行包含国家、抓取时间和原始 trend 对象。

1import json
2import os
3from datetime import datetime, timezone
4
5import requests
6
7API_BASE = "https://api.twexapi.io"
8TOKEN = os.environ["TWEXAPI_TOKEN"]
9COUNTRY = "united-states"
10OUTPUT_PATH = "trending-topics.jsonl"
11
12def fetch_trends(country: str) -> list:
13    response = requests.get(
14        f"{API_BASE}/twitter/{country}/trending",
15        headers={"Authorization": f"Bearer {TOKEN}"},
16        timeout=30,
17    )
18    response.raise_for_status()
19
20    payload = response.json()
21    if payload.get("code") not in (None, 200):
22        raise RuntimeError(payload.get("msg", "TwexAPI request failed"))
23
24    return payload.get("data") or []
25
26fetched_at = datetime.now(timezone.utc).isoformat()
27trends = fetch_trends(COUNTRY)
28
29with open(OUTPUT_PATH, "a", encoding="utf-8") as output:
30    for trend in trends:
31        output.write(
32            json.dumps(
33                {
34                    "country": COUNTRY,
35                    "fetched_at": fetched_at,
36                    "trend": trend,
37                },
38                ensure_ascii=False,
39            )
40            + "\n"
41        )
42
43print(f"Saved {len(trends)} trends for {COUNTRY} at {fetched_at}")

运行方式：

TWEXAPI_TOKEN="your_twexapi_bearer_token" python save-trending-topics.py

监控多个国家

如果要做一个小型地区趋势看板，建议把国家列表显式写在配置里：

countries = ["worldwide", "united-states", "japan", "united-kingdom"]

for country in countries:
    trends = fetch_trends(country)
    print(country, len(trends))

做定时任务时，请按国家分别保存，并用 fetched_at 比较快照。这样更容易回答：

哪些话题同时出现在多个国家？
哪些趋势只出现了一次就消失？
哪些话题从本地扩散到全球？
哪些话题值得继续做搜索导出？

生产环境注意事项

把国家选项放进配置，不要散落在多个脚本里。
保存原始响应，方便排查和适配字段变化。
不要把 tweet_volume 设为必填；它可能缺失。
时间戳统一使用 UTC。
把趋势数据当作发现信号，再用搜索或推文导出工作流收集证据。

如何按国家获取 X 热门话题

API 端点

GET https://api.twexapi.io/twitter/{country}/trending

Authorization: Bearer <your_token>

路径参数：

参数	说明
`country`	`worldwide` 或支持的国家 slug，例如 `united-states`、`japan`、`france`、`india`、`brazil`

请求示例：

curl --request GET \
  --url https://api.twexapi.io/twitter/united-states/trending \
  --header 'Authorization: Bearer <your_token>'

其他地区也使用同一端点：

/twitter/worldwide/trending
/twitter/japan/trending
/twitter/united-kingdom/trending
/twitter/brazil/trending

应保存哪些字段

响应使用 TwexAPI 标准结构，包含 code、msg 和 data。data 中的条目代表所选国家当前的趋势列表。

如果要做可复盘分析，请保存快照，而不是只读取最新响应：

字段	为什么重要
`country`	支持地区对比
`fetched_at`	把易变的趋势列表变成时间序列
`name`	人可读的话题文本
`query` / `url`	方便跳转搜索或后续采集
`tweet_volume`	可用时有参考价值，但可能为空或近似
raw item	保留以后可能需要的字段

趋势变化很快。如果没有 fetched_at，单条趋势记录很快就失去上下文。

Python 快照脚本

下面的脚本获取一个国家的趋势，并追加写入 JSONL 文件。每一行包含国家、抓取时间和原始 trend 对象。

1import json
2import os
3from datetime import datetime, timezone
4
5import requests
6
7API_BASE = "https://api.twexapi.io"
8TOKEN = os.environ["TWEXAPI_TOKEN"]
9COUNTRY = "united-states"
10OUTPUT_PATH = "trending-topics.jsonl"
11
12def fetch_trends(country: str) -> list:
13    response = requests.get(
14        f"{API_BASE}/twitter/{country}/trending",
15        headers={"Authorization": f"Bearer {TOKEN}"},
16        timeout=30,
17    )
18    response.raise_for_status()
19
20    payload = response.json()
21    if payload.get("code") not in (None, 200):
22        raise RuntimeError(payload.get("msg", "TwexAPI request failed"))
23
24    return payload.get("data") or []
25
26fetched_at = datetime.now(timezone.utc).isoformat()
27trends = fetch_trends(COUNTRY)
28
29with open(OUTPUT_PATH, "a", encoding="utf-8") as output:
30    for trend in trends:
31        output.write(
32            json.dumps(
33                {
34                    "country": COUNTRY,
35                    "fetched_at": fetched_at,
36                    "trend": trend,
37                },
38                ensure_ascii=False,
39            )
40            + "\n"
41        )
42
43print(f"Saved {len(trends)} trends for {COUNTRY} at {fetched_at}")

运行方式：

TWEXAPI_TOKEN="your_twexapi_bearer_token" python save-trending-topics.py

监控多个国家

如果要做一个小型地区趋势看板，建议把国家列表显式写在配置里：

countries = ["worldwide", "united-states", "japan", "united-kingdom"]

for country in countries:
    trends = fetch_trends(country)
    print(country, len(trends))

做定时任务时，请按国家分别保存，并用 fetched_at 比较快照。这样更容易回答：

哪些话题同时出现在多个国家？
哪些趋势只出现了一次就消失？
哪些话题从本地扩散到全球？
哪些话题值得继续做搜索导出？

生产环境注意事项

把国家选项放进配置，不要散落在多个脚本里。
保存原始响应，方便排查和适配字段变化。
不要把 tweet_volume 设为必填；它可能缺失。
时间戳统一使用 UTC。
把趋势数据当作发现信号，再用搜索或推文导出工作流收集证据。

如何按国家获取 X 热门话题

如何按国家获取 X 热门话题

API 端点

应保存哪些字段

Python 快照脚本

监控多个国家

热门话题与趋势推文的区别

生产环境注意事项

相关资源

如何按国家获取 X 热门话题

如何按国家获取 X 热门话题

API 端点

应保存哪些字段

Python 快照脚本

监控多个国家

热门话题与趋势推文的区别

生产环境注意事项

相关资源