SEO Keyword Research (DataForSEO)

Setup

Install dependencies:

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:

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

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

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

Be specific — "Get keyword suggestions for 'AI website builders'" works better than "research AI stuff"
Request summaries — Always create a summary document after research, named specifically
Batch related keywords — Pass multiple related keywords at once for comparison
Specify the goal — "for a YouTube video" vs "for a landing page" changes which data matters most
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