Build Your Own Google AI Overview Tracker
This is NOT a dashboard, SaaS application, project manager, reporting platform or GUI. It is a focused command-line utility designed to be called manually or from other scripts.
PRIMARY GOAL
The program accepts:
1. A Google search query/prompt
2. A brand name
3. A website URL or domain
Example:
aio-check –prompt “best pest control company calgary” –brand “Major Pest Control” –url “https://majorpestcontrol.ca/”
The program queries Google search results through a SERP API that provides Google AI Overview data.
Prefer DataForSEO (affiliate link) if its current API exposes the necessary AI Overview content and citations. Design the provider layer so another SERP provider can be substituted later without rewriting the matching and output logic.
Do NOT directly scrape Google unless explicitly requested later.
REQUIRED RESULTS
Determine:
1. Did Google return an AI Overview for the query?
2. Is the supplied brand mentioned anywhere in the AI Overview?
3. Is the supplied domain or URL cited anywhere in the AI Overview?
4. What URLs/domains are cited in the AI Overview?
5. If possible from the API response, return the actual AI Overview text.
These are separate measurements.
A brand may be mentioned without its website being cited.
EXAMPLE JSON OUTPUT
{
“prompt”: “best pest control company calgary”,
“brand”: “Major Pest Control”,
“target_url”: “https://majorpestcontrol.ca/”,
“target_domain”: “majorpestcontrol.ca”,
“aio_present”: true,
“brand_found”: true,
“domain_found”: true,
“exact_url_found”: false,
“aio_text”: “AI Overview text here…”,
“citations”: [
{
“url”: “https://majorpestcontrol.ca/services/pest-control/”,
“domain”: “majorpestcontrol.ca”
},
{
“url”: “https://example.com/pest-control/”,
“domain”: “example.com”
}
],
“error”: null
}
PREFERRED LANGUAGE
Use Python 3.
The application must run on both Windows and Linux/Unix.
Avoid unnecessary dependencies. Use standard Python libraries where practical.
The application should be easy to call from:
– Perl
– PowerShell
– Bash
– VB.NET
– cron
– Windows Task Scheduler
– other applications
CLI INTERFACE
Support:
aio-check –prompt “query” –brand “Brand Name” –url “https://example.com”
Also support short options:
aio-check -p “query” -b “Brand Name” -u “example.com”
Provide three output modes.
NORMAL TEXT MODE
aio-check …
Example:
AIO: YES
Brand: FOUND
Domain: FOUND
Exact URL: NOT FOUND
Citations: 7
JSON MODE
aio-check … –json
Return machine-readable JSON only.
Do not mix status messages, debugging output or explanatory text into stdout when JSON mode is used.
Errors and diagnostics should go to stderr where appropriate.
QUIET MODE
aio-check … –quiet
Produce no normal output. Communicate the primary result through exit codes.
EXIT CODES
Use documented, stable exit codes.
At minimum:
0 = AI Overview present and target brand or domain found
1 = AI Overview present but target brand/domain not found
2 = No AI Overview returned
3 = API/search request failed
4 = Invalid arguments/configuration
Do not make the caller parse text to determine the result.
URL MATCHING
Normalize URLs before comparison.
These should all resolve to the same domain:
https://www.example.com/
http://example.com
https://example.com/page
www.example.com
example.com
Normalize protocol, www, capitalization, trailing slash, fragments and common URL formatting differences.
Domain matching should detect any citation from the supplied target domain.
For example:
Target:
Citation:
https://www.majorpestcontrol.ca/services/ants/
Should result in:
domain_found = true
But:
exact_url_found = false
Do not use naive substring matching for domains because “example.com” must not accidentally match “notexample.com”.
Use proper URL/domain parsing.
BRAND MATCHING
Brand matching should initially be case-insensitive.
For example:
Major Pest Control
major pest control
MAJOR PEST CONTROL
should match.
Create brand matching as its own function/module so fuzzy matching or brand aliases can be added later.
Do not automatically use fuzzy matching in V1 if it could generate false positives.
SERP PROVIDER ARCHITECTURE
Keep the provider separate from the matching logic.
For example:
providers/
base.py
dataforseo.py
The rest of the application should receive a normalized structure regardless of the SERP provider.
Conceptually:
result = provider.search(prompt)
analysis = analyze_aio(result, brand, url)
Do not spread DataForSEO-specific parsing throughout the application.
DATAFORSEO
Use DataForSEO’s current Google SERP API if it provides Google AI Overview data.
Before implementing the parser, verify the current DataForSEO response structure for AI Overview results.
Do not invent API response fields.
Credentials must NOT be hard-coded.
Support credentials through environment variables:
DATAFORSEO_LOGIN
DATAFORSEO_PASSWORD
Optionally support a local configuration file, but environment variables should work without one.
Never print credentials in normal output, JSON output, logs or error messages.
LOCATION
Design the CLI so location can be specified because Google AI Overview results can vary geographically.
Example:
aio-check –prompt “best pest control company” –brand “Major Pest Control” –url “majorpestcontrol.ca” –location “Calgary, Alberta, Canada”
If the SERP provider supports language, device or other useful search parameters, structure the code so they can be added cleanly.
Do not overbuild these features in V1.
RAW RESPONSE
Add an optional debugging switch:
–save-raw filename.json
This saves the original SERP API response.
This is important because API structures can change and we may want to reprocess historical responses later.
Do not save raw responses unless requested.
BATCH MODE
After single-query mode works correctly, add optional support for:
aio-check –prompt-file prompts.txt –brand “Major Pest Control” –url “majorpestcontrol.ca”
Each line in prompts.txt represents one query.
Batch JSON output should be valid structured JSON, not several unrelated JSON objects concatenated together.
Example:
{
“brand”: “Major Pest Control”,
“target_domain”: “majorpestcontrol.ca”,
“queries”: 100,
“aio_present”: 76,
“brand_found”: 31,
“domain_found”: 18,
“results”: []
}
Get single-query mode completely working before implementing batch processing.
SUGGESTED PROJECT STRUCTURE
Keep this small.
aio-check/
aio_check.py
providers/
__init__.py
base.py
dataforseo.py
matching.py
requirements.txt
README.md
Do not introduce databases, web servers, React, Docker, Redis, queues, authentication systems, ORMs or other infrastructure unless there is a demonstrated requirement.
ERROR HANDLING
Handle:
– invalid credentials
– API timeout
– rate limiting
– malformed API response
– missing AI Overview data
– malformed URL
– missing arguments
– network failure
Distinguish “Google returned no AI Overview” from “the API request failed.”
Those are fundamentally different results.
TESTING
Include basic automated tests for:
– URL normalization
– domain matching
– exact URL matching
– case-insensitive brand matching
– AI Overview absent
– brand present/domain absent
– domain present/brand absent
– neither present
– malformed API response
Where possible, use saved/mock API responses so tests do not consume API credits.
README
Create a concise README explaining:
1. Installation
2. DataForSEO credential setup
3. Single-query usage
4. JSON usage
5. Quiet mode
6. Exit codes
7. Location option
8. Batch usage
9. Raw-response debugging
Include Windows PowerShell and Linux/Bash examples.
DEVELOPMENT PRIORITIES
Build this incrementally.
Priority order:
1. Verify DataForSEO’s current AI Overview response format.
2. Create DataForSEO provider.
3. Run one query successfully.
4. Detect whether an AI Overview exists.
5. Extract AI Overview text and citations.
6. Normalize the supplied target domain.
7. Detect target-domain citations.
8. Detect exact URL citations.
9. Detect brand mentions.
10. Implement JSON output.
11. Implement exit codes and quiet mode.
12. Add location support.
13. Add raw-response saving.
14. Add automated tests.
15. Add batch prompt-file support.
Do not start by building batch processing or abstractions before a real single-query request has successfully returned and been parsed.
DEFINITION OF DONE FOR V1
I should be able to install the program, configure my DataForSEO credentials and run:
aio-check –prompt “best pest control company calgary” –brand “Major Pest Control” –url “majorpestcontrol.ca” –location “Calgary, Alberta, Canada” –json
and receive a reliable machine-readable answer telling me:
– Did an AI Overview appear?
– Was the brand mentioned?
– Was the target domain cited?
– Was the exact target URL cited?
– What URLs were cited?
Keep the program small, readable, modular and easy to modify.
Do not turn this into a platform.
The purpose is to create a dependable CLI primitive that other scripts and applications can call thousands of times.
