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

必须在环境变量或 .env 文件中设置 APIFY_TOKEN。

如果 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 后重试。 **大型请求超时：**将每次运行的 maxItems 设为最高 500；如需更大的数据集，按日期范围分批运行。