Google Ads API Requirements and Setup

Overview

Integrating Google Ads with Cogny enables comprehensive ROAS analysis by combining ad spend data with conversion analytics from GA4. This guide covers the setup requirements and API configuration.

Benefits:

• Calculate true ROAS (Return on Ad Spend) by channel
• Analyze campaign performance alongside on-site behavior
• Optimize ad spend based on post-click conversion data
• Attribute revenue to specific campaigns and ad groups

Time to complete: 15-20 minutes

Prerequisites

• Google Ads account with campaign data
• Admin or Standard access to Google Ads account
• Google Cloud Project (can be the same as BigQuery)
• GA4 BigQuery export configured

Google Ads API Access Levels

Basic Access (Automatic)

All Google Ads accounts have Basic Access by default:

• Query Limit: 15,000 operations per day
• Sufficient for: Most small to medium businesses
• No approval needed

Standard Access (Requires Approval)

For higher query limits:

• Query Limit: 1,500,000 operations per day
• Requirements:
  • Minimum $10,000 USD spend over 90 days across managed accounts
  • API usage must comply with Google Ads API Terms
  • Application review by Google (1-2 weeks)

Most Cogny users can use Basic Access successfully.

Step 1: Create Google Cloud Project

If you don't already have a Google Cloud project:

Via Google Cloud Console

1. Go to Google Cloud Console
2. Click Select a project > New Project
3. Enter project details:
   • Project name: Cogny Integration
   • Organization: Select your organization
4. Click Create

Via gcloud CLI

# Create project
gcloud projects create cogny-integration-project \
    --name="Cogny Integration"

# Set as default
gcloud config set project cogny-integration-project

Step 2: Enable Google Ads API

Via Google Cloud Console

1. Navigate to APIs & Services > Library
2. Search for "Google Ads API"
3. Click Google Ads API
4. Click Enable

Via gcloud CLI

gcloud services enable googleads.googleapis.com

Step 3: Create OAuth 2.0 Credentials

Google Ads API requires OAuth 2.0 for authentication.

Via Google Cloud Console

1. Navigate to APIs & Services > Credentials
2. Click Create Credentials > OAuth client ID
3. If prompted, configure the OAuth consent screen:
   • User Type: Internal (for workspace) or External
   • App name: Cogny Analytics
   • User support email: Your email
   • Developer contact: Your email
4. Create OAuth client ID:
   • Application type: Web application
   • Name: Cogny Google Ads Integration
   • Authorized redirect URIs:
     • https://app.cogny.com/oauth/google-ads/callback
     • http://localhost:8080/oauth/callback (for testing)
5. Click Create
6. Save Client ID and Client Secret

Via gcloud CLI

# Note: OAuth consent screen must be configured via console first

# Create OAuth client
gcloud alpha iap oauth-clients create \
    --display_name="Cogny Google Ads Integration"

Step 4: Configure OAuth Consent Screen

User Type

Internal (Recommended for Workspace users):

• Only users in your Google Workspace organization
• No verification required
• Faster setup

External:

• Any Google account can authenticate
• Requires app verification for production use
• Longer setup process

Consent Screen Configuration

1. Navigate to APIs & Services > OAuth consent screen
2. Fill in required fields:
   • App name: Cogny Analytics
   • User support email: Your support email
   • Logo: Optional Cogny logo
   • App domain: app.cogny.com
   • Authorized domains:
     • cogny.com
   • Developer contact: Your email
3. Click Save and Continue

Scopes

Add the following OAuth scopes:

https://www.googleapis.com/auth/adwords

This scope provides read-only access to Google Ads data.

Test Users (External Apps Only)

If using External user type, add test users:

1. Click Add Users
2. Enter email addresses of users who need access
3. Click Save and Continue

Step 5: Get Google Ads Customer ID

Via Google Ads Interface

1. Log in to Google Ads
2. Look for your Customer ID in the top right corner
3. Format: XXX-XXX-XXXX (10 digits)
4. Remove dashes for API use: XXXXXXXXXX

Via Google Ads API

from google.ads.googleads.client import GoogleAdsClient

# Initialize client (credentials configured)
client = GoogleAdsClient.load_from_storage("google-ads.yaml")

# List accessible customers
customer_service = client.get_service("CustomerService")
accessible_customers = customer_service.list_accessible_customers()

for customer_resource_name in accessible_customers.resource_names:
    print(customer_resource_name)  # customers/XXXXXXXXXX

Step 6: Create Manager Account (Optional)

If managing multiple Google Ads accounts, use a Manager Account (MCC):

1. Go to Google Ads
2. Click Tools & Settings > Manager accounts
3. Click Create a manager account
4. Enter account details
5. Link client accounts to manager account

Benefits:

• Single OAuth connection for multiple accounts
• Centralized reporting
• Easier credential management

Step 7: Connect to Cogny

Via Cogny Dashboard

1. Log in to app.cogny.com
2. Navigate to Settings > Integrations
3. Click Connect Google Ads
4. Click Authorize with Google
5. Select Google account with Ads access
6. Grant permissions
7. Select Google Ads account to connect
8. Click Save

OAuth Flow Details

The OAuth flow:

1. Authorization Request:

   https://accounts.google.com/o/oauth2/v2/auth?
     client_id=YOUR_CLIENT_ID&
     redirect_uri=https://app.cogny.com/oauth/google-ads/callback&
     response_type=code&
     scope=https://www.googleapis.com/auth/adwords&
     access_type=offline&
     prompt=consent
   

2. Authorization Code Exchange:

   curl -X POST https://oauth2.googleapis.com/token \
     -d "code=AUTHORIZATION_CODE" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "redirect_uri=https://app.cogny.com/oauth/google-ads/callback" \
     -d "grant_type=authorization_code"
   

3. Refresh Token: Cogny stores the refresh token to maintain long-term access.

API Configuration

google-ads.yaml Format

Cogny uses standard Google Ads API configuration:

# Google Ads API configuration
developer_token: YOUR_DEVELOPER_TOKEN
client_id: YOUR_CLIENT_ID
client_secret: YOUR_CLIENT_SECRET
refresh_token: YOUR_REFRESH_TOKEN
login_customer_id: XXXXXXXXXX  # Manager account (if applicable)
use_proto_plus: True

Developer Token

A developer token is required for API access:

1. Log in to Google Ads
2. Click Tools & Settings > API Center
3. Copy your Developer Token
4. If you don't see one, apply for API access

Note: Cogny manages the developer token. You only need to provide OAuth credentials and customer ID.

Data Synchronization

Available Metrics

Cogny syncs the following Google Ads metrics:

Campaign Metrics:

• Impressions
• Clicks
• CTR (Click-through rate)
• Cost
• Conversions
• Conversion value
• CPA (Cost per acquisition)
• ROAS (Return on ad spend)

Dimension Breakdowns:

• Campaign
• Ad Group
• Keyword
• Ad
• Device
• Geographic location
• Day of week
• Hour of day

Sync Frequency

• Initial sync: Last 90 days of data
• Ongoing sync: Daily at 3 AM UTC
• Real-time sync: Available for Enterprise plans

Data Retention

• Standard: 13 months
• Enterprise: Custom retention periods

Attribution Models

Cogny supports multiple attribution models when combining Google Ads and GA4 data:

Last Click (Default)

Revenue attributed to the last click before conversion:

-- Last-click attribution
SELECT
  campaign_name,
  SUM(cost) as ad_spend,
  SUM(revenue) as attributed_revenue,
  SAFE_DIVIDE(SUM(revenue), SUM(cost)) as roas
FROM cogny_attribution.last_click
WHERE date >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
GROUP BY 1
ORDER BY ad_spend DESC

First Click

Revenue attributed to the first touchpoint:

-- First-click attribution
SELECT
  campaign_name,
  SUM(cost) as ad_spend,
  SUM(revenue) as attributed_revenue,
  SAFE_DIVIDE(SUM(revenue), SUM(cost)) as roas
FROM cogny_attribution.first_click
WHERE date >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
GROUP BY 1
ORDER BY ad_spend DESC

Linear

Revenue distributed equally across all touchpoints:

-- Linear attribution
SELECT
  campaign_name,
  SUM(cost) as ad_spend,
  SUM(revenue) as attributed_revenue,
  SAFE_DIVIDE(SUM(revenue), SUM(cost)) as roas
FROM cogny_attribution.linear
WHERE date >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
GROUP BY 1
ORDER BY ad_spend DESC

Time Decay

More recent touchpoints receive more credit:

-- Time-decay attribution
SELECT
  campaign_name,
  SUM(cost) as ad_spend,
  SUM(revenue) as attributed_revenue,
  SAFE_DIVIDE(SUM(revenue), SUM(cost)) as roas
FROM cogny_attribution.time_decay
WHERE date >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
GROUP BY 1
ORDER BY ad_spend DESC

Example Queries

Campaign ROAS Analysis

WITH ad_spend AS (
  SELECT
    date,
    campaign_name,
    SUM(cost_micros) / 1000000 as cost_usd
  FROM `project.google_ads.campaign_performance`
  WHERE date >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
  GROUP BY 1, 2
),

conversions AS (
  SELECT
    DATE(TIMESTAMP_MICROS(event_timestamp)) as date,
    (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'campaign') as campaign_name,
    SUM(ecommerce.purchase_revenue_in_usd) as revenue
  FROM `project.analytics_123456789.events_*`
  WHERE _TABLE_SUFFIX >= FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY))
    AND event_name = 'purchase'
  GROUP BY 1, 2
)

SELECT
  a.campaign_name,
  SUM(a.cost_usd) as ad_spend,
  SUM(c.revenue) as revenue,
  SAFE_DIVIDE(SUM(c.revenue), SUM(a.cost_usd)) as roas,
  SAFE_DIVIDE(SUM(a.cost_usd), SUM(c.revenue)) as cac_ratio
FROM ad_spend a
LEFT JOIN conversions c USING(date, campaign_name)
GROUP BY 1
ORDER BY ad_spend DESC

Keyword Performance

SELECT
  campaign_name,
  ad_group_name,
  keyword_text,
  SUM(impressions) as impressions,
  SUM(clicks) as clicks,
  SAFE_DIVIDE(SUM(clicks), SUM(impressions)) as ctr,
  SUM(cost_micros) / 1000000 as cost_usd,
  SUM(conversions) as conversions,
  SAFE_DIVIDE(SUM(cost_micros) / 1000000, SUM(conversions)) as cpa,
  SUM(conversion_value) as conversion_value,
  SAFE_DIVIDE(SUM(conversion_value), SUM(cost_micros) / 1000000) as roas
FROM `project.google_ads.keyword_performance`
WHERE date >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
  AND impressions > 0
GROUP BY 1, 2, 3
ORDER BY cost_usd DESC

Device Performance

SELECT
  device,
  SUM(impressions) as impressions,
  SUM(clicks) as clicks,
  SAFE_DIVIDE(SUM(clicks), SUM(impressions)) as ctr,
  SUM(cost_micros) / 1000000 as cost_usd,
  SUM(conversions) as conversions,
  SAFE_DIVIDE(SUM(conversions), SUM(clicks)) as conversion_rate,
  SAFE_DIVIDE(SUM(cost_micros) / 1000000, SUM(conversions)) as cpa
FROM `project.google_ads.campaign_performance`
WHERE date >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
GROUP BY 1
ORDER BY cost_usd DESC

Troubleshooting

Error: "Invalid OAuth Credentials"

Cause: Expired or invalid refresh token

Solution:

1. Disconnect Google Ads in Cogny
2. Reconnect and re-authorize
3. Ensure OAuth consent screen is properly configured

Error: "Customer Not Found"

Cause: Incorrect customer ID format

Solution:

# Remove dashes from customer ID
customer_id = "123-456-7890"
formatted_id = customer_id.replace("-", "")  # "1234567890"

Error: "Permission Denied"

Cause: Insufficient Google Ads account access

Solution:

1. Verify account access level (Standard or Admin required)
2. Check OAuth scope includes https://www.googleapis.com/auth/adwords
3. Ensure user has access to the specific customer account

Error: "Rate Limit Exceeded"

Cause: Too many API requests

Solution:

• Basic Access: 15,000 operations/day limit
• Standard Access: Apply for higher limits
• Cogny automatically implements exponential backoff

Best Practices

1. Use Manager Account for Multiple Accounts

# Connect via manager account
manager_customer_id = "1234567890"
client_accounts = ["1111111111", "2222222222", "3333333333"]

# Single OAuth, multiple accounts

2. Monitor API Usage

Track API quota usage:

# View API usage in Cloud Console
gcloud logging read "resource.type=consumed_api" \
    --limit 50 \
    --format json

3. Implement Error Handling

from google.ads.googleads.errors import GoogleAdsException

try:
    response = customer_service.list_accessible_customers()
except GoogleAdsException as ex:
    print(f"Request failed with status {ex.error.code().name}")
    for error in ex.failure.errors:
        print(f"\tError: {error.message}")

4. Cache API Responses

Cogny caches Google Ads data to minimize API calls:

• Campaign data: 24-hour cache
• Account structure: 7-day cache
• Real-time data available on demand (Enterprise)

Security Considerations

OAuth Token Storage

Cogny encrypts all OAuth tokens:

• Encryption: AES-256-GCM
• Storage: Encrypted database
• Access: Restricted to authorized services
• Rotation: Automatic refresh token rotation

API Key Security

Protect your OAuth credentials:

# Store in environment variables
export GOOGLE_ADS_CLIENT_ID="your-client-id"
export GOOGLE_ADS_CLIENT_SECRET="your-client-secret"

# Never commit credentials
echo "*google-ads.yaml" >> .gitignore

Next Steps

• GA4 BigQuery Schema - Understand GA4 data structure
• Security Best Practices - Security guidelines
• ROAS Analysis Guide - Optimize ad spend

Resources

• Google Ads API Documentation: developers.google.com/google-ads/api
• OAuth 2.0 Guide: developers.google.com/identity/protocols/oauth2
• API Support: Google Ads API Forum