SEO DataForSEO

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

2. Auto-Save

3. Summarize

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:

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

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

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

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