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