Optimization Theory resource collection

DataForSEO integration guide

The importer runs locally against saved completed DataForSEO v3 JSON. It uses Python 3.10+ and the standard library. It does not contact an API or spend credits.

Quick start

  1. Save a completed response from the endpoint in the profile table below. Preserve all task data and pagination results.
  2. Run the matching command from the extracted resource directory.
  3. Open the resulting CSV. Complete required manual fields. Check the generated metadata file for missing fields.
  4. Clear the workbook's lime sample inputs. Paste CSV data rows, without the header, as values at Workspace A13. Check row capacity before pasting.
python3 integration/dataforseo_import.py import   --template 01 --profile keywords   --input keyword-overview.json --output keyword-inputs.csv

python3 integration/dataforseo_import.py overlap   --input serp-a.json serp-b.json --depth 10   --cutoff 0.4 --output overlap-inputs.csv

python3 integration/dataforseo_import.py seasonality   --input keyword-overview.json --output seasonal-inputs.csv

python3 integration/dataforseo_import.py import   --template 09 --csv   --input csv-inputs/09-migration-launch-example.csv   --output launch-inputs.csv

Verified field mappings

All item paths below start within each tasks[].result[] object unless the path states otherwise. The script checks top-level and task status 20000 and rejects mismatched endpoint paths. It never changes missing data to zero.

ProfileDocumentationNormalized fields and response paths
keywordsKeyword Overviewkeyword: items[].keyword
search_volume: items[].keyword_info.search_volume
intent: items[].search_intent_info.main_intent
_monthly: items[].keyword_info.monthly_searches
rankedRanked Keywordskeyword: items[].keyword_data.keyword
search_volume: items[].keyword_data.keyword_info.search_volume
url: items[].ranked_serp_element.serp_item.url
rank: items[].ranked_serp_element.serp_item.rank_group; organic only
onpageOn-Page Pagesurl: items[].url
status_code: items[].status_code
canonical_url: items[].meta.canonical
inlinks: items[].meta.inbound_links_count
from_sitemap: items[].checks.from_sitemap
backlinksBacklinksurl_from: items[].url_from
url_to: items[].url_to
is_lost: items[].is_lost
is_broken: items[].is_broken
url_to_status_code: items[].url_to_status_code
serpOrganic SERP Advancedkeyword: result[].keyword
url: items[].url; organic only
rank: items[].rank_group; organic only
mentionsLLM Search Mentionsquestion: items[].question
platform_model: items[].platform + model_name
observation_id: task ID + response item index
sources: items[].sources; retained in raw response; not inferred as panel observations
mapsMaps Advancedkeyword: result[].keyword
cid: items[].cid; preserve as text
rank: items[].rank_group; maps_search only
grid_point: task.data.location_coordinate

How the four connection types work

Scope and joins

A keyword join needs exact query, country and language. A SERP comparison also needs device, depth and a matched observation window. A URL join needs an approved normalization rule and any migration mapping. Do not strip parameters, change URL case or combine hosts by default.

Each output CSV follows the exact input-column order for its template. No automatic cross-endpoint, GSC, GA4 or catalog join is performed. If the first field is manual, fill it before using the workbook. The workbook flags partially filled rows even when the identifying field is missing.

Pagination and collection

The importer only processes supplied completed responses. It does not retrieve tasks, page through endpoints or infer that a truncated export is complete. Follow the current endpoint's pagination instructions. Keep the original response, request settings, task ID, collection time, filters, limit and response cost.

AI visibility requires extra care

The current endpoint is /v3/ai_optimization/llm_mentions/search_mentions/live. The former search/live endpoint has been replaced. A discovered or target-filtered mentions corpus is not an unbiased panel of all planned runs. The importer preserves one row per discovered answer and leaves observation validity, citation classification, evidence and actual collection date to review.

The helper does not equate an arbitrary URL in an answer with a verified target citation. For AI Overviews, inspect the nested source references in the raw Organic Advanced response. Keep source links separate from merely retrieved search results.

Zero, missing and confirmed absence

Blank means unavailable or unfilled. Zero means a measured zero only where the input definition permits it. Missing rank is not rank 0. Confirmed not-found rank 0 requires a complete search to the stated depth. A failed task is an error, not a negative observation. An empty successful response still requires scope and collection review.

Spreadsheet import details

Percentages use 0-1 decimals. Dates in CSV use ISO YYYY-MM-DD; convert them to actual spreadsheet dates before pasting if your importer leaves them as text. Keep CIDs, SKUs and other long identifiers as text. Formula-leading strings are escaped by the helper before CSV output.

Workbooks support their stated prepared row limit. Do not paste beyond it. Native Excel and Google Sheets import behavior has not been certified; formulas were checked in the authoring engine.

No live authenticated API request was performed for this release. The helper was checked against synthetic fixtures modeled on the documented response shapes. API schemas can change; compare an actual response with the mapping table before a production refresh.

Version 1.0. Reviewed November 17, 2026.