国別に X のトレンドトピックを取得する方法
Trending topics は、X がある地域で今何を強調しているかを素早く見るために役立ちます。完全な世論データではなく、単体で長期的な sentiment として扱うべきものでもありません。価値は即時性にあります。Dashboard、newsroom、content team、alerting system が、今動いている話題に気づくための signal です。
TwexAPI では GET /twitter/{country}/trending でこの workflow を実装できます。worldwide は default global-style trends、united-states、japan、united-kingdom などは supported country slug です。
API エンドポイント
GET https://api.twexapi.io/twitter/{country}/trending
Authorization: Bearer <your_token>Path parameter：
| Parameter | 説明 |
|---|---|
country | worldwide または supported country slug。例：united-states、japan、france、india、brazil |
Request example：
curl --request GET \
--url https://api.twexapi.io/twitter/united-states/trending \
--header 'Authorization: Bearer <your_token>'他の地域も同じ endpoint を使います。
/twitter/worldwide/trending
/twitter/japan/trending
/twitter/united-kingdom/trending
/twitter/brazil/trending保存すべきフィールド
Response は code、msg、data を含む TwexAPI standard wrapper です。data の items が、選択した country の current trend list です。
Repeatable analysis では、最新 response を読むだけでなく snapshot として保存します。
| Field | 理由 |
|---|---|
country | regional comparison ができる |
fetched_at | volatile trend list を time series にできる |
name | human-readable trend text |
query / url | search や follow-up collection に使える |
tweet_volume | 利用可能なら参考になるが、missing や approximate のことがある |
| raw item | 後から使う field を保持できる |
Trend list はすぐ変わります。fetched_at がない trend row は、すぐ context を失います。
Python Snapshot Script
次の script は 1 country の trend list を取得し、JSONL file に append します。各 line には country、fetch time、raw trend object を保存します。
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複数国を監視する
小さな regional dashboard を作る場合、country list は明示的な config にします。
countries = ["worldwide", "united-states", "japan", "united-kingdom"]
for country in countries:
trends = fetch_trends(country)
print(country, len(trends))Scheduled jobs では、country ごとに保存し、fetched_at で snapshots を比較します。これにより次の問いに答えやすくなります。
- 複数国に同時に出た topics は何か？
- 1 snapshot だけで消えた trends は何か？
- local から global に広がった topics は何か？
- follow-up search export すべき topics は何か？
Trend Topics と Trending Tweets の違い
この endpoint は topic list を返します。Dashboard、alerts、editorial planning に向いています。
Trend category 内の tweets が必要な場合は、global trending tweet workflow を使います。その workflow では /twitter/global-trending/countries、/twitter/global-trending/topics、/twitter/global-trending/tweets を使います。
2 つの job は分けてください。Trend topics は何を見るべきかを示し、trending tweets は分析する posts を返します。
本番運用の注意点
- Country choices は scripts に散らさず config に置く。
- Debug と future field changes のため raw responses を保存する。
tweet_volumeは missing になることがあるため schema で必須にしない。- Timestamps は UTC に統一する。
- Trend data は discovery signal として使い、証拠が必要な場合は search や tweet export workflow で収集する。