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

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

Import client: Add skill path and import functions
Call API function: Pass required parameters
Extract results: Use extract_results(response)
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

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

dataforseo

DataForSEO API Skill

Credential Setup