ADTAP - Google Ads API Tools and Patterns

Tap the Google Ads API from your terminal. Read-only exploration, documentation, and pattern discovery.

Overview

ADTAP provides tools, documentation, and patterns for working with the Google Ads API v23.

Non-Goals

This project is strictly READ-ONLY.

Excluded Operations	Reason
Campaign mutations	No create/update/delete of campaigns
AdGroup mutations	No create/update/delete of ad groups
Ad mutations	No create/update/delete of ads
Budget changes	No modification of budgets
Bid adjustments	No modification of bids
Any Mutate calls	All mutate operations are out of scope

ADTAP is designed for:

• Exploration and understanding of the Google Ads API
• Documentation and diagramming of entity relationships
• Read-only queries via GoogleAdsService.Search and SearchStream
• Research and prototyping patterns

ADTAP is NOT designed for:

• Automating campaign management
• Making any changes to Google Ads accounts
• Production ad operations
• Productionized data pipelines
• High-efficiency batch processing
• Production ETL workflows

This is an exploration tool, not a production system. While we reference best practices for understanding API patterns (SearchStream vs Search vs Get), our goal is learning and documentation, not operational efficiency.

Getting Started

Prerequisites

1. A Google Ads Manager Account
2. A Google Cloud Project with billing enabled
3. A Google Ads Developer Token
4. Service Account credentials (JSON)

Step 1: Obtain a Developer Token

A developer token is a 22-character alphanumeric string that lets your app connect to the Google Ads API.

Create or Select a Manager Account

Use an email address that has not been previously associated with any Google Ads account.

Apply for API Access

1. Navigate to API Center in your Google Ads manager account
2. Complete the API Access form with:
   • Accurate company details
   • A functioning website URL
   • Valid API contact email (monitor this for review communications)

Access Levels

Level	Description
Test Account	Limited to test accounts only
Basic	Standard access after approval
Standard	Full capabilities with higher rate limits

Reference: Developer Token Documentation

Step 2: Set Up Google Cloud Credentials

Create a Service Account

# Create service account
gcloud iam service-accounts create google-ads-api \
    --display-name="Google Ads API Service Account"

# Download credentials
gcloud iam service-accounts keys create credentials.json \
    --iam-account=google-ads-api@YOUR_PROJECT_ID.iam.gserviceaccount.com

Configure Environment

Copy the example environment file and fill in your values:

cp .env.example .env

Edit .env with your credentials:

GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/credentials.json
GOOGLE_PROJECT_ID=your-project-id
GOOGLE_ADS_DEVELOPER_TOKEN=your-22-char-developer-token

Step 3: Using with MCP Server

The Google Ads MCP server allows Claude to interact with the Google Ads API.

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/credentials.json",
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
      }
    }
  }
}

Step 4: Test Your Setup

Using Test Accounts

For initial development, use test accounts to avoid affecting production data:

# Test accounts don't serve ads and have no spending limits
# Create via: Google Ads UI > Tools & Settings > Setup > Test accounts

Verify API Access

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("google-ads.yaml")
customer_service = client.get_service("CustomerService")

# List accessible customers
accessible_customers = customer_service.list_accessible_customers()
print(f"Accessible customers: {accessible_customers.resource_names}")

Project Structure

adtap/
├── .env.example              # Environment variable template
├── README.org                # This file
├── CLAUDE.md                 # Claude Code project instructions
├── docs/
│   ├── references.org        # External references and links
│   └── google-ads-api-v23-diagrams.org  # Entity diagrams (ERD, state, sequence)
└── vendor/                   # Git submodules for reference
    ├── google-ads-mcp/       # MCP server for Claude integration
    ├── google-ads-api-developer-assistant/  # Gemini CLI extension
    └── google-ads-pb/        # Go protobuf implementation

Vendor Submodules

Related projects included as git submodules for review:

Submodule	Description	Version
google-ads-mcp	MCP server for LLM integration	main
google-ads-api-developer-assistant	Gemini CLI extension for natural language API interaction	v2.0
google-ads-pb	Go protobuf implementation	v1.23.0

Initialize Submodules

After cloning this repository:

git submodule update --init --recursive

google-ads-mcp

MCP server providing tools for LLM interaction with Google Ads API:

• search - Retrieve account information via GAQL
• list_accessible_customers - List accessible customer accounts

google-ads-api-developer-assistant

Gemini CLI extension for natural language interaction:

• Natural language to GAQL conversion
• Code generation in Python, Ruby, PHP
• Direct API execution from terminal
• CSV export of results

google-ads-pb

Go implementation of Google Ads API protobufs for building Go clients.

API Version

This project targets Google Ads API v23 (released January 2026).

Version	Status	Sunset Date
v23	Current	TBD
v22	Supported	TBD
v21	Supported	TBD
v20	Supported	TBD
v10	Sunset	2023-02-01

See Deprecation and Sunset Dates for current schedule.

Resources

API Reference

• Google Ads API v23 Reference
• Official Protobuf Definitions

Developer Toolkit

Tool	Description	Link
AI Assistant	Gemini CLI extension for natural language	Link
MCP Server	Claude/LLM integration for API access	Link
API Explorer	Interactive REST API exploration	Link
Query Builder	Build GAQL queries interactively	Link
Query Validator	Validate GAQL query syntax	Link

Client Libraries

• Python Client Library
• Go Protobuf Implementation
• Google Ads MCP Server

Documentation in This Repo

• Mind Map - Visual overview of all areas
• Getting Started: GAQL
• Getting Started: REST API
• Entity Diagrams (ERD, State, Sequence)

License

TBD