Introduction
# SEO Keyword Research (DataForSEO)
## Setup
Install dependencies:
```bash pip install -r scripts/requirements.txt ```
Configure credentials by creating a `.env` file in the project root:
``` [email protected] DATAFORSEO_PASSWORD=your_api_password ```
Get credentials from: https://app.dataforseo.com/api-access
## Quick Start
| User says | Function to call | |-----------|-----------------| | "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")` |
Execute functions by importing from `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") ```
## Workflow Pattern
Every research task follows three phases:
### 1. Research Run API functions. Each function call hits the DataForSEO API and returns structured data.
### 2. Auto-Save All results automatically save as timestamped JSON files to `results/{category}/`. File naming pattern: `YYYYMMDD_HHMMSS__operation__keyword__extra_info.json`
### 3. Summarize After research, read the saved JSON files and create a markdown summary in `results/summary/` with data tables, ranked opportunities, and strategic recommendations.
## High-Level Functions
These are the primary functions in `scripts/main.py`. Each orchestrates multiple API calls for a complete research workflow.
| Function | Purpose | What it gathers | |----------|---------|----------------| | `keyword_research(keyword)` | Single keyword deep-dive | Overview, suggestions, related keywords, difficulty | | `youtube_keyword_research(keyword)` | YouTube content research | Overview, suggestions, YouTube SERP rankings, YouTube trends | | `landing_page_keyword_research(keywords, competitor_domain)` | Landing page SEO | Overview, intent, difficulty, SERP analysis, competitor keywords | | `full_keyword_analysis(keywords)` | Strategic content planning | Overview, difficulty, intent, keyword ideas, historical volume, Google Trends | | `competitor_analysis(domain, keywords)` | Competitor intelligence | Domain keywords, Google Ads keywords, competitor domains | | `trending_topics(location_name)` | Current trends | Currently trending searches |
### Parameters
All functions accept an optional `location_name` parameter (default: "United States"). Most functions also have boolean flags to skip specific sub-analyses (e.g., `include_suggestions=False`).
### Individual API Functions
For granular control, import specific functions from the API modules. See [references/api-reference.md](references/api-reference.md) for the complete list of 25 API functions with parameters, limits, and examples.
## Results Storage
Results auto-save to `results/` with this structure:
``` results/ ├── keywords_data/ # Search volume, CPC, competition ├── labs/ # Suggestions, difficulty, intent ├── serp/ # Google/YouTube rankings ├── trends/ # Google Trends data └── summary/ # Human-readable markdown summaries ```
### Managing Results
```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") ```
### Utility Functions
```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") ```
## Creating Summaries
After running research, create a markdown summary document in `results/summary/`. Include:
- **Data tables** with volumes, CPC, competition, difficulty - **Ranked lists** of opportunities (sorted by volume or opportunity score) - **SERP analysis** showing what currently ranks - **Recommendations** for content strategy, titles, tags
Name the summary file descriptively (e.g., `results/summary/ai-tools-keyword-research.md`).
## Tips
1. **Be specific** — "Get keyword suggestions for 'AI website builders'" works better than "research AI stuff" 2. **Request summaries** — Always create a summary document after research, named specifically 3. **Batch related keywords** — Pass multiple related keywords at once for comparison 4. **Specify the goal** — "for a YouTube video" vs "for a landing page" changes which data matters most 5. **Ask for competition analysis** — "Show me what videos are ranking" helps identify content gaps
## Defaults
- **Location**: United States (code 2840) - **Language**: English - **API Limits**: 700 keywords for volume/overview, 1000 for difficulty/intent, 5 for trends, 200 for keyword ideas