介绍
# SEO Keyword Research (DataForSEO)
## 设置
安装依赖：
```bash pip install -r scripts/requirements.txt ```
通过在项目根目录下创建 `.env` 文件来配置凭据：
``` [email protected] DATAFORSEO_PASSWORD=your_api_password ```
从以下地址获取凭据：https://app.dataforseo.com/api-access
## 快速开始
| 用户说 | 要调用的函数 | |-----------|-----------------| | "Research keywords for [topic]" | `keyword_research("topic")` | | "YouTube keyword data for [idea]" | `youtube_keyword_research("idea")` | | "Analyze competitor [domain.com]" | `competitor_analysis("domain.com")` | | "What's trending?" | `trending_topics()` | | "Keyword analysis for [list]" | `full_keyword_analysis(["kw1", "kw2"])` | | "Landing page keywords for [topic]" | `landing_page_keyword_research(["kw1"], "competitor.com")` |
通过从 `scripts/main.py` 导入来执行函数：
```python import sys from pathlib import Path sys.path.insert(0, str(Path("scripts"))) from main import *
result = keyword_research("AI website builders") ```
## 工作流模式
每个研究任务都遵循三个阶段：
### 1. 研究
运行 API 函数。每个函数调用都会访问 DataForSEO API 并返回结构化数据。
### 2. 自动保存
所有结果都会自动保存为带时间戳的 JSON 文件到 `results/{category}/`。文件命名模式：`YYYYMMDD_HHMMSS__operation__keyword__extra_info.json`
### 3. 汇总
研究结束后，读取保存的 JSON 文件并在 `results/summary/` 中创建包含数据表格、排名机会和战略建议的 markdown 摘要。
## 高级函数
这些是 `scripts/main.py` 中的主要函数。每个函数都协调多个 API 调用以完成完整的研究工作流。
| 函数 | 目的 | 收集内容 | |----------|---------|----------------| | `keyword_research(keyword)` | 单个关键词深度分析 | 概览、建议、相关关键词、难度 | | `youtube_keyword_research(keyword)` | YouTube 内容研究 | 概览、建议、YouTube SERP 排名、YouTube 趋势 | | `landing_page_keyword_research(keywords, competitor_domain)` | 落地页 SEO | 概览、意图、难度、SERP 分析、竞争对手关键词 | | `full_keyword_analysis(keywords)` | 战略内容规划 | 概览、难度、意图、关键词构思、历史搜索量、Google Trends | | `competitor_analysis(domain, keywords)` | 竞争对手情报 | 域名关键词、Google Ads 关键词、竞争对手域名 | | `trending_topics(location_name)` | 当前趋势 | 当前热门搜索 |
### 参数
所有函数都接受一个可选的 `location_name` 参数（默认值："United States"）。大多数函数还具有布尔标志，用于跳过特定的子分析（例如，`include_suggestions=False`）。
### 独立 API 函数
如需精细控制，请从 API 模块导入特定函数。有关包含参数、限制和示例的完整 25 个 API 函数列表，请参阅 [references/api-reference.md](references/api-reference.md)。
## 结果存储
结果自动保存到 `results/`，结构如下：
``` results/ ├── keywords_data/ # Search volume, CPC, competition ├── labs/ # Suggestions, difficulty, intent ├── serp/ # Google/YouTube rankings ├── trends/ # Google Trends data └── summary/ # Human-readable markdown summaries ```
### 管理结果
```python from core.storage import list_results, load_result, get_latest_result
# List recent results files = list_results(category="labs", limit=10)
# Load a specific result data = load_result(files[0])
# Get most recent result for an operation latest = get_latest_result(category="labs", operation="keyword_suggestions") ```
### 实用函数
```python from main import get_recent_results, load_latest
# List recent files across all categories files = get_recent_results(limit=10)
# Load latest result for a category data = load_latest("labs", "keyword_suggestions") ```
## 创建摘要
运行研究后，在 `results/summary/` 中创建 markdown 摘要文档。包括：
- **数据表格**，包含搜索量、CPC、竞争度、难度 - **排名列表**，列出机会（按搜索量或机会得分排序） - **SERP 分析**，显示当前排名内容 - **建议**，针对内容策略、标题、标签
请为摘要文件起一个描述性的名称（例如 `results/summary/ai-tools-keyword-research.md`）。
## 提示
1. **具体明确** —— "获取 'AI website builders' 的关键词建议" 比 "研究 AI 相关内容" 效果更好 2. **请求摘要** —— 研究后务必创建一个命名的摘要文档 3. **批量相关关键词** —— 一次传递多个相关关键词以进行比较 4. **明确目标** —— "针对 YouTube 视频" 与 "针对落地页" 会改变哪些数据最重要 5. **询问竞争分析** —— "向我展示哪些视频排名靠前" 有助于识别内容空白
## 默认值
- **位置**：美国 (United States，代码 2840) - **语言**：英语 - **API 限制**：700 个关键词用于搜索量/概览，1000 个用于难度/意图，5 个用于趋势，200 个用于关键词构思