Google Ads Python Client Library

raw JSON →
49.0.0 verified Tue May 12 auth: no python install: verified

The official Python client library for the Google Ads API, enabling programmatic access to Google Ads data and management. It facilitates operations such as campaign management, reporting, and bid adjustments. The library is currently at version 49.0.0 and receives quarterly updates to support new API versions and deprecate older ones, ensuring compatibility with the frequently evolving Google Ads API.

pip install google-ads

Common errors

error ModuleNotFoundError: No module named 'google.ads.google_ads' (or 'googleads') ↓
cause The Python client library for the Google Ads API was installed, but the import path is incorrect, or an older, deprecated library ('googleads') is being referenced.
fix
Ensure the google-ads library is installed (pip install google-ads) and use the correct import statement for the current library version: from google.ads.googleads.client import GoogleAdsClient.
error AttributeError: '_Rendezvous' object has no attribute 'request_id' ↓
cause This error occurs when attempting to access the `request_id` directly from the raw gRPC `_Rendezvous` object, which is returned in case of a gRPC error, rather than from a `GoogleAdsException` object.
fix
Wrap your Google Ads API calls in a try...except google.ads.googleads.errors.GoogleAdsException as ex: block. The request_id can then be accessed from ex.request_id within the exception handler.
error google.auth.exceptions.RefreshError: invalid_grant (or AuthenticationError.NOT_ADS_USER, PERMISSION_DENIED) ↓
cause These are common authentication and authorization issues. `invalid_grant` often means the refresh token is expired or revoked. `NOT_ADS_USER` or `PERMISSION_DENIED` indicates the Google account used for OAuth lacks necessary access to the Google Ads account, the client customer ID is incorrect, or required OAuth scopes are missing.
fix
For invalid_grant: Regenerate the OAuth2 refresh token, ensuring the Google Cloud project's OAuth consent screen publishing status is 'In production' if it's for long-term use, and revoke previous tokens before generating a new one. For NOT_ADS_USER/PERMISSION_DENIED: Verify the Google account used for authentication has active access to the Google Ads account, ensure the client customer ID is correct (e.g., '1234567890' not '123-456-7890'), and confirm that the OAuth scopes include https://www.googleapis.com/auth/adwords.
error ValueError: Specified Google Ads API version 'vX' does not exist. Valid API versions are: 'vY', 'vZ' ↓
cause The `GoogleAdsClient` was initialized with an API version string (`vX`) that is no longer supported or does not exist. The Google Ads API is updated quarterly, deprecating older versions.
fix
Update the API version string used when initializing the client (e.g., client.get_service('CampaignService', version='vX')) to one of the currently valid versions listed in the error message or the latest official documentation.
error AttributeError: 'str' object has no attribute 'get' (when loading client config) ↓
cause This error typically occurs when the `google-ads.yaml` configuration file is malformed, empty, or unreadable, causing the client loading method (`load_from_storage`, `load_from_string`, etc.) to return a string instead of a dictionary-like object that `get()` can be called on.
fix
Carefully review the google-ads.yaml file for correct YAML syntax (indentation, key-value pairs), ensure all required fields are present, and verify the file path is correct and accessible. If loading from a string, ensure it's a valid YAML formatted string.

Warnings

gotcha The modern client library for the Google Ads API is installed via `pip install google-ads` and imported from `google.ads.googleads`. Do not confuse it with the deprecated and very old `googleads` PyPI package (which would be `pip install googleads`). The prompt's input contained conflicting information regarding `pypi-slug: googleads` vs. the provided version and GitHub URL which clearly refer to `google-ads`. ↓
fix Always install with `pip install google-ads` and import from `google.ads.googleads`.
breaking Google Ads API versions are frequently updated (quarterly) and old versions are deprecated and removed. Applications built against older API versions will cease to function when those versions are removed. The Python client library is updated to support new versions and remove support for old ones. ↓
fix Regularly update the `google-ads` library and your code to the latest API version (e.g., `client = GoogleAdsClient.load_from_storage(version='v16')`). Monitor release notes for breaking changes and migration guides.
gotcha Authentication can be complex, requiring a Developer Token, OAuth2 Client ID/Secret, a Refresh Token, and potentially a Login Customer ID (for manager accounts). Misconfiguration is a common source of errors. ↓
fix Refer to the official documentation for detailed setup instructions. Utilize a `google-ads.yaml` configuration file for development and environment variables for production to manage credentials securely.
gotcha The Google Ads API uses Google Ads Query Language (GAQL) for reporting and searching resources. Understanding GAQL syntax and the available resources/fields is critical but can have a steep learning curve. ↓
fix Consult the Google Ads API documentation for GAQL reference, resource definitions, and example queries. Use the Google Ads Query Builder tool to construct and validate queries.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 1.61s 264.0M
3.10 alpine (musl) - - 1.53s 223.4M
3.10 slim (glibc) wheel 14.1s 1.04s 263M
3.10 slim (glibc) - - 1.06s 222M
3.11 alpine (musl) wheel - 2.23s 285.8M
3.11 alpine (musl) - - 2.55s 241.7M
3.11 slim (glibc) wheel 13.4s 1.68s 284M
3.11 slim (glibc) - - 1.62s 240M
3.12 alpine (musl) wheel - 2.27s 274.2M
3.12 alpine (musl) - - 2.40s 230.7M
3.12 slim (glibc) wheel 13.2s 2.04s 273M
3.12 slim (glibc) - - 2.12s 229M
3.13 alpine (musl) wheel - 2.20s 271.7M
3.13 alpine (musl) - - 2.23s 228.6M
3.13 slim (glibc) wheel 13.3s 1.83s 270M
3.13 slim (glibc) - - 2.01s 227M
3.9 alpine (musl) wheel - 1.47s 264.3M
3.9 alpine (musl) - - 1.40s 223.7M
3.9 slim (glibc) wheel 16.8s 1.27s 263M
3.9 slim (glibc) - - 1.12s 222M

Imports

Quickstart last tested: 2026-04-24

Initializes the Google Ads client and lists accessible customer IDs. Authentication is typically handled via a `google-ads.yaml` file in the user's home directory or through environment variables for sensitive credentials. Replace 'v16' with the latest stable API version.

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

def main():
    try:
        # Authenticate using google-ads.yaml or environment variables
        # For environment variables, set GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID,
        # GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN, GOOGLE_ADS_LOGIN_CUSTOMER_ID.
        # login_customer_id is required for some API calls, and should be the ID of the manager account.
        client = GoogleAdsClient.load_from_storage(version='v16') # Use the latest API version

        # Example: Get a list of accessible customer IDs
        customer_service = client.get_service('CustomerService')
        resource_names = customer_service.list_accessible_customers()

        print('Accessible customer resource names:')
        for resource_name in resource_names.resource_names:
            print(f' - {resource_name}')

    except GoogleAdsException as ex:
        print(f'Request with ID "{ex.request_id}" failed with status "{ex.error.code().name}" and includes the following errors:')
        for error in ex.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}')
    except Exception as e:
        print(f'An unexpected error occurred: {e}')

if __name__ == '__main__':
    # Set environment variables for authentication if not using google-ads.yaml
    # os.environ['GOOGLE_ADS_DEVELOPER_TOKEN'] = os.environ.get('GOOGLE_ADS_DEVELOPER_TOKEN', '')
    # os.environ['GOOGLE_ADS_CLIENT_ID'] = os.environ.get('GOOGLE_ADS_CLIENT_ID', '')
    # os.environ['GOOGLE_ADS_CLIENT_SECRET'] = os.environ.get('GOOGLE_ADS_CLIENT_SECRET', '')
    # os.environ['GOOGLE_ADS_REFRESH_TOKEN'] = os.environ.get('GOOGLE_ADS_REFRESH_TOKEN', '')
    # os.environ['GOOGLE_ADS_LOGIN_CUSTOMER_ID'] = os.environ.get('GOOGLE_ADS_LOGIN_CUSTOMER_ID', '') # Manager account ID

    main()
last verified Tue May 12
next check Sat Jul 11