{"id":984,"library":"google-ads","title":"Google Ads Python Client Library","description":"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.","status":"active","version":"49.0.0","language":"python","source_language":"en","source_url":"https://github.com/googleads/googleads-python-lib","tags":["google","ads","api","marketing","client-library"],"install":[{"cmd":"pip install google-ads","lang":"bash","label":"Install modern Google Ads API Client"}],"dependencies":[],"imports":[{"note":"The `googleads` package is an old, deprecated library. The modern client for the Google Ads API is `google-ads`, imported via `google.ads.googleads`.","wrong":"import googleads","symbol":"GoogleAdsClient","correct":"from google.ads.googleads.client import GoogleAdsClient"},{"symbol":"GoogleAdsException","correct":"from google.ads.googleads.errors import GoogleAdsException"}],"quickstart":{"code":"import os\nfrom google.ads.googleads.client import GoogleAdsClient\nfrom google.ads.googleads.errors import GoogleAdsException\n\ndef main():\n    try:\n        # Authenticate using google-ads.yaml or environment variables\n        # For environment variables, set GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID,\n        # GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN, GOOGLE_ADS_LOGIN_CUSTOMER_ID.\n        # login_customer_id is required for some API calls, and should be the ID of the manager account.\n        client = GoogleAdsClient.load_from_storage(version='v16') # Use the latest API version\n\n        # Example: Get a list of accessible customer IDs\n        customer_service = client.get_service('CustomerService')\n        resource_names = customer_service.list_accessible_customers()\n\n        print('Accessible customer resource names:')\n        for resource_name in resource_names.resource_names:\n            print(f' - {resource_name}')\n\n    except GoogleAdsException as ex:\n        print(f'Request with ID \"{ex.request_id}\" failed with status \"{ex.error.code().name}\" and includes the following errors:')\n        for error in ex.errors:\n            print(f'\\tError with message \"{error.message}\".')\n            if error.location:\n                for field_path_element in error.location.field_path_elements:\n                    print(f'\\t\\tOn field: {field_path_element.field_name}')\n    except Exception as e:\n        print(f'An unexpected error occurred: {e}')\n\nif __name__ == '__main__':\n    # Set environment variables for authentication if not using google-ads.yaml\n    # os.environ['GOOGLE_ADS_DEVELOPER_TOKEN'] = os.environ.get('GOOGLE_ADS_DEVELOPER_TOKEN', '')\n    # os.environ['GOOGLE_ADS_CLIENT_ID'] = os.environ.get('GOOGLE_ADS_CLIENT_ID', '')\n    # os.environ['GOOGLE_ADS_CLIENT_SECRET'] = os.environ.get('GOOGLE_ADS_CLIENT_SECRET', '')\n    # os.environ['GOOGLE_ADS_REFRESH_TOKEN'] = os.environ.get('GOOGLE_ADS_REFRESH_TOKEN', '')\n    # os.environ['GOOGLE_ADS_LOGIN_CUSTOMER_ID'] = os.environ.get('GOOGLE_ADS_LOGIN_CUSTOMER_ID', '') # Manager account ID\n\n    main()","lang":"python","description":"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."},"warnings":[{"fix":"Always install with `pip install google-ads` and import from `google.ads.googleads`.","message":"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`.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T22:12:51.263Z","next_check":"2026-07-11T00:00:00.000Z","problems":[{"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`.","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.","error":"ModuleNotFoundError: No module named 'google.ads.google_ads' (or 'googleads')"},{"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.","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.","error":"AttributeError: '_Rendezvous' object has no attribute 'request_id'"},{"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`.","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.","error":"google.auth.exceptions.RefreshError: invalid_grant (or AuthenticationError.NOT_ADS_USER, PERMISSION_DENIED)"},{"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.","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.","error":"ValueError: Specified Google Ads API version 'vX' does not exist. Valid API versions are: 'vY', 'vZ'"},{"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.","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.","error":"AttributeError: 'str' object has no attribute 'get' (when loading client config)"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"30.1.0","cli_name":"google-ads","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.61,"mem_mb":21.9,"disk_size":"264.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.53,"mem_mb":21.5,"disk_size":"223.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":14.1,"import_time_s":1.04,"mem_mb":20.5,"disk_size":"263M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.06,"mem_mb":20.1,"disk_size":"222M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":2.23,"mem_mb":24.2,"disk_size":"285.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.55,"mem_mb":23.9,"disk_size":"241.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":13.4,"import_time_s":1.68,"mem_mb":22.8,"disk_size":"284M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.62,"mem_mb":22.5,"disk_size":"240M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":2.27,"mem_mb":23.9,"disk_size":"274.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.4,"mem_mb":23.6,"disk_size":"230.7M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":13.2,"import_time_s":2.04,"mem_mb":22.6,"disk_size":"273M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.12,"mem_mb":22.3,"disk_size":"229M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":2.2,"mem_mb":24.4,"disk_size":"271.7M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.23,"mem_mb":24.1,"disk_size":"228.6M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":13.3,"import_time_s":1.83,"mem_mb":23.1,"disk_size":"270M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.01,"mem_mb":22.8,"disk_size":"227M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.47,"mem_mb":21.8,"disk_size":"264.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.4,"mem_mb":21.6,"disk_size":"223.7M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":16.8,"import_time_s":1.27,"mem_mb":20.4,"disk_size":"263M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.12,"mem_mb":20.2,"disk_size":"222M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}