seo-dataforseo

# 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:

```
DATAFORSEO_LOGIN=your_email@example.com
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)` | YouT...