Google Ads Python Client Library

Warnings

• breaking Major library versions frequently remove support for older Google Ads API versions (e.g., `29.0.0` removed support for API `v19`). Failing to update your client library and API version in your code will result in API requests being blocked.
  Fix: Regularly check the library's `ChangeLog` and the Google Ads API 'Deprecation and sunset timetable' to ensure your client library version and API version (`client = GoogleAdsClient.load_from_storage(version="vX")`) are compatible with the latest supported API versions.
• breaking The library actively ceases support for Python versions once they reach their End-of-Life (EOL) by the Python Software Foundation. For example, Python 3.9 will lose support in Q4 2025, and a new major library version will be incompatible with it. Python 3.8 users lost access around Q1 2026 when API v19 sunset.
  Fix: Ensure your Python environment is kept up-to-date. Users on Python 3.8 or 3.9 should upgrade to Python 3.10 or higher as soon as possible to maintain access.
• gotcha Setting up authentication (developer token, client ID, client secret, refresh token, and `login_customer_id`) is complex and a common source of errors. Misconfigurations, such as an incorrect `login_customer_id` or an unassociated user, can lead to `NOT_ADS_USER` errors.
  Fix: Carefully follow the official Google Ads API authentication guides. Utilize `google-ads.yaml` or environment variables for configuration. Leverage Application Default Credentials (ADC), supported since v28.3.0, for simplified local development and production. Ensure the user associated with the credentials has appropriate access to the Google Ads account being queried.
• gotcha Directly importing API service clients or types (e.g., `from google.ads.googleads.vX.services import GoogleAdsService`) is discouraged. The internal structure of the generated protobuf code can change across library versions, causing direct imports to break.
  Fix: Always use `client.get_service("ServiceName")` and `client.get_type("TypeName")` to retrieve API service clients and types, respectively. This provides an abstraction layer that insulates your code from internal library changes.
• gotcha When programmatically overriding logging configurations, these changes must be applied *before* initializing the `GoogleAdsClient` instance. If the client is initialized first, any logging settings defined in your `google-ads.yaml` file will take precedence and override programmatic settings.
  Fix: Configure logging (e.g., setting log levels or handlers) prior to calling `GoogleAdsClient.load_from_storage()` or `GoogleAdsClient.load_from_dict()`.

Install

• pip install google-ads Install latest version

Imports

• GoogleAdsClient

  from google.ads.googleads.client import GoogleAdsClient

  While `GoogleAdsClient` is imported directly, the official documentation recommends using `client.get_service()` and `client.get_type()` methods for retrieving API service clients and types, respectively. This practice is preferred to mitigate potential breaking changes due to the generated nature of the client library's internal structure.

Quickstart

This quickstart demonstrates how to initialize the Google Ads client and perform a simple API request to list campaigns. It assumes authentication details are configured via a `google-ads.yaml` file (by default in the user's home directory) or environment variables. Replace `GOOGLE_ADS_CUSTOMER_ID` with an actual customer ID to run.

import os
from google.ads.googleads.client import GoogleAdsClient

# Ensure your google-ads.yaml is configured or environment variables are set.
# For quickstart, we assume a google-ads.yaml in the home directory or specified path.
# You would typically set client_id, client_secret, refresh_token, developer_token,
# and login_customer_id in this file or via environment variables.
# Example: os.environ['GOOGLE_ADS_DEVELOPER_TOKEN'] = 'YOUR_DEVELOPER_TOKEN'
# For full authentication setup, refer to Google Ads API documentation.

# Initialize the client. By default, it loads from google-ads.yaml in your home directory.
# Or specify path: GoogleAdsClient.load_from_storage(path='path/to/google-ads.yaml')
try:
    client = GoogleAdsClient.load_from_storage()
except Exception as e:
    print(f"Failed to load Google Ads client configuration: {e}")
    print("Please ensure your google-ads.yaml file is correctly configured or credentials are set via environment variables.")
    exit(1)

# Replace with your Google Ads customer ID
# If using a manager account, this is the ID of the account you want to query.
customer_id = os.environ.get('GOOGLE_ADS_CUSTOMER_ID', '123-456-7890').replace('-', '') # Remove hyphens

def main(client, customer_id):
    try:
        ga_service = client.get_service("GoogleAdsService")

        # Create a query to select all active campaigns
        query = """
            SELECT
                campaign.id,
                campaign.name,
                campaign.status
            FROM
                campaign
            ORDER BY
                campaign.id
            """

        # Issue a search request.
        response = ga_service.search(customer_id=customer_id, query=query)

        print(f"Listing campaigns for customer ID: {customer_id}")
        for row in response:
            campaign = row.campaign
            print(f"\tCampaign ID: {campaign.id}, Name: {campaign.name}, Status: {campaign.status.name}")

    except Exception as e:
        print(f"An API error occurred: {e}")

if __name__ == "__main__":
    main(client, customer_id)