scraping-tweets-by-keyword

用途

该技能用于按关键词抓取推文，针对任意关键词、话题标签、短语或布尔查询进行原始推文采集。技能本身不预设使用场景，而是返回完整推文数据集，供后续分析使用。

主要能力

• 支持关键词、话题标签、精确短语、布尔查询、from 账号、@提及等多种查询构建方式。
• 支持多种过滤条件：排序（Latest、Top、Latest+Top）、语言、最大条数、仅验证用户、仅 Twitter Blue 订阅者、仅含图片、仅含视频、仅引用推文、指定作者、回复对象、提及对象、地理定位、地点、最低转发数、最低点赞数、最低回复数、起止日期等。
• 可选择将匹配的搜索词附加到每条推文。
• 支持通过 JavaScript 自定义映射函数转换每条输出对象。
• 输出数据集包含 15 个字段：id、text、author_id、author_username、likeCount、retweetCount、replyCount、quoteCount、lang、createdAt、tweetUrl、media、isRetweet、isQuote、source。

使用方式

前置条件

• 设置 APIFY_TOKEN 环境变量。
• 可选：安装 Apify MCP 服务器。

工作流

分为四步：

1. 构建搜索查询：话题标签使用 #keyword；精确短语使用 "exact phrase"；布尔查询使用 word1 AND word2 -exclude；来自账号使用 from:username；提及使用 @username。
2. 运行 actor：推荐使用 run_actor.js，可自动处理等待、输出与文件保存。
3. 轮询直至 SUCCEEDED。
4. 获取并交付数据集。

运行示例

# 快速回答（在聊天中打印表格）
node scripts/run_actor.js \
  --actor "apidojo~tweet-scraper" \
  --input '{"param": "value"}'

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

# 保存为 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"

输入参数

参数	类型	必填	默认	说明
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	否	—	指定作者 handle
inReplyTo	string	否	—	回复指定 handle 的推文
mentioning	string	否	—	提及指定 handle 的推文
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 函数

适用场景

适用于需要原始推文数据的场景，返回完整数据集供下游分析，不限定具体用途。

限制与边界情况

• 0 结果：查询可能过窄、拼写错误或受语言过滤限制。可放宽关键词、移除语言过滤、延长日期范围。
• 少于 20 结果：尝试移除 since/until 约束。部分低量词数据稀疏。
• 重复推文 ID：交付前按 id 字段去重。
• 封禁/删除账号：来自封禁账号的推文返回时 author 字段为空，需标记这些行。

故障排除

• 有效话题标签返回空结果：Twitter API 索引延迟，15 分钟后重试。
• 速率限制错误：将 maxItems 减至 100 并重试。
• 大请求超时：每次运行最多设置 maxItems: 500；更大数据集可配合日期范围串联多次运行。

输出格式

# 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