scraping-tweets-by-keyword

キーワードでツイートをスクレイピング

任意のキーワード、ハッシュタグ、ブール検索クエリを使ってツイートを生の状態で収集します。想定されるユースケースはありません。後続の分析で利用できるツイートデータセット全体を返します。

前提条件

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

入力

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

ワークフロー

Progress:
- [ ] Step 1: Build search query string
- [ ] Step 2: Run tweet-scraper
- [ ] Step 3: Poll for SUCCEEDED
- [ ] Step 4: Fetch and deliver dataset

ステップ 1：検索クエリを作成する

• ハッシュタグ検索 → #keyword
• 完全一致フレーズ → "exact phrase"
• ブール検索 → word1 AND word2 -exclude
• アカウント指定 → from:username
• メンション → @username

ステップ 2：Actor を実行する

推奨 — 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": ["<query>"],
  "maxItems": 200,
  "since": "<YYYY-MM-DD>",
  "lang": "<lang_code>"
}

REST API を使う場合：

curl -X POST \
  "https://api.apify.com/v2/acts/apidojo~tweet-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms": ["<query>"], "maxItems": 200}'

id を RUN_ID として保存します。status = SUCCEEDED になるまでポーリングします：

curl "https://api.apify.com/v2/actor-runs/$RUN_ID?token=$APIFY_TOKEN" | grep '"status"'

結果を取得します：

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

ステップ 3：エッジケースに対処する

• 結果が 0 件：クエリが絞り込みすぎている、スペルミスがある、または言語でフィルタリングされている可能性があります。検索語を広げ、言語フィルターを削除し、日付範囲を広げてください。
• 結果が 20 件未満：since／until の制約を削除してみてください。検索ボリュームが少ない語句では、データがまばらな場合があります。
• ツイート ID の重複：返す前に id フィールドを使って重複を除去してください。
• 凍結／削除されたアカウント：凍結されたアカウントのツイートは、投稿者フィールドが空の状態で返されます。これらの行にフラグを付けてください。

出力形式

# Tweet Dataset: "<query>"
Total collected: N | Date range: SINCE – UNTIL | Language: LANG

| Tweet ID | Author | Text (truncated) | Likes | Retweets | Replies | Timestamp |
|----------|--------|-----------------|-------|----------|---------|-----------|
| ...      | ...    | ...             | ...   | ...      | ...     | ...       |

Full dataset: N rows × 15 fields
Available fields: id, text, author_id, author_username, likeCount, retweetCount,
replyCount, quoteCount, lang, createdAt, tweetUrl, media, isRetweet, isQuote, source

トラブルシューティング

有効なハッシュタグなのに結果が空の場合： Twitter API のインデックス反映に遅延がある可能性があります。15 分後にもう一度試してください。 レート制限エラー： maxItems を 100 に減らして再試行してください。 大きなリクエストがタイムアウトする場合： 1 回の実行につき maxItems: 500 を上限に設定し、より大きなデータセットの場合は日付範囲を指定して複数回実行してください。