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
- Save a completed response from the endpoint in the profile table below. Preserve all task data and pagination results.
- Run the matching command from the extracted resource directory.
- Open the resulting CSV. Complete required manual fields. Check the generated metadata file for missing fields.
- 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.
| Profile | Documentation | Normalized fields and response paths |
|---|---|---|
| keywords | Keyword Overview | keyword: items[].keywordsearch_volume: items[].keyword_info.search_volumeintent: items[].search_intent_info.main_intent_monthly: items[].keyword_info.monthly_searches |
| ranked | Ranked Keywords | keyword: items[].keyword_data.keywordsearch_volume: items[].keyword_data.keyword_info.search_volumeurl: items[].ranked_serp_element.serp_item.urlrank: items[].ranked_serp_element.serp_item.rank_group; organic only |
| onpage | On-Page Pages | url: items[].urlstatus_code: items[].status_codecanonical_url: items[].meta.canonicalinlinks: items[].meta.inbound_links_countfrom_sitemap: items[].checks.from_sitemap |
| backlinks | Backlinks | url_from: items[].url_fromurl_to: items[].url_tois_lost: items[].is_lostis_broken: items[].is_brokenurl_to_status_code: items[].url_to_status_code |
| serp | Organic SERP Advanced | keyword: result[].keywordurl: items[].url; organic onlyrank: items[].rank_group; organic only |
| mentions | LLM Search Mentions | question: items[].questionplatform_model: items[].platform + model_nameobservation_id: task ID + response item indexsources: items[].sources; retained in raw response; not inferred as panel observations |
| maps | Maps Advanced | keyword: result[].keywordcid: items[].cid; preserve as textrank: items[].rank_group; maps_search onlygrid_point: task.data.location_coordinate |
How the four connection types work
- Direct: existing response fields populate the corresponding input columns. Planning assumptions remain manual.
- Enrichment: API records provide context or an inventory. Join private analytics and human decisions using an explicit key.
- Derived: transforms or aggregation create the right row grain. The helper includes overlap and 12-month seasonality transforms. Other aggregations are manual.
- Evidence: a human completes a workflow and attaches crawl or market proof. The helper accepts a completed input CSV rather than converting API items into approvals.
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.