dataforseo

DataForSEO API Skill

Universal interface to all DataForSEO APIs for comprehensive SEO data retrieval and analysis.

Credential Setup

Before first use, set up credentials:

import sys, os
sys.path.insert(0, os.path.expanduser('~/.agents/skills/dataforseo/scripts'))
from dataforseo_client import save_credentials, verify_credentials

# Get credentials from https://app.dataforseo.com/
login = "your_email@example.com"  # API login (email)
password = "your_api_password"    # API password (from dashboard)

# Verify and save
if verify_credentials(login, password):
    save_credentials(login, password)
    print("Credentials saved!")

Credentials stored at ~/.dataforseo_config.json. To update, run setup again.

Quick Start

import sys, os
sys.path.insert(0, os.path.expanduser('~/.agents/skills/dataforseo/scripts'))
from dataforseo_client import *

# Example: Get search volume
response = keywords_search_volume(
    keywords=["seo tools", "keyword research"],
    location_name="United States"
)
results = extract_results(response)
csv_path = to_csv(results, "keyword_volumes")
print(f"Results saved to: {csv_path}")

API Selection Guide

User Request	Function to Use
Search volume, CPC, competition	keywords_search_volume()
Keyword ideas/suggestions	labs_keyword_ideas() or labs_related_keywords()
Keywords a site ranks for	labs_ranked_keywords()
SERP results for keyword	serp_google_organic()
Local/Maps rankings	serp_google_maps()
YouTube rankings	serp_youtube()
Backlink profile	backlinks_summary()
List of backlinks	backlinks_list()
Referring domains	backlinks_referring_domains()
Domain authority/rank	backlinks_bulk_ranks()
Competing domains	labs_competitors_domain()
Keyword gap analysis	labs_domain_intersection()
Link gap analysis	backlinks_domain_intersection()
Technical page audit	onpage_instant_pages()
Lighthouse scores	lighthouse_live()
Technology stack	domain_technologies()
Brand mentions	content_search()
Google Trends	google_trends()

Core Workflow

1. Import client: Add skill path and import functions
2. Call API function: Pass required parameters
3. Extract results: Use extract_results(response)
4. Export to CSV: Use to_csv(results, "filename")

import sys, os
sys.path.insert(0, os.path.expanduser('~/.agents/skills/dataforseo/scripts'))
from dataforseo_client import labs_ranked_keywords, extract_results, to_csv

response = labs_ranked_keywords(
    target="competitor.com",
    location_name="United States",
    language_name="English",
    limit=500
)
results = extract_results(response)
csv_path = to_csv(results, "ranked_keywords")

Default Parameters

Most functions use these defaults:

• location_name: "United States" (override with "India", "United Kingdom", etc.)
• language_name: "English"
• limit: 100 (increase up to 1000 for more results)
• device: "desktop" (or "mobile" for SERP)

Common Location Names

• United States, United Kingdom, India, Germany, Australia, Canada
• For city-level: "New York,New York,United States", "London,England,United Kingdom"

Output

All results export to CSV at ~/dataforseo_outputs/. Files auto-named with timestamp if not specified.

Reference Files

• API Reference: references/api_reference.md - Complete endpoint documentation
• Use Cases: references/use_cases.md - Ready-to-use code recipes

Error Handling

response = some_api_function(...)
if response.get("status_code") == 20000:
    results = extract_results(response)
    # Process results
else:
    print(f"Error: {response.get('status_message')}")

Rate Limits & Costs

• 2000 requests/minute max
• Live methods cost more than Standard
• Check usage with get_user_data()
• Response includes cost field

Important Notes

1. Async endpoints: Some APIs (merchant, app_data, business reviews) create tasks. Check task status separately.
2. Limits: Increase limit parameter for comprehensive data (default 100, max usually 1000)
3. Multiple keywords: Pass as list: keywords=["kw1", "kw2", "kw3"]