X のグローバルトレンドツイートを取得する方法

トレンド名だけでは、監視には情報が足りないことがあります。話題が伸びているなら、その裏でどの投稿が広がっているのか、誰が投稿しているのか、どの言語やリンク、メディアが使われているのかまで見たいはずです。

TwexAPI の Global Trending Tweets ワークフローは、トレンドラベルから投稿オブジェクトへ進むための流れです。対応している国、トピック、コンテンツタグを取得し、選んだセグメントでトレンド投稿を取得します。結果はアラート、BI ダッシュボード、LLM 要約、編集企画、ソーシャル分析に使えます。

この結果は、X 全体の完全な会話記録ではなく、選択した条件に基づくトレンド文脈として扱います。後から説明できるように、各クロールの country、topic、content、count、取得時刻を一緒に保存してください。

API の流れ

TwexAPI は、選択肢の取得と投稿データの取得を分けています。本番環境では、国、トピック、コンテンツタグを手書きせず、次の順番で呼び出してください。

すべてのリクエストは Bearer Token 認証を使います。

Authorization: Bearer <your_token>

公式 API リファレンス:

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

Global Trending Tweets API

/twitter/global-trending/tweets は最終的に投稿データを取得する API です。country は必須で、任意で topic、content、count を指定できます。

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

Authorization: Bearer <your_token>

クエリパラメータ

まず countries と topics をキャッシュします。例えば 1 時間ごとに更新します。contents は選択された country + topic に依存するため、ユーザーがフィルタを変えたときや、スケジュールジョブが新しいセグメントを処理するときに取得します。

JavaScript と Python の例

以下の例では、国、トピック、コンテンツタグを取得してから、トレンド投稿を取得します。本番環境では Token をサーバー側の環境変数に保存し、ブラウザ側に公開しないでください。

レスポンス構造

/twitter/global-trending/tweets は標準レスポンスを返し、data が投稿配列になります。

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}

よく使うフィールドは目的別に整理できます。

トレンド投稿モニターを作る

実用的なトレンド投稿モニターは、通常 4 つのレイヤーに分かれます。

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 ごとの取得結果を時間窓で保存し、最新クロールと前回クロールを比較します。新規投稿数、平均エンゲージメントの変化、上位投稿者の変化が有用なシグナルになります。

エラーハンドリング

主に 3 種類のケースを処理します。

• 422 バリデーションエラー: 多くの場合、country、topic、content に公式オプション API が返していない値を使っています。ラベルを手書きせず、先に有効な選択肢を取得してください。
• 401/403 認証エラー: Bearer Token が有効か、Authorization ヘッダーが付いているか、Token をクライアント側コードで使っていないか確認します。
• 空の結果: 国、トピック、コンテンツタグの組み合わせによっては、一時的にトレンド投稿がない場合があります。空配列はシステム障害ではなく通常の結果として扱います。

count はクライアント側とサーバー側の両方で 1 から 100 に制限し、ユーザー入力による無効リクエストを避けます。

どこで使えるか

• ニュースと世論監視: ある国で伸びている話題を、どの投稿が支えているかまで確認できます。
• ブランドと競合追跡: 製品、会社、カテゴリ名がトレンド会話にどう出てくるかを追えます。
• 編集企画: 上位投稿を編集チームや LLM 要約に渡し、次に扱う切り口を見つけます。
• 広告とキャンペーン分析: is_paid_promotion とエンゲージメントを組み合わせ、自然な会話と商業シグナルを分けて見ます。
• 金融と暗号資産モニタリング: cashtags、プロジェクト名、取引所、政策関連の話題を地域別に追跡します。

実装時の注意点

1. contents を問い合わせる前に、countries と topics をキャッシュします。
2. 書き込み前に tweet_id で重複排除します。
3. 後から再解析できるように、元の JSON を保存します。
4. 各リクエストの country、topic、content、count、取得時刻を記録します。
5. ユーザー入力のフィルタは、オプション API が返した値と照合します。

小まとめ

Global Trending Tweets は、1 回だけ呼ぶ API というより、収集パイプラインとして使うと効果が出ます。有効なフィルタを取得し、投稿オブジェクトを集め、tweet_id で重複排除し、各クロールの country、topic、content、count、取得時刻を保存します。そうすると、国、トピック、コンテンツタグ、投稿者、メディア、言語、エンゲージメント、広告シグナルを時系列で比較できます。

まずは 1 つの国と 1 つのトピックで検証してください。フィールド、スコアリング、アラート閾値が実務に使えると分かったら、スケジューラーをより多くのセグメントへ広げます。