twitter-search

Twitter 検索と分析

概要

高度な検索構文を使って Twitter でキーワードを検索し、関連するツイートを最大 1000 件取得します。データを分析して、知見、統計、実行可能な推奨事項を含む専門的なレポートを作成します。

前提条件

API キーが必要です：https://twitterapi.io から Twitter API キーを設定する必要があります。

API キーは次の 3 つの方法で指定できます。

1. 環境変数（推奨）：~/.bashrc または ~/.zshrc に TWITTER_API_KEY を設定します。

   echo 'export TWITTER_API_KEY="your_key_here"' >> ~/.bashrc
   source ~/.bashrc
   

2. 引数として指定：ラッパースクリプトで --api-key YOUR_KEY を使用します。
3. 直接渡す：Python スクリプトの第 1 引数として渡します。

クイックスタート

ラッパースクリプトを使用する（推奨）

ラッパースクリプトは、環境変数の読み込みと依存関係の確認を自動的に処理します。

# Basic search (uses TWITTER_API_KEY from shell config)
./scripts/run_search.sh "AI"

# With custom API key
./scripts/run_search.sh "AI" --api-key YOUR_KEY

# With options
./scripts/run_search.sh "\"Claude AI\"" --max-results 100 --format summary

# Advanced query
./scripts/run_search.sh "from:elonmusk since:2024-01-01" --query-type Latest

Python スクリプトを直接使用する

# Search for a keyword
scripts/twitter_search.py "$API_KEY" "AI"

# Search with multiple keywords
scripts/twitter_search.py "$API_KEY" "\"ChatGPT\" OR \"Claude AI\""

# Search from specific user
scripts/twitter_search.py "$API_KEY" "from:elonmusk"

# Search with date range
scripts/twitter_search.py "$API_KEY" "Bitcoin since:2024-01-01"

高度なクエリ

# Complex query: AI tweets from verified users, English only
scripts/twitter_search.py "$API_KEY" "AI OR \"machine learning\" lang:en filter:verified"

# Recent crypto tweets with minimum engagement
scripts/twitter_search.py "$API_KEY" "Bitcoin min_retweets:10 lang:en"

# From specific influencers
scripts/twitter_search.py "$API_KEY" "from:elonmusk OR from:VitalikButerin since:2024-01-01"

出力形式

# Full JSON with all tweets
scripts/twitter_search.py "$API_KEY" "AI" --format json

# Summary with statistics (default)
scripts/twitter_search.py "$API_KEY" "AI" --format summary

オプション

• --max-results N：取得するツイートの最大数（デフォルト：1000）
• --query-type Latest|Top：並べ替え順（デフォルト：関連性を優先する Top）
• --format json|summary：出力形式（デフォルト：summary）

ワークフロー

1. ユーザーの要件を把握する

分析の目標を明確にします。

• 検索するトピック／キーワードは何ですか？
• 希望する日付範囲はありますか？
• 対象に含める、または除外する特定のユーザーはいますか？
• 希望する言語はありますか？
• 必要なインサイトの種類は何ですか（トレンド、センチメント、インフルエンサーなど）？

2. 検索クエリを作成する

Twitter Advanced Search の構文を使用します。

構文	例	説明
keyword	AI	単一のキーワード
"phrase"	"machine learning"	完全一致するフレーズ
OR	AI OR ChatGPT	いずれかの語句
from:user	from:elonmusk	特定のユーザーからの投稿
to:user	to:elonmusk	ユーザーへの返信
since:DATE	since:2024-01-01	指定日以降
until:DATE	until:2024-12-31	指定日より前
lang:xx	lang:en	言語コード
#hashtag	#AI	ハッシュタグ
filter:links	filter:links	リンクを含むツイート
min_retweets:N	min_retweets:100	リツイートの最小数

3. データを取得する

検索スクリプトを実行します。

scripts/twitter_search.py "$API_KEY" "YOUR_QUERY" --max-results 1000 --query-type Top

重要：デフォルトの取得上限は 1000 件です。スクリプトは自動的に次の処理を行います。

• 利用可能なすべての結果をページネーションで取得します。
• 1000 件で停止します（API の上限を考慮）。
• エラーを適切に処理します。

4. 分析してレポートを作成する

データの取得後、次の内容を含む包括的で専門的なレポートを作成します。

レポートの構成

1. エグゼクティブサマリー（2～3 文）

   • 検索した内容
   • 主な調査結果の概要

2. データの概要

   • 分析したツイートの合計数
   • データの日付範囲
   • 使用したクエリのパラメーター

3. 主要指標

   • エンゲージメントの合計（いいね、リツイート、返信、引用、表示回数）
   • ツイートあたりの平均エンゲージメント
   • 言語の分布
   • 返信とオリジナルツイートの比率

4. 人気コンテンツの分析

   • リツイート数が最も多いツイート（元のツイートへのURL リンク付き）
   • いいね数が最も多いツイート（元のツイートへのURL リンク付き）
   • 頻度別の人気ハッシュタグ
   • 最も多く言及されたユーザー
   • 完全な URL 参照を付けたツイートの例

5. インフルエンサー分析

   • フォロワー数上位のユーザー
   • 最もアクティブなユーザー
   • 認証済みユーザーの割合

6. トレンドに関するインサイト（データのパターンに基づく）

   • 新たに浮上しているテーマ
   • センチメントの指標
   • 時間的なパターン
   • 会話を促進する要因

7. 主な要点

   • 中核となるインサイトを 3～5 個、箇条書きで記載
   • データに基づく結論

8. 実行可能な推奨事項

   • 具体的で実行可能な提案
   • データから得られた調査結果に基づく内容
   • 影響度の高い順に優先順位を付ける

分析ガイドライン

• データに基づく：すべての主張で実際の指標を参照します
• 背景を説明する：指標が重要な理由を説明します
• パターンを特定する：データセット全体の傾向を探します
• 客観性を保つ：事実を提示し、憶測を避けます
• 具体的にする：推奨事項は具体的で実行可能なものにします
• 外部の背景情報を考慮する：関連する場合はウェブ検索を利用します

5. 出力形式

次の要素を含む、明確な Markdown 形式でレポートを提示します。

• 各セクションの見出し
• 構造化データの表
• リストの箇条書き
• 主要な指標の太字表記
• ツイートの例を示すコードブロック
• 参照するすべてのツイートのクリック可能な URL（形式：[@username](https://x.com/username/status/tweet_id)）

ツイートの URL 形式

ツイートへのクリック可能なリンクを必ず含めます。

| Author | Tweet | URL |
|--------|-------|-----|
| @user | Summary of tweet content | [View](https://x.com/user/status/123456) |

またはインライン形式：

- **@username**: Tweet summary - [View Tweet](https://x.com/username/status/123456)

ユースケース別のクエリ例

トレンド分析

"AI" OR "artificial intelligence" lang:en min_retweets:50

競合モニタリング

from:competitor1 OR from:competitor2 since:2024-01-01

製品ローンチの追跡

#ProductName OR "Product Name" lang:en filter:verified

危機モニタリング

#BrandName OR "Brand Name" lang:en --query-type Latest

インフルエンサーの発見

#Topic lang:en min_retweets:100 min_faves:500

感情分析

"brand name" OR #BrandName lang:en --max-results 1000

リソース

scripts/run_search.sh（ラッパースクリプト）

環境変数の読み込みや依存関係の確認を処理する便利なラッパーです。

• ~/.bashrc または ~/.zshrc から TWITTER_API_KEY を自動的に読み込みます
• Python が利用可能か確認し、不足している依存関係をインストールします
• わかりやすいエラーメッセージを表示します
• Python スクリプトのすべてのコマンドラインオプションに対応しています

使用方法：

./scripts/run_search.sh <query> [options]

オプション：

• --api-key KEY：環境変数の API キーを上書きします
• --max-results N：取得するツイートの最大数（デフォルト：1000）
• --query-type Latest|Top：並べ替え順（デフォルト：Top）
• --format json|summary：出力形式（デフォルト：json）

scripts/twitter_search.py

次の機能を備えた実行可能な Python スクリプトです。

• Twitter API からツイートを取得します
• ページネーションを自動的に処理します
• ツイートの主要な指標を抽出します
• 集計統計を計算します
• 構造化された JSON データを出力します

使用方法：

scripts/twitter_search.py <api_key> <query> [options]

references/twitter_api.md

次の内容を含む包括的な API ドキュメントです。

• パラメーターの完全なリファレンス
• クエリ構文ガイド
• レスポンス構造の詳細
• ページネーションの手順
• 分析のベストプラクティス
• エラー処理ガイド

次の場合に参照してください：複雑なクエリを作成する場合や、データ構造を理解する場合。

より良い分析のためのヒント

1. トレンド分析には Top クエリタイプを使用する（より関連性の高い結果が得られます）
2. 日付フィルターを設定すると、タイムリーな分析情報を得られます
3. 言語でフィルタリングすると、テキストを正確に分析できます
4. 最低エンゲージメント数を指定すると、ノイズを除外できます
5. ウェブ検索と組み合わせると、トレンドを検証できます
6. 指標だけでなく、コンテンツのテーマも分析します
7. ハッシュタグを追跡すると、関連する会話を特定できます
8. フォロワー数とエンゲージメントを組み合わせてインフルエンサーを特定します

エラー処理

スクリプトが失敗した場合：

• API キーが有効か確認します
• クエリ構文を確認します
• ネットワーク接続を確認します
• レート制限を確認します（該当する場合）
• エラーメッセージを確認して、具体的な問題を特定します