adsPRO — Google Ads API Tool Design Documentation

Company: Project-Pro
Tool Name: adsPRO
Date: February 2026
Version: 1.0

1. Tool Overview

adsPRO is an internal advertising management platform built for our agency to centralize and automate the management of Google Ads campaigns across multiple client accounts. The tool provides a unified dashboard for monitoring campaign performance, analyzing key metrics (ROAS, cost, conversion value), and managing campaign settings — eliminating the need to switch between multiple Google Ads accounts manually.

2. Purpose and Business Use Case

Our agency manages Google Ads campaigns for multiple clients. Currently, campaign data is collected manually or via Google Apps Script, which is fragile and hard to maintain. adsPRO replaces this workflow with a direct, reliable integration with the Google Ads API.

Key goals:

• Automatically retrieve campaign performance data for all managed client accounts
• Display historical trends (ROAS, budget, spend, conversions) in a centralized dashboard
• Enable campaign management operations (budget adjustments, bidding strategy changes, campaign status updates) directly from the platform
• Reduce manual work and improve response time for campaign optimization

3. Google Ads API Usage

3.1 Data Retrieval (Read Operations)

The tool uses the GoogleAdsService.SearchStream endpoint to fetch campaign data using GAQL (Google Ads Query Language).

Data retrieved:

• Campaign name, ID, and status
• Bidding strategy type and target ROAS
• Campaign budget (daily)
• Cost (spend) over the last 30 days
• Conversion value over the last 30 days
• All-time ROAS calculation

GAQL queries used:

SELECT campaign.id, campaign.name, campaign.bidding_strategy_type,
       campaign.target_roas.target_roas, campaign_budget.amount_micros,
       metrics.cost_micros, metrics.conversions_value
FROM campaign
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS

SELECT campaign.id, metrics.cost_micros, metrics.conversions_value
FROM campaign
WHERE campaign.status = 'ENABLED'

3.2 Campaign Management (Write Operations)

The tool will also support campaign management operations through the Google Ads API:

• Budget adjustments — updating campaign_budget.amount_micros via CampaignBudgetService.MutateCampaignBudgets
• Bidding strategy changes — modifying bidding strategy type and target ROAS via CampaignService.MutateCampaigns
• Campaign status updates — enabling/pausing campaigns via CampaignService.MutateCampaigns

All write operations are initiated manually by authorized agency staff through the adsPRO interface. No automated modifications are made without human approval.

4. API Request Frequency

• Automated data retrieval: Once per day via server-side CRON job (scheduled at 06:00 CET)
• Campaign management operations: On-demand, initiated manually by agency staff (estimated 10–50 requests per day)
• Number of client accounts: Currently under 20, expected to grow to ~50
• Estimated total daily API calls: Under 200 requests per day

5. Authentication and Authorization

• OAuth 2.0 authentication with offline access (refresh token flow)
• Credentials stored securely in a server-side database (not exposed to end users)
• Access token is refreshed automatically when expired
• Optional Manager Account (MCC) support for centralized access to client accounts

6. Architecture

[CRON - daily at 06:00]
        |
        v
[adsPRO Server (PHP)]
        |
        v
[Google Ads REST API v18]
   - SearchStream (read campaign data)
   - MutateCampaigns (manage campaigns)
   - MutateCampaignBudgets (adjust budgets)
        |
        v
[MySQL Database]
   - campaigns table (current state)
   - campaigns_history table (daily snapshots)
        |
        v
[adsPRO Dashboard]
   - Campaign performance charts
   - ROAS tracking over time
   - Campaign management interface

7. Data Handling and Privacy

• All data is stored on our own private server (shared hosting with SSL)
• Data is accessible only to authenticated agency staff (login required)
• No campaign data is shared with third parties
• No personally identifiable information (PII) is collected from end users
• API credentials are stored server-side and never exposed in client-facing code

8. Users

This is an internal agency tool. It is not a publicly available application. Access is restricted to authorized staff members of our agency (currently 3 users). There is no self-registration — accounts are created by the administrator.

9. Compliance

• The tool complies with the Google Ads API Terms of Service
• The tool complies with the Google API Services User Data Policy
• No data is sold or shared with third parties
• The tool does not perform automated campaign modifications without human oversight