google-ads-scripts

Process

1. Identify the repetitive task — What are you doing manually that a script could handle?
2. Match to script category — Use the decision tree below
3. Select specific script — Read references/scripts-catalog.md for detailed options
4. Understand prerequisites — API access, spreadsheet setup, email notifications
5. Install and configure — Follow the standard installation process
6. Test in preview mode — Always preview before authorizing
7. Schedule and monitor — Set appropriate frequency, check logs regularly

Read references/scripts-catalog.md for the complete catalog of 50+ top scripts with sources, use cases, and implementation notes.

Script Category Decision Tree

What problem are you solving?

Top Categories & Use Cases

1. Search Term / N-Gram Analysis

Purpose: Mine search query reports to find negative keyword candidates and promotion opportunities at scale.

Top pick: Brainlabs Search Query Mining Script (updated for GAQL by Nils Rooijmans, March 2025)

What it does:

• Breaks queries into 1-grams, 2-grams, 3-grams
• Aggregates performance by n-gram
• Highlights high-spend / zero-conversion patterns
• checkNegatives parameter: verifies new negatives don't block existing keywords

When to run: Weekly for new campaigns, bi-weekly for stable ones.

Output: Google Sheet with n-gram breakdown, sorted by spend and CPA.

2. Bid Management

Purpose: Adjust bids automatically based on performance patterns or external signals.

Common scripts:

• Day-of-week bid modifiers — Apply bid adjustments based on historical day-of-week conversion rates
• Hour-of-day bid modifiers — Same for hour of day
• Weather-based bid adjusters — Modify bids based on local weather (umbrella sales → increase on rainy days)
• Impression share targeting scripts — Dynamically adjust bids to hit target impression share

Warning: These scripts predate Smart Bidding. For accounts running tCPA/tROAS, most bid scripts are unnecessary — Smart Bidding handles these optimizations automatically. Use bid scripts mainly for:

• Accounts with <30 conversions/month (pre-Smart Bidding)
• Specific signals Smart Bidding doesn't know (weather, inventory, external factors)

3. Budget Pacing & Redistribution

Purpose: Prevent overspend/underspend. Automatically shift budget between campaigns.

Common scripts:

• Budget pacing monitors — Alert when a campaign will overspend or underspend by month-end
• Budget redistribution — Shift unused budget from underperformers to high-performers
• Seasonal budget automation — Adjust budgets based on expected seasonal demand

ECPC deprecation note (March 2025): Some older budget scripts reference ECPC. If you encounter one, update or replace — ECPC is gone.

4. Performance Monitoring & Anomaly Detection

Purpose: Catch problems before they waste money.

Top scripts:

• Anomaly detection (Frederick Vallaeys) — Alerts on sudden metric changes (CTR, CPC, conversion rate deviations from baseline)
• Zero-impression keyword pause — Pause keywords with zero impressions over X days
• Quality Score tracking — Historical QS tracking (Google doesn't store QS history natively)
• Broken landing page URL monitor — Tests all landing page URLs, alerts on 404s or slow loads
• Emergency stop button — Pauses account if website is down (integrates with uptime monitors)

When to run: Daily for anomaly detection, weekly for URL checks and QS tracking.

5. Reporting Automation

Purpose: Generate client-ready reports without manual grind.

Common scripts:

• Monthly presentation deck generator (Optmyzr-style)
• Client performance heat maps (Kratu)
• Hourly performance trend heat maps (Daniel Gilbert)
• Change history reports
• Custom metric dashboards

6. Ecommerce-Specific

Purpose: Profit-based optimization beyond ROAS.

Top pick: Jack Felsted's Revenue Maximizer Tiering

What it does:

• Tiers products by gross profit margin using custom labels
• Applies different tROAS targets per tier
• High-margin products get lower tROAS target (more volume), low-margin get higher (tighter efficiency)
• 7/14/28/90-day ROI lookback for dynamic tier updates

Requires: Merchant Center feed with custom labels (use the google-merchant-center skill to set these up).

7. Ad Copy Analysis

Purpose: Find winning language patterns in ads.

Top pick: Frederick Vallaeys' RSA n-gram analyzer

What it does: Analyzes which words/phrases in your ad copy correlate with higher CTR and conversion rates. Applies n-gram analysis methodology to ad copy instead of search terms.

8. Competitive Monitoring

Purpose: Track competitor movement in auctions.

Common scripts:

• Auction Insights trend tracker — Stores historical impression share, overlap rate, position above rate
• Competitor ad copy change alerts (requires Google Ads Transparency Center)

Installation Process (Standard)

Every Google Ads script follows this installation pattern:

Always preview before running. Scripts that make changes (pause keywords, adjust bids, change budgets) can cause damage if misconfigured.

Script Selection Framework

Before installing a script, answer these questions:

Scheduling Guidelines

Don't over-schedule. More frequent ≠ better. Some scripts have API rate limits or cost real time/money to run.

Script Libraries & Sources

Output Format

When recommending scripts, produce this deliverable:

## Google Ads Script Recommendations

### Business Problem
[What the user is trying to solve or automate]

### Recommended Scripts

#### Script 1: [Name]
- **Source:** [Author/organization]
- **Purpose:** [What it does]
- **Why this script:** [How it solves the user's specific problem]
- **Prerequisites:** [API access, spreadsheets, email setup]
- **Configuration variables:** [Key settings to customize]
- **Schedule:** [Recommended frequency]
- **Expected outcome:** [What you'll see after it runs]

#### Script 2: [Name]
[Same structure]

### Installation Order
1. [First script to install and why]
2. [Second script]

### Monitoring Plan
- Check logs after [time period]
- Success criteria: [what good looks like]
- Warning signs: [what to watch for]

### Smart Bidding Compatibility
[Note which scripts are redundant if using Smart Bidding, and which remain useful]

Example

Input: "I manage 8 Google Ads accounts for ecommerce clients. Spending $4K-$30K/month each. Most are on PMax + Search with Smart Bidding. I'm spending hours every week manually checking search terms, monitoring for anomalies, and building reports. What scripts should I set up?"

Output:

Google Ads Script Recommendations

Business Problem

Agency workload from manual search term review, anomaly monitoring, and reporting across 8 accounts. Time savings from automation compounds across multiple accounts.

Recommended Scripts

Script 1: Brainlabs Search Query Mining (Nils Rooijmans GAQL update)

• Source: Nils Rooijmans (updated March 2025 for GAQL)
• Purpose: Automated n-gram analysis on search term reports. Identifies high-spend / zero-conversion patterns and promotion candidates
• Why this script: Replaces manual search term review across 8 accounts. Biggest immediate time saver
• Prerequisites: Google Sheet for output, email for notifications
• Configuration variables: Date range (last 30 days recommended), spend threshold ($50+), checkNegatives parameter (set to true to verify no conflicts with existing keywords)
• Schedule: Weekly for new campaigns, bi-weekly for stable ones. Run Sunday night so Monday morning starts with fresh data
• Expected outcome: Sheet per account showing n-gram waste candidates + promotion opportunities

Script 2: Anomaly Detection (Frederick Vallaeys)

• Source: Frederick Vallaeys (Optmyzr / Search Engine Land)
• Purpose: Alerts on sudden metric changes (CTR, CPC, conversion rate, spend deviations from baseline)
• Why this script: Across 8 accounts, catching issues early prevents wasted spend. Replaces manual daily pulse checks
• Prerequisites: Email notification setup, baseline calculation period (14-30 days)
• Configuration variables: Deviation thresholds (e.g., >20% from 7-day average), metrics to monitor, alert recipients
• Schedule: Daily, early morning (catches overnight issues)
• Expected outcome: Email alert only when anomaly detected. Most days = silent. Action days = immediate visibility

Script 3: Jack Felsted's Revenue Maximizer Tiering

• Source: Jack Felsted
• Purpose: Automatically tiers products by gross profit margin using custom labels. Applies differentiated tROAS targets per tier
• Why this script: Ecommerce clients need profit-based bidding (POAS > ROAS). High-margin products tolerate lower tROAS for more volume
• Prerequisites: Merchant Center feed with cost/margin data, custom labels set up (use the google-merchant-center skill)
• Configuration variables: Margin thresholds per tier, tROAS targets per tier, lookback period (7/14/28/90-day)
• Schedule: Weekly
• Expected outcome: Products re-tiered weekly based on trailing performance, bids automatically adjusted

Script 4: Broken Landing Page URL Monitor

• Source: Google Developers / community (multiple open-source versions)
• Purpose: Tests all active landing page URLs. Alerts on 404s, timeouts, slow loads
• Why this script: Broken URLs burn budget silently. Across 8 accounts, this catches issues within 24 hours
• Prerequisites: Email notification setup
• Configuration variables: Timeout threshold (10 sec), alert recipients, ignored URLs
• Schedule: Weekly
• Expected outcome: Alert only when broken URL found

Script 5: Monthly Reporting Deck Generator (Optmyzr-style)

• Source: Optmyzr has a paid version; several open-source community versions exist
• Purpose: Pulls performance data and generates monthly client reports
• Why this script: Agency reporting time sink. 8 accounts × manual reporting = many hours per month
• Prerequisites: Google Slides template, data field mapping
• Configuration variables: Template slides, metrics to include, date range
• Schedule: Monthly (1st of month for previous month data)
• Expected outcome: Draft deck per account, ready for analyst review and narrative

Installation Order

1. Week 1: Anomaly Detection — Install first. Set to notification-only for 7 days. Tighten thresholds after seeing baseline noise
2. Week 1: Broken URL Monitor — Install concurrently. Low risk, high value
3. Week 2: Brainlabs Search Query Mining — Install once anomaly detection is stable. This requires review/action, so don't stack it until you can manage the output
4. Week 3: Revenue Maximizer — Requires Merchant Center custom label setup first. Do that using the google-merchant-center skill, then install this script
5. Week 4: Reporting Deck Generator — Install last. Biggest customization effort but runs monthly so not urgent

Monitoring Plan

• Daily: Check anomaly detection email alerts
• Weekly: Review search query mining sheet, URL monitor output
• Monthly: Review reporting deck output, tune thresholds based on false positives/negatives
• Success criteria: Time spent on manual tasks drops by 50%+ within 30 days. Time to catch issues drops from days to hours
• Warning signs: If anomaly detection alerts too often → raise threshold. If search query mining is flagging wrong n-grams → tighten minimum spend threshold

Smart Bidding Compatibility

• Compatible (use these): Search query mining, anomaly detection, URL monitor, reporting, Revenue Maximizer (uses Smart Bidding targets as inputs)
• Redundant with Smart Bidding (skip): Day-of-week bid modifiers, hour-of-day bid modifiers, impression share bid targeting — Smart Bidding handles these natively with tCPA/tROAS
• Still useful: Weather-based bidding (Smart Bidding doesn't know weather), inventory-based bid adjustments (needs external data)

Guidelines

• Don't install scripts that duplicate Smart Bidding. Most bid management scripts were built before Smart Bidding existed. If the account runs tCPA/tROAS, skip day-of-week, hour-of-day, and impression share bid scripts.
• Don't skip preview mode. Always run in preview before authorizing. Scripts that pause keywords or change bids can cause damage if misconfigured.
• Don't chain scripts without understanding dependencies. If a search term mining script creates negatives and a QS tracker depends on keyword history, adding negatives can break QS data. Think through interactions.
• Don't run scripts more often than needed. Daily anomaly detection is useful. Daily search term mining is overkill and may hit API limits.
• Don't use stale scripts. Scripts that reference ECPC (deprecated March 2025), older GAQL syntax, or deprecated Google Ads API versions will break. Check publication dates and look for GAQL-updated versions (many were updated in 2024-2025).
• Don't ignore the logs. Scripts fail silently sometimes. Check logs weekly, especially after Google Ads API updates.
• Don't authorize scripts you don't understand. If the code is obfuscated or unclear, don't run it. Scripts have full account access.
• Cross-references: For search term strategy that informs n-gram scripts, use the google-ads-keyword-engine skill. For Merchant Center setup required by Revenue Maximizer, use the google-merchant-center skill. For account audits that identify automation opportunities, use the google-ads-audit skill. For ongoing optimization, use the google-ads-optimizer skill.
• Confidence: Script library URLs and maintainer information can change. For the most current version of any script, search the author's current website/blog rather than relying on older GitHub repos. Read references/scripts-catalog.md for the full categorized catalog.