Twitter Search

# Twitter Search and Analysis

## 概述

使用高级搜索语法在 Twitter 上搜索关键词，获取多达 1000 条相关推文，并分析数据以生成包含洞察、统计数据和可落地建议的专业报告。

## 前置条件

**需要 API 密钥**：用户必须从 https://twitterapi.io 配置其 Twitter API 密钥

可以通过三种方式提供 API 密钥： 1. **环境变量**（推荐）：在您的 `~/.bashrc` 或 `~/.zshrc` 中设置 `TWITTER_API_KEY` ```bash echo 'export TWITTER_API_KEY="your_key_here"' >> ~/.bashrc source ~/.bashrc ``` 2. **作为参数**：在封装脚本中使用 `--api-key YOUR_KEY` 3. **直接传递**：作为 Python 脚本的第一个参数

## 快速开始

### 使用封装脚本（推荐）

封装脚本会自动处理环境变量加载和依赖检查：

```bash # 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 脚本

```bash # 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" ```

### 高级查询

```bash # 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" ```

### 输出格式

```bash # 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 高级搜索](https://github.com/igorbrigadir/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. 获取数据

执行搜索脚本：

```bash 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 格式

始终包含指向推文的可点击链接： ```markdown | Author | Tweet | URL | |--------|-------|-----| | @user | Summary of tweet content | [View](https://x.com/user/status/123456) | ```

或内联格式： ```markdown - **@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 脚本的所有命令行选项

**用法**： ```bash ./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 数据

**用法**： ```bash scripts/twitter_search.py <api_key> <query> [options] ```

### references/twitter_api.md

综合 API 文档，包括： - 完整参数参考 - 查询语法指南 - 响应结构详情 - 分页说明 - 分析最佳实践 - 错误处理指南

**阅读时机**：构建复杂查询或理解数据结构时。

## 改进分析的技巧

1. **使用 Top 查询类型**进行趋势分析（结果更相关） 2. **设置日期过滤器**以获取及时的洞察 3. **按语言过滤**以进行准确的文本分析 4. **包含最小互动量**以过滤噪音 5. **结合网络搜索**以验证趋势 6. **超越指标**——分析内容主题 7. **跟踪话题标签**以识别子对话 8. **结合粉丝数和互动量**识别影响者

## 错误处理

如果脚本失败： - 检查 API 密钥有效性 - 验证查询语法 - 确保网络连接正常 - 检查速率限制（如适用） - 查看错误消息以了解具体问题