DataForSEO SERP API

Provenance

This is an experimental project to test how OpenCode, plugged into frontier LLMs (OpenAI GPT-5.2), can help generate high-fidelity agent skill files for API integrations.

When to Apply

• "track keyword rankings", "rank tracking", "SERP monitoring"
• "get Google SERP", "Bing SERP", "YouTube SERP", "localized SERP"
• "compare SERP by country/city", "location-based SERP", "language-based SERP"
• "SERP features", "local pack", "news results", "images results"
• "SERP screenshot", "SERP HTML", "SERP snapshot"
• "build an SEO dashboard", "SERP alerts", "SERP volatility"

Integration Contract (Language-Agnostic)

See references/REFERENCE.md for the shared DataForSEO integration contract (auth, status handling, task lifecycle, sandbox, and .ai responses).

Implementation Expectations (for the agent)

1. Choose the exact SERP endpoint family (Google/Bing/YouTube/etc.) and the result format (Regular/Advanced/HTML) from the docs.
2. Collect required inputs:
   • query/keyword
   • location + language (when applicable)
   • device, depth, and any optional SERP modifiers
3. Decide Live vs Task-based flow.
4. Execute HTTP request(s) with Basic Auth.
5. Validate status_code and return:
   • a normalized, compact result for the user
   • the raw response payload for debugging

Steps

1. Identify the exact endpoint(s) in the official docs for this use case.
2. Choose execution mode:
   • Live (single request) for interactive queries
   • Task-based (post + poll/webhook) for scheduled or high-volume jobs
3. Build the HTTP request:
   • Base URL: https://api.dataforseo.com/
   • Auth: HTTP Basic (Authorization: Basic base64(login:password)) from https://docs.dataforseo.com/v3/auth/
   • JSON body exactly as specified in the endpoint docs
4. Execute and validate the response:
   • Check top-level status_code and each tasks[] item status
   • Treat any status_code != 20000 as a failure; surface status_message
5. For task-based endpoints:
   • Store tasks[].id
   • Poll tasks_ready then fetch results with task_get (or use postback_url/pingback_url if supported)
6. Return results:
   • Provide a normalized summary for the user
   • Include the raw response payload for debugging

Inputs Checklist

• Credentials: DataForSEO API login + password (HTTP Basic Auth)
• Target: keyword(s) / domain(s) / URL(s) / query string (depends on endpoint)
• Targeting (if applicable): location + language, device, depth/limit
• Time window (if applicable): date range, trend period, historical flags
• Output preference: regular vs advanced vs html (if the endpoint supports it)

Example (cURL)

curl -u "${DATAFORSEO_LOGIN}:${DATAFORSEO_PASSWORD}"   -H "Content-Type: application/json"   -X POST "https://api.dataforseo.com/v3/<group>/<path>/live"   -d '[
    {
      "<param>": "<value>"
    }
  ]'

Notes:

• Replace <group>/<path> with the exact endpoint path from the official docs.
• For task-based flows, use the corresponding task_post, tasks_ready, and task_get endpoints.

Docs Map (Official)

• Overview: https://docs.dataforseo.com/v3/serp/overview/
• Endpoints list: https://docs.dataforseo.com/v3/serp/endpoints/
• Example task flow (Google Organic Task POST): https://docs.dataforseo.com/v3/serp/google/organic/task_post/
• Authentication: https://docs.dataforseo.com/v3/auth/
• Sandbox: https://docs.dataforseo.com/v3/appendix/sandbox/
• Errors: https://docs.dataforseo.com/v3/appendix/errors/
• AI-optimized response: https://docs.dataforseo.com/v3/appendix/ai_optimized_response/

Business & Product Use Cases

• Build a rank tracking product (scheduled keywords, multi-location, historical charts).
• Monitor competitors' search visibility across markets and languages.
• Detect SERP volatility and feature changes and send alerts to stakeholders.
• Validate SEO impact after releases (content updates, internal linking, template changes).
• Power an SEO reporting dashboard for clients (white-label PDFs/CSVs).
• Feed SERP output into a content roadmap (what formats and intent types win).

Examples (User Prompts)

• "If you don't have the skill installed, install dataforseo-serp-api and then continue."
• "Install the DataForSEO SERP skill and track daily rankings for these 50 keywords in New York (EN)."
• "Get the top 10 Google organic results for 'best running shoes' in Brazil (PT) and summarize the intent."
• "Compare SERPs for 'crm software' in US vs UK and highlight different competitors."
• "Pull Google Maps results for 'pizza near me' in Chicago and extract top businesses + ratings."
• "Take a SERP screenshot for 'wireless earbuds' in Germany and save the URL in the report."