Google Ads API comprehensive onboarding guide

This guide details the end-to-end process for onboarding, authenticating, and making your first call to the Google Ads API.

1. Prerequisites and account hierarchy

Before interacting with the Google Ads API, you must understand the account hierarchy and have the correct top-level account structure in place.

  • Manager Account (MCC): A Google Ads Manager Account (formerly My Client Center) is a primary account used to view and manage multiple client accounts. You must have a Manager Account to apply for a Google Ads API developer token.
  • Client Account: The standard account where campaigns, ad groups, and ads are created and billing is configured.

Action Item: If you do not have a Manager Account, create one at Google Ads Manager Accounts.

2. Obtain a developer token

The developer token uniquely identifies your application to the Google Ads API and controls your call volume access tier.

Steps to apply

  1. Sign in to your Google Ads Manager Account.
  2. Navigate to Tools and settings > Setup > API Center (or Admin > API Center).
  3. Fill out the developer details form and agree to the API Terms of Service.
  4. Submit your application.

Access levels

  • Pending Approval: Newly created tokens immediately receive a "Pending" status. You can use a pending token to connect to Test Accounts immediately, but it will not work against production accounts.
  • Basic Access: Allows up to 15,000 API operations per day once approved.
  • Standard Access: Unlimited daily API operations for applications that meet the Required Minimum Functionality (RMF).

3. Set up test accounts

Developing and testing against production accounts risks unwanted ad spend and campaign modifications. It is highly recommended to perform all active development against test accounts.

How to create a test manager account

  1. Go to the Google Ads Test Manager Account creation page.
  2. Sign in with a Google Account that is not already linked to your production Google Ads Manager Account.
  3. Enter a descriptive account name (e.g., MyCompany Test MCC).
  4. Select the primary use as Manage other people's accounts.
  5. Choose your billing country, time zone, and currency. Click Save and continue.

How to create a test client account

Once your Test Manager Account is created, you must create at least one child client account to run test campaigns.

  1. Sign in to your newly created Test Manager Account.
  2. From the left navigation menu, click Accounts, then select Sub-account settings (or Performance).
  3. Click the blue + (plus) button and select Create new account.
  4. Select Google Ads account.
  5. Enter an account name (e.g., Test Client Account A).
  6. Select a time zone and currency, then click Save and continue.
  7. Note down the 10-digit Customer ID (e.g., 1234567890 without hyphens) of this new client account.

Important rules for test accounts

  • Developer Token Usage: Do not apply for a developer token from your Test Manager Account. Always use the pending or approved developer token from your Production Manager Account.
  • Billing: Test accounts do not serve actual ads, so you do not need to enter real billing information.

4. Google Cloud project setup

All API requests must be authenticated using a Google Cloud project with the Google Ads API enabled.

Steps to enable the API

  1. Go to the Google Cloud Console.
  2. Create a new project or select an existing project.
  3. Navigate to APIs & Services > Library.
  4. Search for Google Ads API and click Enable.

Pricing and billing note

  • No API Fees: Creating a Google Cloud project, enabling the Google Ads API, and generating OAuth 2.0 credentials is 100% free. Google does not charge any fees for calling or using the Google Ads API itself.
  • Other Cloud Resources: You will only incur Google Cloud fees if you actively use other billable Google Cloud services (such as Compute Engine, Cloud Run, or BigQuery) beyond their Free Tier limits to host your application or store your ad data.

5. OAuth 2.0 authentication configuration

The Google Ads API uses OAuth 2.0 to authenticate and authorize requests.

Steps for desktop or web application flow

  1. In your Google Cloud project, go to APIs & Services > OAuth consent screen and configure the consent screen.
  2. Go to APIs & Services > Credentials.
  3. Click Create Credentials > OAuth client ID.
  4. Select the application type (e.g., Desktop app or Web application).
  5. Click Create. Download or copy your Client ID and Client Secret.

Generate a refresh token

Once you have your Client ID and Client Secret, you must generate a Refresh Token. You can do this using either the Google OAuth 2.0 Playground or a client library script.

Method A: Use Google OAuth 2.0 Playground (web-based)

  1. Go to the Google OAuth 2.0 Playground.
  2. Click the Gear icon (OAuth 2.0 configuration) in the upper right corner.
  3. Check the box for Use your own OAuth credentials.
  4. Enter your OAuth2 Client ID and Client Secret, then click Close.
  5. In Step 1 (Select & authorize APIs) on the left, input the Google Ads API scope in the "Input your own scopes" field: https://www.googleapis.com/auth/adwords
  6. Click Authorize APIs. When prompted, sign in with the Google Account that has access to your Google Ads Manager Account (or Test Account).
  7. Click Continue on the consent screen.
  8. In Step 2 (Exchange authorization code for tokens), click the blue Exchange authorization code for tokens button.
  9. Your Refresh token and Access token will be displayed in the response panel. Copy and save the Refresh token.

Method B: Use client library script (Python example)

The official Python client library provides a built-in helper script to generate credentials. Alternatively, you can run the following standalone Python script:

  1. Install the required OAuth library:
pip install google-auth-oauthlib
  1. Create a script named generate_refresh_token.py and run it:
from google_auth_oauthlib.flow import InstalledAppFlow

# Set your Client ID and Secret
CLIENT_ID = "INSERT_YOUR_CLIENT_ID_HERE"
CLIENT_SECRET = "INSERT_YOUR_CLIENT_SECRET_HERE"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    client_config = {
        "installed": {
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
            "auth_uri": "https://accounts.google.com/o/oauth2/auth",
            "token_uri": "https://oauth2.googleapis.com/token",
        }
    }
    
    # Initialize the flow
    flow = InstalledAppFlow.from_client_config(client_config, SCOPES)
    
    # Run the local server flow to prompt the user to log in
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

6. Client library and credentials setup

Google provides officially supported client libraries that handle authentication, serialization, and communication with the gRPC endpoints.

Supported languages

  • Python: pip install google-ads
  • Java: Available through Maven or Gradle
  • PHP: composer require googleads/google-ads-php
  • .NET: Install-Package Google.Ads.GoogleAds
  • Ruby: gem install google-ads-googleads

Configuration file (google-ads.yaml)

Create a configuration file containing your credentials. By default, the client library's initialization method (e.g., GoogleAdsClient.load_from_storage()) will automatically search for google-ads.yaml in two locations:

  1. The current working directory from which your script is run.
  2. Your user home directory (~ on Linux/macOS or %HOMEPATH% on Windows).

If you store the file in a custom location, you can explicitly pass the path to the initialization method (e.g., load_from_storage("path/to/google-ads.yaml")).

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

7. Make your first API call

To verify your onboarding setup, run a quickstart script to fetch existing campaigns from your test account.

Example Python script (quickstart.py)

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(f"Campaign with ID {row.campaign.id} and name '{row.campaign.name}' was found.")

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the current working directory
    # or the user's home directory (~). You can also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens)
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    except GoogleAdsException as ex:
        print(f"Request failed with status {ex.error.code().name} and includes the following errors:")
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

8. Best practices and resources

  • Logging: Enable detailed logging in your client library to capture request/response IDs (request-id), which are essential when requesting support from Google.
  • Error Handling: Implement robust error handling for GoogleAdsException, specifically managing rate limits (RESOURCE_TEMPORARILY_EXHAUSTED).
  • Official Documentation: Google Ads API Developer Docs
  • Client Libraries & Code Samples: GitHub Google Ads Repositories
Previous
Introduction
Next
Quickstart