Google Ads API Design Document

Quarry Rentals - Internal Advertising Performance System

Company Name

Quarry Rentals (ONeill Media LLC)

Business Model

Quarry Rentals operates a dumpster and portable sanitation rental business serving Southern California. We provide temporary waste management solutions to contractors, homeowners, and businesses through our website quarryrents.com.

We use Google Ads to generate leads for rental inquiries, primarily through:

• Phone call conversions
• Online quote request forms
• Direct website inquiries

We only advertise for our own business (quarryrents.com) and do not manage advertising for any other companies or clients.

Tool Access/Use

Who Will Use This Tool

This API tool will be used exclusively by internal employees at Quarry Rentals for:

• Viewing advertising performance reports
• Analyzing keyword effectiveness and ROI
• Identifying optimization opportunities
• Tracking ad spend vs. customer acquisition

Tool Functionality

Our internal system will provide:

1. Reporting Dashboard - Internal web interface showing:

   • Daily/weekly/monthly ad spend by campaign and location
   • Keyword performance metrics (spend, clicks, impressions, conversions)
   • Cost-per-acquisition analysis
   • Geographic performance breakdown (Los Angeles, Orange County, etc.)

2. AI-Powered Insights - Automated analysis to identify:

   • Underperforming keywords that should be added as negatives
   • High-cost low-conversion keywords
   • Budget reallocation recommendations
   • Seasonal trends and opportunities

3. Automated Sync - Daily synchronization script that:

   • Pulls campaign performance data into our internal database
   • Updates historical tracking for trend analysis
   • Generates weekly performance summary reports

Data Access

• All data pulled from the API will be stored in our internal PostgreSQL database
• Access is restricted to authorized employees only
• No external parties will have direct access to the tool
• Reports may be shared internally with management via PDF/email

Tool Design

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     Google Ads API                          │
└────────────────────────┬────────────────────────────────────┘
                         │
                         │ OAuth 2.0 Authentication
                         │ Daily API Calls (backfill-capable)
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│              Quarry Rentals Rails Application               │
│                                                               │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Google Ads Sync Service (Daily Scheduled Job)       │  │
│  │  - Fetches campaign/keyword/geo performance          │  │
│  │  - Idempotent upserts (refresh if re-run)            │  │
│  │  - Supports 30-60 day backfill                       │  │
│  │  - Triggers AI analysis                              │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                               │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  PostgreSQL Database                                  │  │
│  │  - google_ads_campaigns                               │  │
│  │  - google_ads_keywords                                │  │
│  │  - google_ads_daily_reports                           │  │
│  │  - companies (customer data)                          │  │
│  │  - orders (sales data)                                │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                               │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Admin Dashboard (Internal Web UI)                    │  │
│  │  - Campaign performance & anomalies                   │  │
│  │  - Keyword analysis & negatives                       │  │
│  │  - Geo performance                                    │  │
│  │  - AI recommendations display                         │  │
│  │  - ROI tracking (ad spend vs revenue)                 │  │
│  │  - Manual sync & date-range backfill                  │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                               │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │  Authorized Staff   │
              │  (Internal Access)  │
              └─────────────────────┘

Data Flow

1. Daily Data Sync (Automated Background Job)

   • Runs once daily at 2:00 AM Pacific Time
   • Pulls previous day's performance metrics from Google Ads API
   • Supports configurable backfill window (e.g., last 30-60 days on demand)
   • Stores in internal database with idempotent upserts for accurate reruns

2. User-Initiated Reports (On-Demand)

   • Staff access admin dashboard through authenticated web interface
   • View pre-calculated metrics from internal database
   • Request AI analysis for specific campaigns or time periods

3. Weekly AI Analysis (Automated)

   • Analyzes 7-day performance trends
   • Identifies optimization opportunities
   • Generates summary report delivered via email to management

Data Security

• All API credentials stored as encrypted environment variables
• OAuth tokens refreshed automatically using secure token management
• Database access restricted to application server only
• Admin dashboard requires authentication (username/password)
• All connections use SSL/TLS encryption
• OAuth dashboard shows token freshness/login-customer ID to validate connectivity

API Services Called

We will use the following Google Ads API services:

1. GoogleAdsService.SearchStream

Purpose: Retrieve campaign and keyword performance data

Resources Accessed:

• campaign - Campaign names, IDs, status, location targets
• ad_group - Ad group names and IDs
• ad_group_criterion (keywords) - Keyword text, match type, performance
• metrics - Cost, clicks, impressions, conversions, CTR

Query Example:

SELECT
  campaign.id,
  campaign.name,
  ad_group.id,
  ad_group.name,
  ad_group_criterion.keyword.text,
  metrics.cost_micros,
  metrics.clicks,
  metrics.impressions,
  metrics.conversions
FROM keyword_view
WHERE segments.date DURING LAST_7_DAYS
ORDER BY metrics.cost_micros DESC

Call Frequency: Once daily

2. Customer Resource

Purpose: Retrieve account-level information and settings

Data Accessed:

• Customer ID
• Account currency
• Time zone

Call Frequency: Once per session (cached)

3. Geographic View

Purpose: Analyze performance by location (Los Angeles, Orange County, etc.)

Data Accessed:

• Geographic location names
• Performance metrics by location

Call Frequency: Once daily

API Call Volume Estimate

• Daily Scheduled Sync: ~5-10 API calls per day

  • 1 call for campaign data
  • 1 call for keyword performance
  • 1 call for geographic data
  • 1-2 calls for account metadata

• On-Demand Reports: ~0-5 API calls per day

  • Triggered by user requests for updated data
  • Most reports served from cached database

Total Estimated API Calls: 10-15 per day

Use Cases

Use Case 1: Weekly Performance Review

Scenario: Management reviews last week's advertising performance every Monday.

Process:

1. System automatically pulls previous week's data overnight
2. AI analyzes performance and identifies trends
3. Dashboard displays:
   • Total spend by campaign
   • Cost per lead/conversion
   • New customers acquired
   • ROI calculation (revenue vs ad spend)
4. Management reviews dashboard and makes budget decisions

Use Case 2: Keyword Optimization

Scenario: Identify keywords that are wasting budget.

Process:

1. User accesses "Keyword Analysis" dashboard
2. System displays keywords sorted by:
   • High spend, zero conversions → negative keyword candidates
   • High cost-per-click, low relevance
   • Geographic mismatch (spending in areas we don't serve)
3. AI provides recommendations: "Add 'dumpster rental phoenix' as negative keyword - $450 spent, no conversions"
4. User reviews and implements changes in Google Ads interface

Use Case 3: Budget Allocation

Scenario: Determine which campaigns should receive more/less budget.

Process:

1. System calculates ROI per campaign:
   • Campaign A: $2000 spend, 15 customers, $8000 revenue → 4x ROI
   • Campaign B: $1500 spend, 3 customers, $1200 revenue → 0.8x ROI
2. AI recommends: "Increase Campaign A budget by 30%, reduce Campaign B by 50%"
3. Management reviews recommendation and adjusts budgets accordingly

Use Case 4: Seasonal Trend Analysis

Scenario: Understand how advertising effectiveness changes by season.

Process:

1. System tracks performance metrics over 12 months
2. Identifies patterns:
   • Spring/Summer: Higher conversion rates, lower CPA
   • Fall/Winter: Lower volume, higher CPA
3. AI recommends: "Increase budget 20% in March-August, decrease in November-January"
4. Management plans budget allocation for upcoming year

Tool Mockups

Dashboard - Campaign Overview

┌──────────────────────────────────────────────────────────────┐
│  Quarry Rentals - Advertising Performance Dashboard          │
├──────────────────────────────────────────────────────────────┤
│                                                                │
│  Date Range: [Last 7 Days ▼]                                 │
│                                                                │
│  ┌─────────────┬─────────────┬─────────────┬──────────────┐ │
│  │ Total Spend │   Clicks    │ Conversions │     CPA      │ │
│  ├─────────────┼─────────────┼─────────────┼──────────────┤ │
│  │   $3,245    │     892     │      24     │   $135.21    │ │
│  └─────────────┴─────────────┴─────────────┴──────────────┘ │
│                                                                │
│  Campaign Performance:                                         │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Campaign              │ Spend  │ Conv │ CPA    │ Status│  │
│  ├───────────────────────┼────────┼──────┼────────┼───────┤  │
│  │ LA Dumpster Rental    │ $1,450 │  12  │ $120   │ 🟢    │  │
│  │ OC Roll-Off Service   │ $1,100 │   8  │ $137   │ 🟢    │  │
│  │ Porta-Potty Rental    │   $695 │   4  │ $173   │ 🟡    │  │
│  └───────────────────────┴────────┴──────┴────────┴───────┘  │
│                                                                │
│  🤖 AI Insights:                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ • Campaign "LA Dumpster Rental" outperforming by 15%   │  │
│  │   → Recommend budget increase                           │  │
│  │                                                          │  │
│  │ • 8 keywords with $500+ spend and 0 conversions        │  │
│  │   → Review negative keyword recommendations            │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                                │
└──────────────────────────────────────────────────────────────┘

Dashboard - Keyword Analysis

┌──────────────────────────────────────────────────────────────┐
│  Keyword Performance - Optimization Opportunities             │
├──────────────────────────────────────────────────────────────┤
│                                                                │
│  Filter: [High Spend, Low Performance ▼]                      │
│                                                                │
│  Negative Keyword Candidates:                                 │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Keyword               │ Spend │ Clicks │ Conv │ Action │  │
│  ├───────────────────────┼───────┼────────┼──────┼────────┤  │
│  │ cheap dumpster        │ $340  │   48   │   0  │ [−]    │  │
│  │ dumpster rental free  │ $285  │   62   │   0  │ [−]    │  │
│  │ trash pickup          │ $180  │   31   │   0  │ [−]    │  │
│  └───────────────────────┴───────┴────────┴──────┴────────┘  │
│                                                                │
│  🤖 AI Recommendation:                                        │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Add these 3 keywords as negative keywords:              │  │
│  │ • "cheap" (attracts price shoppers, low conversion)     │  │
│  │ • "free" (not our service model)                        │  │
│  │ • "trash pickup" (different service category)           │  │
│  │                                                          │  │
│  │ Estimated Monthly Savings: $805                         │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                                │
└──────────────────────────────────────────────────────────────┘

Dashboard - Geographic Performance

┌──────────────────────────────────────────────────────────────┐
│  Performance by Location                                      │
├──────────────────────────────────────────────────────────────┤
│                                                                │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Location          │ Spend  │ Conv │ CPA    │ Revenue  │  │
│  ├───────────────────┼────────┼──────┼────────┼──────────┤  │
│  │ Los Angeles       │ $1,890 │  15  │ $126   │ $7,500   │  │
│  │ Orange County     │ $1,055 │   7  │ $150   │ $3,200   │  │
│  │ San Bernardino    │   $300 │   2  │ $150   │   $950   │  │
│  └───────────────────┴────────┴──────┴────────┴──────────┘  │
│                                                                │
│  🤖 AI Insight:                                               │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Los Angeles shows best ROI (3.97x)                      │  │
│  │ → Consider increasing LA budget by 25%                  │  │
│  │                                                          │  │
│  │ San Bernardino has limited volume but good CPA          │  │
│  │ → Maintain current budget, monitor for growth           │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                                │
└──────────────────────────────────────────────────────────────┘

Data Retention and Privacy

Data Storage

• Performance data stored indefinitely for trend analysis
• No personally identifiable information (PII) collected from Google Ads
• Data includes only aggregate metrics (clicks, spend, conversions)

Data Privacy

• API credentials stored in encrypted environment variables
• Database access restricted to application server
• No data shared with external parties
• Complies with Google Ads API Terms of Service

Data Security Measures

• SSL/TLS encryption for all API communication
• OAuth 2.0 token-based authentication
• Regular security audits of application
• Access logs maintained for accountability

Compliance

This tool complies with:

• Google Ads API Terms of Service
• Google Ads API Usage Policies
• CCPA (California Consumer Privacy Act)
• Our internal data security policies

We do not:

• Scrape or cache ad creative content
• Share Google Ads data with third parties
• Use data for purposes other than internal business intelligence
• Access data from accounts we don't own

Contact Information

Company: ONeill Media LLC / Quarry Rentals Primary Website: https://quarryrents.com API Contact Email: robert@quarry.app Google Ads Manager Account ID: 623-323-9884

Technical Contact: Robert O'Neill robert@quarry.app

This document describes our planned internal use of the Google Ads API for business intelligence and advertising optimization purposes only. All usage will be in compliance with Google Ads API policies and terms of service.