# Google Ads API Agent — Full Technical Reference > Complete technical documentation for LLMs and AI agents. Covers the Google Ads API Agent, Google Ads Builder, Marketing Analytics Auditor, 250-Point Audit Engine, Business Discovery Engine, and all content properties. --- ## Entity & Organization Graph - **Site**: googleadsagent.ai — Open-source AI agent platform for Google Ads API management. - **Parent Organization**: It All Started With A Idea (https://itallstartedwithaidea.com) — Performance marketing agency specializing in PPC, Google Ads, and AI-powered marketing tools. - **Founder**: John Williams — Senior Paid Media Specialist at Seer Interactive (https://www.seerinteractive.com). 15+ years managing $48M+ in digital advertising across Google Ads, Meta, Microsoft, Amazon, and other platforms. Former NortonLifeLock (192% YoY paid search growth), Gen Digital, Farmers Insurance. Hero Conf 2025 speaker. - **Relationship**: googleadsagent.ai is a product built by It All Started With A Idea. Both entities share the same founder and brand ecosystem. - **Social Profiles**: LinkedIn (https://www.linkedin.com/in/johnmichaelwilliams), X (https://x.com/_johnmwilliams), Instagram (https://www.instagram.com/_johnmwilliams/), Substack (https://substack.com/@itallstartedwithaidea), GitHub (https://github.com/itallstartedwithaidea), Reddit (https://www.reddit.com/r/allthingsadvertising/). --- ## Project: Google Ads API Agent ### Overview An open-source AI agent that manages Google Ads accounts through the API. 28 custom Python actions, 6 specialized sub-agents, live read/write access to real Google Ads accounts. Built on Claude by Anthropic. ### Repository - GitHub: https://github.com/itallstartedwithaidea/google-ads-api-agent - 66 files across 12 directories - License: MIT ### Architecture #### The Loop The agent's core reasoning cycle: 1. Receive user request 2. Ask clarifying questions (CEP Protocol) 3. Call appropriate tools/actions 4. Analyze returned data 5. Confirm write operations with preview 6. Execute changes with rollback labeling 7. Present results #### CEP Protocol (Clarify, Execute, Present) Every interaction follows this pattern. The agent never makes assumptions — it asks clarifying questions before executing any API call. #### Filter-First Architecture 6-tier filtering narrows data at each level: 1. Account-level filter (which MCC child account) 2. Campaign-level filter (campaign name/ID) 3. Ad group filter 4. Entity filter (keywords, ads, etc.) 5. Metric filter (date range, performance thresholds) 6. Presentation filter (top N, sort order) #### Write Safety Confirmation All write operations require: - Preview of current vs. proposed changes - Explicit "CONFIRM" from the user - Rollback labeling (label applied to changed entities for undo) ### 28 API Actions (Complete List) 1. label_manager.py — Create/apply/remove labels 2. conversion_tracking_manager.py — Conversion action management 3. audience_manager.py — Audience list management 4. asset_manager.py — Asset operations 5. budget_manager.py — Campaign budget modifications 6. rsa_ad_manager.py — Responsive Search Ad CRUD 7. bid_keyword_manager.py — Bid and keyword operations 8. negative_keywords_manager.py — Negative keyword lists 9. campaign_adgroup_manager.py — Campaign & ad group operations 10. google_ads_mutate.py — Generic mutate operations 11. account_access_checker.py — Account access verification 12. scripts_manager.py — Google Ads Scripts management 13. experiments_manager.py — A/B test experiment management 14. package_installer.py — Python package installation 15. check_user_access.py — User access validation 16. api_gateway.py — API gateway operations 17. session_state_manager.py — Session and state management 18. cloudinary_creative_tools.py — Cloudinary image processing 19. query_planner.py — Dynamic GAQL query builder 20. recommendations_manager.py — Google Ads recommendations 21. search_term_manager.py — Search term analysis 22. geo_location_manager.py — Geographic targeting 23. device_performance_manager.py — Device performance analysis 24. change_history_manager.py — Account change log 25. campaign_creator.py — Full campaign creation 26. ad_schedule_manager.py — Ad scheduling 27. bidding_strategy_manager.py — Bidding strategy management 28. pmax_asset_group_manager.py — PMax asset group operations ### 6 Sub-Agents 1. **Simba** (Reporting & Analysis) — 8 actions: campaign reports, ad group reports, keyword reports, ad reports, search terms, auction insights, change history, PMax reports 2. **Nemo** (Research & Intelligence) — 4 actions: keyword planner, Google Trends, ads transparency, query planner 3. **Elsa** (Optimization) — Planned: bulk bid changes, budget optimization, recommendation engine 4. **Aladdin** (Shopping & PMax) — Planned: product feed management, asset group optimization 5. **Moana** (Creative) — 2 actions: responsive display ads, demand gen campaigns 6. **Baymax** (Creative Innovate) — 2 actions: Cloudinary image processing, Gemini vision AI --- ## Project: Google Ads Builder ### Overview AI-powered Google Ads copy generator. Creates RSA headlines (30 chars x 15), descriptions (90 chars x 4), sitelinks, and callouts by analyzing landing pages. ### URLs - Landing: https://googleadsagent.ai/tools/google-ads-builder/ - App: https://googleadsagent.ai/tools/google-ads-builder/app.html - Docs: https://googleadsagent.ai/tools/google-ads-builder/docs.html ### Technical Details - Single HTML file, zero build step - Supports Claude, GPT-4, and Gemini APIs - API keys stored in browser sessionStorage only - All processing client-side - Exports: CSV, Google Ads Editor format, clipboard --- ## Project: Marketing Analytics Auditor ### Overview Free, open-source GA4 + GTM + marketing pixel auditor with auto-generated remediation code. Scans any URL for tags, runs property health checks, validates pixel and CAPI configurations, and generates copy-paste code to fix every issue found. ### URLs - Landing: https://googleadsagent.ai/tools/auditor/ - App: https://googleadsagent.ai/tools/auditor/app.html - Docs: https://googleadsagent.ai/tools/auditor/docs.html ### Technical Architecture #### Three Core Pillars 1. **Audit** — Scan GA4 properties, GTM containers, and marketing pixels for misconfigurations 2. **Remediate** — Generate copy-paste dataLayer code, GTM container JSON, CAPI boilerplate 3. **Discover** — AI vision scans pages to identify elements and suggest tracking events #### Tag Detection Engine Detects 10 platforms using 4 methods: DOM script tag pattern matching, JavaScript global object detection, network request URL pattern matching, cookie signature scanning. #### Scoring System Tag Health Score: 0-100. Grades: A (90+), B (80-89), C (70-79), D (60-69), F (<60). #### Security Model All analysis runs client-side. No server-side storage, no database, no user accounts. API keys in sessionStorage only. Open source. --- ## Project: 250-Point Google Ads Audit Engine ### Overview An open-source, MCP-first 250-point Google Ads audit engine with 9 service connectors, weighted scoring, vertical calibration for 8 industries, and auto-generated cross-channel 30/60/90 day strategy. Single HTML file, zero dependencies, runs entirely in the browser. Connects to Google Ads, GA4, GTM, Search Console, PageSpeed, Merchant Center, Meta, Microsoft Ads, and Semrush. ### URLs - Landing: https://googleadsagent.ai/tools/audit-engine/ - App: https://googleadsagent.ai/tools/audit-engine/app.html - Docs: https://googleadsagent.ai/tools/audit-engine/docs.html ### Repository - GitHub: https://github.com/itallstartedwithaidea/google-ai-agent-audit-engine - License: MIT - Architecture: Single HTML file, zero build step, zero backend ### 10 Audit Categories (250 Points) 1. Account Foundation & Settings — 25 points (1-25), Google Ads 2. Campaign Architecture & Structure — 30 points (26-55), Google Ads 3. Keyword & Search Term Strategy — 30 points (56-85), Google Ads + Search Console 4. Ad Creative & Messaging — 30 points (86-115), Google Ads 5. Bidding & Budget Strategy — 25 points (116-140), Google Ads 6. Audience Strategy & Data — 30 points (141-170), Google Ads + GA4 7. Landing Pages & Post-Click — 25 points (171-195), PageSpeed + Google Ads 8. Tracking & Measurement — 30 points (196-225), GA4 + GTM + Google Ads 9. Competitive & Market Intelligence — 15 points (226-240), Google Ads + Semrush 10. Cross-Channel Integration — 10 points (241-250), All platforms ### 9 MCP Service Connectors 1. Google Ads API — 220+ audit points, 12 MCP tools 2. GA4 Admin + Data API — 45+ points, 5 tools 3. GTM API — 15+ points, 3 tools 4. Search Console API — 20+ points, 3 tools 5. PageSpeed Insights API — 10+ points, 3 tools 6. Google Merchant Center — 8+ points 7. Meta Marketing API — 10+ points 8. Microsoft Ads API — 5+ points 9. Semrush / SpyFu API — 10+ points ### Scoring Methodology 0-4 scale with weight multipliers (1-3): - 0: Critical Fail — not implemented, causing harm (Days 1-7 emergency) - 1: Below Standard — partially implemented, significant gaps (Days 1-30 foundation) - 2: Meets Baseline — implemented but not optimized (Days 31-60 optimization) - 3: Best Practice — fully optimized per current standards (Days 61-90 maintain) - 4: Industry Leading — advanced implementation exceeding standards (Days 61-90 iterate) Account Health Index = (Sum of weighted scores) / (Sum of maximum weighted scores) × 100 ### Vertical Calibration Built-in guidance for: eCommerce, B2B/SaaS, Healthcare, Financial Services, Local Services, Education, Real Estate, Automotive ### Strategy Generation Auto-generated 30/60/90 day cross-channel roadmap: - Days 1-30: All items scored 0-1 (foundation fixes) - Days 31-60: All items scored 2 (optimization opportunities) - Days 61-90: Items scored 3-4 (maintenance and iteration) Every action traces to a specific audit item number. ### Export Formats JSON (full data for programmatic use), CSV (spreadsheet analysis), Markdown (reports) ### Security All data stays in browser. API keys in localStorage only. Direct API calls from browser to services. No intermediary server. --- ## Project: AI Agents Crash Course ### Overview A free, open-source 5-day crash course on building AI agents — from absolute zero to deploying multi-agent systems. Written by John Williams with 15+ years managing $48M+ in digital advertising. Every concept maps to a real component of googleadsagent.ai. Includes 5 playable games built through vibe coding, 5 Google/Kaggle white paper references, hands-on labs, self-assessments, and APA 7th Edition citations. ### URLs - Course Page: https://googleadsagent.ai/course/ - GitHub: https://github.com/itallstartedwithaidea/ai-agents-crash-course ### Curriculum - Day 0: Environment Setup (Claude, ChatGPT, Cursor, Kaggle, GitHub, Python) - Day 1: Introduction to AI Agents — Brain, Tools, Loop, ReAct pattern. Game: Tetris. - Day 2: Agent Tools & MCP — Tool-use cycle, Model Context Protocol, MCP architecture. Game: Zelda Adventure. - Day 3: Context Engineering — Six layers of context, scratchpad pattern, RAG, memory strategies. Game: Football (Tecmo Bowl). - Day 4: Agent Quality — Evaluation, observability, guardrails, LLM-as-a-Judge, CONFIRM protocol. Game: Super Mario Bros. - Day 5: Production & Multi-Agent — Prototype-to-production gap, A2A protocol, 6 sub-agents, UCP. Game: Duck Hunt + Capstone RPG. ### Learning Paths - Observer (executives, strategists): Concepts only, 2-3 hours/day. - Builder (marketers, analysts): Hands-on labs + games, 4-6 hours/day. - Architect (developers, engineers): Deep theory + production, 6-8 hours/day. ### googleadsagent.ai Through-Line Every course concept maps to a live component: - Brain = Claude (Opus 4.5 + Sonnet 4.5) - Tools = 28 Python API actions - MCP = Adapter layer (tool_executor.py) - Context = CEP Protocol + Session State Manager - Quality = Top-Down Reporting + CONFIRM write-safety - Multi-Agent = Simba, Nemo, Elsa, Aladdin, Moana, Baymax - Production = CLI, REST API, Docker, Python SDK ### Key References - Google/Kaggle: 5 White Papers on AI Agents (2024-2025) - Anthropic: Model Context Protocol (Nov 2024) - Google: Agent-to-Agent Protocol (Apr 2025) - Google: Universal Commerce Protocol at NRF 2026 (Jan 2026) - Yao et al.: ReAct paper (2022) - Karpathy: Vibe Coding (Feb 2025) --- ## Project: Business Discovery Engine ### Overview An open-source business discovery engine v6.1 that finds contacts, emails, social profiles, and company intelligence from 100% public data. Round-robin discovery across 5 states (54 cities), 65 business categories, 4 sources. Inline enrichment with 9 email extraction methods, MX verification, WHOIS business age scoring, social media extraction, crash recovery, and live Google Sheets dashboard. Built with Node.js and Puppeteer. ### URLs - Landing: https://googleadsagent.ai/tools/business-discovery/ - Docs: https://googleadsagent.ai/tools/business-discovery/docs.html ### Repository - GitHub: https://github.com/itallstartedwithaidea/business-discovery-engine - Engine: engine.js (1,763 lines, single file) - License: MIT - Version: 6.1.0 ### Architecture: Round-Robin + Inline Enrichment #### v6.1 Key Changes - INLINE ENRICHMENT: Data flows into Sheets continuously as each chunk completes - ROUND-ROBIN: Shuffles states × sources × cities within each category for natural distribution - 1,000 per CATEGORY (not per state) — 65,000 max total across all states - Chunk rotation: rotate to next category every 250 discoveries (configurable) - Global dedup — zero duplicates across all states/sources - Single command: --state ALL runs everything - Per-category checkpoint + crash recovery #### Discovery Pipeline (v6.1) For each category: 1. DISCOVER 250 businesses (shuffled states × sources × cities, global dedup on every insert) 2. FIND WEBSITES (DuckDuckGo + Google fallback) 3. ENRICH each business (visit website → contacts → social → WHOIS → infer → MX verify) 4. PUSH TO SHEETS (immediately, batches of 10) → Save checkpoint → Rotate to next category → Repeat #### 4 Discovery Sources 1. **Yellow Pages** — Puppeteer + stealth plugin, 3 pages per category/city 2. **Yelp** — Smart auto-skip after 5 consecutive blocks, stealth scrolling 3. **BBB** — React SPA rendered via headless Chrome 4. **Google Maps** — Aria-label extraction, /maps/search/ URLs #### 9 Email Extraction Methods 1. JSON-LD / Schema.org structured data 2. Mailto link extraction 3. Regex on page text 4. Meta tags (author, contact) 5. VCard / hCard microformats 6. Staff directory parsing 7. WHOIS/RDAP registrant data 8. Email pattern inference 9. MX verification #### 65 Business Categories Local Services (30), Retail & Ecommerce (10), Food & Beverage (5), Health & Wellness (6), Professional Services (6), Home Services (8) #### 18-Column Output First Name, Last Name, Email, Title, Company Name, Location, Website, Phone, Facebook, Instagram, LinkedIn, Twitter/X, Source, Confidence, Biz Age, Year Founded, Industry, Date --- ## Author & Content Properties ### John Williams - Senior Paid Media Specialist at Seer Interactive - 15+ years managing $48M+ in digital advertising - Platforms: Google Ads, Meta, Microsoft, Amazon, TikTok, LinkedIn, Pinterest - Previous: NortonLifeLock (192% YoY growth), Avast, Gen Digital, Farmers Insurance - Conference speaker: Hero Conf 2025 San Diego (AI in advertising) - Main website: https://itallstartedwithaidea.com - Agent tools: https://googleadsagent.ai ### Websites - https://googleadsagent.ai — AI-powered Google Ads tools (this site) - https://itallstartedwithaidea.com — Consultancy, blogs, paid media resources ### Social Profiles - LinkedIn: https://www.linkedin.com/in/johnmichaelwilliams - X / Twitter: https://x.com/_johnmwilliams - Instagram: https://www.instagram.com/_johnmwilliams/ - Substack: https://substack.com/@itallstartedwithaidea (15K+ subscribers) - Reddit: https://www.reddit.com/r/allthingsadvertising/ ### GitHub Repositories - https://github.com/itallstartedwithaidea/google-ads-api-agent — 28-action AI agent (MIT) - https://github.com/itallstartedwithaidea/googleadsagent-site — This website source - https://github.com/itallstartedwithaidea/google-ai-agent-audit-engine — 250-point audit engine (MIT) - https://github.com/itallstartedwithaidea/business-discovery-engine — Lead discovery engine (MIT) - https://github.com/itallstartedwithaidea — Organization profile (scripts, templates, tools) --- ## Blog Articles — itallstartedwithaidea.com All published at https://itallstartedwithaidea.com/blogs/ 1. [The Dark Side of AI Overload in Campaign Management](https://itallstartedwithaidea.com/the-dark-side-of-ai-overload-in-campaign-management/) — Analysis of AI tool proliferation risks in PPC management. 2. [The Future of Automated Campaign Types in PPC and Social Media](https://itallstartedwithaidea.com/the-future-of-automated-campaign-types-in-ppc-and-social-media/) — Forward-looking view on automation trends across advertising platforms. 3. [Truths in AI Search Has A Citation Problem](https://itallstartedwithaidea.com/truths-in-ai-search-has-a-citation-problem/) — AI search engines and attribution challenges for content creators. 4. [Doing Ads on a Small Budget: A Strategic Guide](https://itallstartedwithaidea.com/doing-ads-on-a-small-budget-a-strategic-guide/) — Practical strategies for maximizing limited PPC budgets. 5. [Unlocking Accurate Google Ads Impression Share with a Simple Script](https://itallstartedwithaidea.com/unlocking-accurate-google-ads-impression-share-with-a-simple-script/) — Technical walkthrough of impression share tracking script. 6. [Rethinking Ads & CPC Strategies in 2025](https://itallstartedwithaidea.com/rethinking-ads-cpc-strategies-in-2025/) — Evolution from manual to AI-driven bidding. 7. [Balancing Visionary Leadership with AI-Driven Decision-Making [White Paper]](https://itallstartedwithaidea.com/balancing-visionary-leadership-with-ai-driven-decision-making-white-paper/) — White paper on AI integration in marketing leadership. 8. [Guide 2025: From Strategy to Execution](https://itallstartedwithaidea.com/guide-2025-from-strategy-to-execution/) — Comprehensive digital marketing execution guide. 9. [Free Google Ads Headline & Description Generator](https://itallstartedwithaidea.com/free-google-ads-headline-description-generator/) — How to use the AI ad copy generator. 10. [Google Ads Campaign Management: From Single Sheet to Multi-Account Scaling](https://itallstartedwithaidea.com/google-ads-campaign-management-from-single-sheet-to-multi-account-scaling/) — Scaling Google Ads across 1,000+ accounts. 11. [Maximizing the Power of Customer Lists and First Party Data in Google Ads](https://itallstartedwithaidea.com/maximizing-the-power-of-customer-lists-and-first-party-data-in-google-ads/) — First-party data strategies for Customer Match and targeting. 12. [PMAX: Audiences To Test or Not To Test](https://itallstartedwithaidea.com/pmax-audiences-to-test-or-not-to-test/) — Performance Max audience signal testing methodology. 13. [Federal Appeals Court Upholds TikTok Ban Law](https://itallstartedwithaidea.com/federal-appeals-court-upholds-tiktok-ban-law/) — Impact on marketers and businesses. 14. [Budget Projection & Performance Ads Script](https://itallstartedwithaidea.com/budget-projection-performance-ads-script/) — Automated budget forecasting for Google Ads. 15. [MarketingDashboard: A Powerful Tool for Optimizing Advertising Campaigns](https://itallstartedwithaidea.com/marketingdashboard-a-powerful-tool-for-optimizing-advertising-campaigns/) — Dashboard guide for campaign optimization. 16. [Navigating Digital Marketing in 2025](https://itallstartedwithaidea.com/navigating-digital-marketing-in-2025/) — Professional and personal growth guide. 17. [Have You Struggled with Broad Match on Google Ads?](https://itallstartedwithaidea.com/have-you-struggled-with-broad-match-on-google-ads/) — Turning broad match into a competitive advantage. 18. [I Analyzed 1,000 Online Stores](https://itallstartedwithaidea.com/i-analyzed-1000-online-stores/) — E-commerce analysis separating winners from losers. 19. [Are You Measuring What Matters?](https://itallstartedwithaidea.com/are-you-measuring-what-matters/) — Measurement framework for digital advertising. 20. [29 Google Ads Automated Features and Practices to Approach with Caution](https://itallstartedwithaidea.com/29-google-ads-automated-features-and-practices-to-approach-with-caution/) — Risks of Google Ads automation defaults. --- ## LinkedIn Articles & Newsletters Published on LinkedIn Pulse — https://www.linkedin.com/in/johnmichaelwilliams/recent-activity/newsletter/ 1. [Mastering Google Ads and LinkedIn Ads](https://www.linkedin.com/pulse/mastering-google-ads-linkedin-john-williams--3umrc) — Cross-platform advertising strategies with case studies. 2. [Google Ads Campaign Management: From Single Sheet to Multi-Account Scaling](https://www.linkedin.com/pulse/google-ads-campaign-management-from-single-sheet-john-williams--gwcwc) — Automation and scaling for agency-level management. 3. [Have You Struggled with Broad Match on Google Ads?](https://www.linkedin.com/pulse/have-you-struggled-broad-match-google-ads-heres-how-i-john-williams--i3owc) — Practical broad match optimization guide. 4. [Navigating the Google Ad Representative](https://www.linkedin.com/pulse/navigating-google-ad-representative-john-williams--s5q1c) — Working effectively with Google Ads reps. 5. [Rethinking Ads & CPC Strategies in 2025](https://www.linkedin.com/pulse/rethinking-ads-cpc-strategies-2025-john-williams--ezupc) — AI-driven bidding evolution. 6. [Google Ads Free Keywords — Official Guide](https://www.linkedin.com/pulse/google-ads-free-keywords-its-official-john-williams--4b2qc/) — Keyword optimization and cost reduction. --- ## Substack - Profile: https://substack.com/@itallstartedwithaidea - Newsletter: https://itallstartedwithaidea.substack.com - Subscribers: 15,000+ - Topics: Paid media, AI in advertising, marketing automation, Google Ads strategy --- ## Reddit Community - Subreddit: https://www.reddit.com/r/allthingsadvertising/ — Community for advertising professionals - [MCP Server + Google Ads + Meta Ads with AI](https://www.reddit.com/r/PPC/comments/1r30hsz/mcp_server_google_ads_meta_ads_with_ai/) — r/PPC discussion on AI-powered ads management - [After Years in Ads, the Future Isn't Dashboards — Intent-to-API](https://www.reddit.com/r/googleads/comments/1r3q6r2/after_years_in_ads_i_think_the_future_isnt/) — r/googleads post on Intent-to-API paradigm --- ## Featured & Press - [Feedonomics: Tips to Improve Google Ads Performance](https://feedonomics.com/digital-marketing-tips-from-the-pros/tips-to-help-improve-your-google-ads-performance-part-2/) — Featured expert tips - [Hero Conf 2025 — San Diego (Speaking)](https://paidsearch.org/event/hero-conf-2025-san-diego/) — Conference talk on AI applications in advertising --- ## Free Resources & Tools on itallstartedwithaidea.com - [Paid Search Strategy](https://itallstartedwithaidea.com/paid-search/) — Comprehensive paid search playbook - [Display Ads Guide](https://itallstartedwithaidea.com/display-ads/) — Display advertising strategy - [Social Ads Guide](https://itallstartedwithaidea.com/social-ads/) — Social media advertising strategy - [Video Ads Guide](https://itallstartedwithaidea.com/video-ads/) — Video advertising strategy - [Top PPC Questions](https://itallstartedwithaidea.com/top-ppc-questions/) — Common PPC questions answered - [AI Discovery Workspace](https://itallstartedwithaidea.com/ai-discovery-workspace-for-digital-marketing/) — AI-powered marketing workspace - [GPT Ad Generator](https://itallstartedwithaidea.com/gpt-ad-generator/) — AI ad copy generation tool - [Free UTM/URL Builder](https://docs.google.com/spreadsheets/d/1R1Oj4GoPWLWzxnWChmy4rLv-ROUhdKlRBMVGPj6EHg4/) — Campaign URL builder spreadsheet - [Google Ads Account Grader Script](https://github.com/itallstartedwithaidea/itallstartedwithaidea_google_ads_account_grader/) — Automated account grading - [Shopping Campaign Template](https://docs.google.com/spreadsheets/d/1WqkzlGfvL_B2sRhyhQUjtejd771FlZXuXsw8ovOMrXE/) — Shopping feed template - [Video Ads Script Template](https://docs.google.com/spreadsheets/d/1cqE8xaqK12Xmf6TwLgVk0c7Pz8dlLWJMq_gnbEOei6Y/) — Video campaign builder - [PPC Audit Sheet](https://docs.google.com/spreadsheets/d/1mcHZeQ1ncW7AWZtpWk3W8iKmdfDxfstMwppFWccXvr8/) — Google Ads audit spreadsheet - [Digital Marketing Services](https://itallstartedwithaidea.com/digital-marketing-services/) — Consulting services - [Audit Details & NDA](https://itallstartedwithaidea.com/audit-details/) — PPC audit process and NDA --- ## Site Structure ``` googleadsagent.ai/ ├── index.html Homepage (Agent overview) ├── llms.txt LLM-readable project summary ├── llms-full.txt This file — full technical reference ├── sitemap.xml XML sitemap ├── robots.txt Crawler directives ├── sitemap.xml Sitemap index (core + service sitemaps) ├── sitemap-core.xml Core pages sitemap (14 pages) ├── sitemaps/ │ └── sitemap-services-{1..44}.xml Service page sitemaps (1,971,336 URLs) ├── functions/ │ └── services/[[catchall]].js Cloudflare Pages Function — edge-renders service pages ├── services/ │ ├── template.html Static service page template │ ├── template-edge.html Edge-rendered template (dark/light mode, Web3Forms) │ ├── build.js Static page generator │ ├── data/ │ │ ├── services.json 154 service verticals across 15 categories with pain points │ │ └── cities.json 18,744 US cities with hooks and market insights │ └── {city-slug}/ Pre-built static pages (35 initial cities) │ └── {service-slug}/index.html Individual service landing page ├── tools/ │ ├── google-ads-builder/ │ │ ├── index.html Builder landing page │ │ ├── app.html Builder application │ │ └── docs.html Builder documentation │ ├── auditor/ │ │ ├── index.html Analytics Auditor landing page │ │ ├── app.html Analytics Auditor application │ │ └── docs.html Analytics Auditor documentation │ ├── audit-engine/ │ │ ├── index.html 250-Point Audit Engine landing page │ │ ├── app.html 250-Point Audit Engine application │ │ └── docs.html 250-Point Audit Engine documentation │ └── business-discovery/ │ ├── index.html Discovery Engine landing page │ └── docs.html Discovery Engine documentation ``` --- ## Programmatic SEO — Service Landing Pages ### Overview 2,800,000+ unique landing pages covering 154 service verticals across 15 categories and 18,744 US cities. Each page is edge-rendered at the Cloudflare network edge via a Pages Function, providing near-instant load times worldwide. ### Architecture - **Edge Function**: `functions/services/[[catchall]].js` — Cloudflare Pages Function that handles all `/services/{city}/{service}/` routes. Contains embedded city data, service data, and the full HTML template (~600KB compiled). - **Static Fallback**: Pre-built HTML pages for 35 major US cities in `services/{city-slug}/`. - **Template**: Each page includes SEO meta tags, Schema.org ProfessionalService + Organization + Person + WebSite (SearchAction) + BreadcrumbList + FAQPage markup (V2 complete schema stack with @id entity linking), local market intelligence, seasonal demand data, CPC benchmarks, climate/economic signals, 6 pain-point cards, solution overview, 12 capability items, pricing section, about section with trust signals, testimonials, and a Web3Forms lead capture form. - **Sitemaps**: 44 partitioned XML sitemaps, each containing up to 50,000 URLs (Google's per-sitemap limit). Referenced from the sitemap index at `/sitemap.xml`. - **Indexing**: All pages indexed — zero noindex tags. robots meta: `index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1`. X-Robots-Tag header: `index, follow`. stale-while-revalidate caching. - **IndexNow**: `/api/indexnow` endpoint for batch URL submission to Bing, Yandex, Naver, and Seznam (up to 10,000 URLs per POST). ### Companion & Context Pages - **Page Type B — Local Guide** (`/services/{city}/{service}/local-guide/`): Local competitive intelligence page with real agency data (SearchAPI Google Maps integration), expert YouTube video embeds (category-matched from curated channel library), Google Trends data (state-level with rising queries), pricing comparison (agency rate vs John's $500/mo flat fee), CTA form, and cross-links to landing page and community insights. Available for all 1.97M service/city combinations. Full schema stack: Article, VideoObject, BreadcrumbList (5-level), Organization, Person, WebSite. - **Page Type C — Community Insights** (`/services/{city}/{service}/community-insights/`): Aggregated community voice from Reddit (r/PPC, r/GoogleAds, r/smallbusiness), Quora, and local forums with expert commentary from John. Available for Tier 1-2 markets only (metro population 100K+, ~800 markets). Schema: Article, BreadcrumbList, Organization, Person, WebSite. - **Three-Page Content Cluster**: Each service/city combination forms a topical authority cluster: Page A (Landing) + Page B (Local Guide) + Page C (Community Insights, Tier 1-2 only). Cross-links between all three pages with `rel="related"`. - **SearchAPI Integration**: Google Maps (agency data), Google Trends (search interest + rising queries), YouTube (expert videos). Data cached in Cloudflare KV with 30-day TTL. Graceful fallback when API data unavailable. ### Service Verticals (154 across 15 categories) **Home Services** (40): Plumber, HVAC, Electrician, Roofer, Landscaping, General Contractor, Pest Control, and 33 more. **Healthcare** (21): Dentist, Chiropractor, Dermatologist, Primary Care, Plastic Surgeon, and 16 more. **Legal** (17): Personal Injury, Criminal, Family, DUI, Estate, Immigration, and 11 more. **Education** (9): Preschool, Tutor, Driving Instructor, and 6 more. **Beauty** (6): Hair Salon, Nail Salon, Tattoo Studio, and 3 more. **Professional** (7): Financial Planning, Real Estate, Tax Services, and 4 more. **Automotive** (5): Auto Repair, Auto Body, Car Wash, Tire Shop, Towing. **Pet Services** (5): Veterinarian, Pet Grooming, Pet Boarding, Pet Training, Pet Adoption. **Retail** (6): Jewelry Store, Clothing Store, Cell Phone Repair, and 3 more. **Restaurants & Food** (7): Restaurant, Catering, Bakery, Food Truck, Bar & Pub, Coffee Shop, Meal Prep. **Fitness & Wellness** (7): Gym, CrossFit, Martial Arts, Pilates, Med Spa, IV Therapy, Nutrition Coaching. **Financial Services** (6): Mortgage Broker, Credit Repair, Debt Consolidation, Wealth Management, Bookkeeper, Payroll. **Senior Care** (6): Assisted Living, Home Health Aide, Memory Care, Hospice, Senior Transportation, Adult Daycare. **Events & Entertainment** (6): Wedding Venue, Photographer, DJ, Event Planner, Party Rental, Florist. **Tech Services** (6): IT Support, Managed Services, Web Design, Cybersecurity, App Development, Data Recovery. ### Cities (18,744) Every US city and town with population data, state mapping, local market hooks, and market insight narratives. 35 cities have pre-built static pages as fallbacks; all 18,744 are served by the edge function. ### Offer Structure - Free 30-day Google Ads audit and strategy - $500/month flat fee after trial (no percentage of spend, no contract) - AI-powered management with 28 API tools - Human approval required for all write operations --- ## Total Content Inventory ### googleadsagent.ai core pages: 14 ### Service landing pages: 1,971,336 ### Ecommerce landing pages: 374,880 ### Service sitemaps: 44 ### Ecommerce sitemaps: 9 ### itallstartedwithaidea.com blog posts: 20+ ### LinkedIn articles/newsletters: 6+ ### Substack: 15K+ subscriber newsletter ### Reddit threads: 3+ ### GitHub repositories: 5 ### Free Google Sheets tools: 4 ### Social profiles: 5 (LinkedIn, X, Instagram, Substack, Reddit) ### Conference appearances: 1 (Hero Conf 2025) ### Press features: 1 (Feedonomics)