Data sources

DataForSEO is the implementation provider for Public Mode. It is not the methodology. The normalized data model, rubric, and score are provider-agnostic. A future adapter can replace the provider without rewriting the scorecard.

Endpoint families used

Endpoint shapes were verified against the current official DataForSEO documentation on 2026-10-27. Do not rely on an old request or response shape.

Family	Endpoint	Used for
SERP	POST /v3/serp/google/organic/live/advanced	Local Pack observations and organic results
SERP	POST /v3/serp/google/maps/live/advanced	Google Maps observations at a coordinate
SERP	POST /v3/serp/google/local_finder/live/advanced	Local Finder observations where configured
SERP	POST /v3/serp/google/ai_mode/live/advanced	Google AI Mode consumer/search observations
DataForSEO Labs	POST /v3/dataforseo_labs/google/keyword_overview/live	Demand context for the locked universe
AI Optimization	POST /v3/ai_optimization/llm_mentions/search_mentions/live	ChatGPT/model mention observations
Backlinks	POST /v3/backlinks/summary/live	Authority summary
Backlinks	POST /v3/backlinks/referring_domains/live	Referring-domain relevance and competitor comparison
Business Data	POST /v3/business_data/business_listings/search/live	Target resolution and external listing consistency

Official references:

• Google Maps SERP
• Google Local Finder SERP
• Google AI Mode SERP
• Google Organic SERP
• DataForSEO Labs Keyword Overview
• LLM Mentions
• Backlinks Summary
• Referring Domains
• Business Listings Search

Provider constraints the collector respects

• Maps search_places: DataForSEO warns that search-places mode can return results for a location other than the requested coordinate. Grid collection therefore sends search_places=false by default and only opts in when a caller explicitly asks for it.
• ChatGPT LLM Mentions: DataForSEO documents this surface for the United States and English only. The adapter refuses another market or language instead of silently scoring US data for a local business elsewhere.
• Task-level errors: A top-level 20000 response can still contain a failed task. The client treats the task status as authoritative and raises a typed provider error, so the observation is recorded as not collected rather than as "rank not found."
• Competitor cohort: Observed SERP businesses are matched to the locked cohort by place ID, CID, domain, phone, then name/alias. A matched business keeps the cohort ID; an unlocked local business is recorded as obs-... and is not counted as a scored peer. Directories and publishers remain serp-... occupiers.

Provider layer

All vendor-specific HTTP lives in:

providers/dataforseo/
  auth.mjs          environment-only Basic Auth
  client.mjs        timeout, retries, concurrency, cache, cost tracking
  serp.mjs          organic, maps, local finder, AI Mode
  labs.mjs          demand context
  ai.mjs            LLM mentions
  backlinks.mjs     summary and referring domains
  business-data.mjs business listings
  normalize.mjs     raw response → normalized observation

The rest of the pipeline consumes normalized structures, not raw DataForSEO responses.

Authentication

Credentials come from the environment only:

Option A — separate credentials:

export DATAFORSEO_LOGIN="..."
export DATAFORSEO_PASSWORD="..."

Option B — a pre-encoded Base64 login:password value:

export DATAFORSEO_BASIC_AUTH="Basic <base64-login-password>"

The client accepts the bare Base64 value or a full Basic ... header, validates that it decodes to login:password, and keeps it in memory. The application never loads .env automatically. It never writes the login, password, or Basic Authorization header to an audit artifact, cache key, URL, log, report, or exception.

Request safety

The client enforces:

• an explicit timeout,
• bounded retries with backoff,
• bounded concurrency,
• a maximum response size,
• request deduplication,
• a local raw-response cache,
• rate-limit and provider-error classification,
• partial-run detection,
• task and cost tracking.

It never logs request headers or dumps an auth object.

Cost

Before a live run, the collector shows:

• core keywords,
• grid points,
• Maps and Local Pack tasks,
• organic tasks,
• AI prompt tasks,
• competitor and authority tasks,
• estimated total task count,
• configured SERP and AI task ceilings,
• cost estimate, if a local pricing file is supplied.

If a reliable cost estimate is unavailable, the tool says so. It does not invent a provider price. --max-cost-usd requires --pricing with real local prices.

--dry-run and --plan send no paid request. A plan that exceeds a configured ceiling does not run without explicit --allow-over-budget opt-in.

Raw responses

Raw provider responses stay in .cache/dataforseo/ or .audit/. Both are gitignored. The audit artifact contains normalized observations and provenance, not the raw payload.

Never commit raw API responses from a real audit.

Provider-agnostic model

A source record says provider: "dataforseo" because that is how the observation was collected. The score does not require DataForSEO. The normalized model is:

• surface,
• method,
• location method,
• language,
• device,
• observation,
• target match,
• competitors,
• provenance.

A future provider can implement the same normalized shape.

Current limitations

• V1 implements Google surfaces, Google AI Mode, ChatGPT via LLM Mentions, backlinks, and business listings.
• Bing, Apple Maps, Nextdoor, Yelp, Houzz, and manufacturer directories are documented future adapters.
• LLM Responses endpoints are not implemented until their current request shapes are validated against the official documentation and a fixture. Do not guess an endpoint.
• DataForSEO availability, pricing, and response shapes can change. Re-verify the official documentation before changing an adapter.

What the report says

The report identifies DataForSEO as the provider and includes a provenance table. It does not present the provider as the methodology, and it does not publish account spending.

---

Scorecard family boundary

This page covers discovery. The GBP Scorecard diagnoses profile trust and action; the Website Scorecard diagnoses website conversion. Read The Scorecard Family for the ownership matrix and the no-duplicate-scoring rule.