monitoring-brand-mentions-on-twitter

Twitterでのブランドへの言及をモニタリングする

指定した期間内に、Twitter/Xでブランド、製品、またはキーワードに言及したすべての公開ツイートを収集します。感情別にグループ化し、主な苦情や称賛を抽出して、エンゲージメントの合計を提示します。

前提条件

• APIFY_TOKEN 環境変数が設定されていること
• 任意：Apify MCP サーバーがインストールされていること

入力

パラメーター	型	必須	デフォルト	備考
searchTerms	配列	✅	[]	Twitterの高度な検索クエリ（例：["#AI lang:en", "from:NASA"]）
sort	文字列	任意	Top	並べ替え順：Latest、Top、または Latest+Top
tweetLanguage	文字列	任意	—	ISO 639-1言語コード（例：en）
maxItems	数値	任意	無制限	返すツイートの最大数
onlyVerifiedUsers	ブール値	任意	false	認証済みユーザーのツイートのみ
onlyTwitterBlue	ブール値	任意	false	Twitter Blue登録者のツイートのみ
onlyImage	ブール値	任意	false	画像付きのツイートのみ
onlyVideo	ブール値	任意	false	動画付きのツイートのみ
onlyQuote	ブール値	任意	false	引用ツイートのみ
author	文字列	任意	—	特定のユーザー名に絞り込み
inReplyTo	文字列	任意	—	特定のユーザー名への返信ツイート
mentioning	文字列	任意	—	特定のユーザー名に言及したツイート
geotaggedNear	文字列	任意	—	特定の場所付近のツイート
withinRadius	文字列	任意	—	geotaggedNear の周囲の半径
geocode	文字列	任意	—	緯度・経度と半径を指定する文字列
placeObjectId	文字列	任意	—	場所がタグ付けされたツイート
minimumRetweets	数値	任意	—	リツイート数の最小値
minimumFavorites	数値	任意	—	いいね数の最小値
minimumReplies	数値	任意	—	返信数の最小値
start	文字列	任意	—	この日付以降のツイート（YYYY-MM-DD）
end	文字列	任意	—	この日付より前のツイート（YYYY-MM-DD）
includeSearchTerms	ブール値	任意	false	一致した検索語を各ツイートに追加
customMapFunction	文字列	任意	—	各出力オブジェクトを変換するJavaScript関数

ワークフロー

Progress:
- [ ] Step 1: Define brand terms and date range
- [ ] Step 2: Run tweet-scraper
- [ ] Step 3: Retrieve dataset
- [ ] Step 4: Classify sentiment (positive/negative/neutral)
- [ ] Step 5: Deliver structured report

ステップ1：パラメーターを確認する

ユーザーに次の内容を尋ねます。

• ブランド関連語 — ブランド名、ユーザー名、製品名、ハッシュタグ、よくあるスペルミスを確認し、リストを作成します。 例：["@Nike", "Nike", "#Nike", "Nike shoes"]
• 期間 — 例：「過去7日間」または具体的な日付
• リツイートを除外するか？（デフォルト：はい — ノイズを除去します）
• エンゲージメントの最小値（任意 — 例：いいねが10件以上のツイートのみ）
• 言語（デフォルト：すべて）

ステップ2：tweet-scraperを実行する

カバー範囲を最大化するため、主要な検索語ごとに1回実行します。実行後に結果をまとめます。

推奨 — run_actor.js（待機、出力、ファイル保存を自動で処理します）：

# Quick answer (prints table to chat)
node scripts/run_actor.js \
  --actor "apidojo~tweet-scraper" \
  --input '{"param": "value"}'

# Save as CSV
node scripts/run_actor.js \
  --actor "apidojo~tweet-scraper" \
  --input '{"param": "value"}' \
  --output YYYY-MM-DD_results.csv --format csv

# Save as JSON
node scripts/run_actor.js \
  --actor "apidojo~tweet-scraper" \
  --input '{"param": "value"}' \
  --output YYYY-MM-DD_results.json --format json

APIFY_TOKEN は環境変数または .env ファイルに設定する必要があります。

Apify MCPが利用可能な場合：

Tool: apify:run-actor
Actor: "apidojo~tweet-scraper"
Input:
{
  "searchTerms": ["[BRAND_TERM]"],
  "maxItems": 500,
  "includeReplies": true,
  "tweetLanguage": "en",
  "since": "[YYYY-MM-DD]",
  "until": "[YYYY-MM-DD]"
}

Apify MCPが利用できない場合：

curl -X POST \
  "https://api.apify.com/v2/acts/apidojo~tweet-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchTerms": ["[BRAND_TERM]"],
    "maxItems": 500,
    "includeReplies": true,
    "since": "[YYYY-MM-DD]",
    "until": "[YYYY-MM-DD]"
  }'

リスト内のブランド関連語ごとに実行します。SUCCEEDED になるまで待機し、すべての結果を収集します。

ステップ3：結果を取得して統合する

curl "https://api.apify.com/v2/actor-runs/$RUN_ID/dataset/items?token=$APIFY_TOKEN"

すべての実行結果のデータセットを統合します。ツイートの id に基づいて重複を除外します。結果は、すべての言及をまとめた統一リストになります。

ステップ4：感情を分類する

各ツイートの text フィールドに対して、簡易的な分類を行います。

肯定的なシグナル：「love」、「great」、「amazing」、「best」、「recommend」、「thank」、「perfect」などの単語 否定的なシグナル：「hate」、「awful」、「broken」、「scam」、「worst」、「never again」、「disappointed」、「avoid」などの単語 **中立：**その他すべて（告知、ニュース、質問）

ツイートを肯定的、否定的、中立の3つのグループに分類します。

エンゲージメントが最も高い否定的なツイートを上位5件特定します（優先的に迅速な対応が必要です）。 エンゲージメントが最も高い肯定的なツイートを上位5件特定します（リツイート候補／お客様の声として活用できます）。

ステップ5：レポートを作成する

以下の出力テンプレートを使用します。

出力形式

# Brand Mention Report: [BRAND]
Period: [START_DATE] – [END_DATE] | Total mentions: [N] | Analyzed: [DATE]

## Sentiment Summary
| Sentiment | Count | % of Total | Avg Engagement |
|-----------|-------|------------|----------------|
| Positive  | [N]   | [X%]       | [likes+RT avg] |
| Negative  | [N]   | [X%]       | [likes+RT avg] |
| Neutral   | [N]   | [X%]       | [likes+RT avg] |

## 🔴 Top Negative Mentions (Action Required)
1. @[handle] ([likes] likes): "[tweet text excerpt]" → [url]
2. @[handle] ([likes] likes): "[tweet text excerpt]" → [url]
3. @[handle] ([likes] likes): "[tweet text excerpt]" → [url]

## 🟢 Top Positive Mentions (Amplify These)
1. @[handle] ([likes] likes): "[tweet text excerpt]" → [url]
2. @[handle] ([likes] likes): "[tweet text excerpt]" → [url]
3. @[handle] ([likes] likes): "[tweet text excerpt]" → [url]

## Volume Over Time
[Day 1]: [N] mentions | [Day 2]: [N] mentions | [Day 3]: [N] mentions...

## Key Themes in Negative Mentions
- [Theme 1]: [N] tweets (e.g., "shipping delays")
- [Theme 2]: [N] tweets (e.g., "customer service")

## Key Themes in Positive Mentions
- [Theme 1]: [N] tweets
- [Theme 2]: [N] tweets

トラブルシューティング

人気ブランドの検索結果が多すぎる場合： 影響力のある言及に絞り込むには、minLikes フィルターを 5 または 10 に増やしてください。 言及が見つからない場合： Twitter 検索 API の無料プランでは、検索可能な期間は約 7～10 日です。過去のデータを検索するには、日付範囲を短くしてください。 センチメントの誤分類： キーワードマッチングでは皮肉を検出しにくいため、エンゲージメントの高いツイートにフラグを付けて手動で確認してください。