Configuration

  • Clients can be configured using a YAML file, environment variables, a YAML string, or a Python dictionary.

  • Configuration using a YAML file can be loaded from a default location or a specified path using load_from_storage.

  • Client configuration can be stored as environment variables, which are read using the load_from_env method.

  • You can load configuration directly from a YAML string using load_from_string or from a Python dictionary using load_from_dict.

  • Various configuration fields are available for general settings, authentication, and logging.

You can configure the Python client library using a YAML file, environment variables, a YAML string, or a dict.

Authentication configuration

There are multiple ways to manage the OAuth credentials needed to access the Google Ads API. The approach you choose affects which configuration fields you use. For more information, see the authentication guide.

Configuration using YAML file

You can specify a YAML file to use when initializing the client that contains the necessary information needed to make requests to the Google Ads API. This file is accessed when a client is initialized using the load_from_storage method. The easiest way to generate this file is to copy the google-ads.yaml example from the GitHub repository and modify it to include your credentials, including your refresh token, client ID, and client secret.

If you don't provide a path, the library looks in your $HOME directory for the file:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

To specify a location where the google-ads.yaml file is located, you can pass the path as a string to the method when calling it:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

You can also specify the path by defining a specific environment variable:

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

os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
client = GoogleAdsClient.load_from_storage()

If both values are provided—a path is passed into the method, and the environment variable is present—then the library prioritizes the path passed into the method.

Configuration using environment variables

You can store all of your client configuration as environment variables, which are read when using the client's load_from_env method. Environment variables should have the same name as those defined in the google-ads.yaml file, but must be all uppercase and prefixed with the GOOGLE_ADS_ namespace. For example, client_id should be stored as GOOGLE_ADS_CLIENT_ID.

Environment variables are commonly defined in a bash configuration file such as a .bashrc or .bash_profile file located in the $HOME directory. They can also be defined using the command line.

Here are some basic steps to define an environment variable using a .bashrc file in a terminal:

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

Environment variables can also be set in your terminal instance directly from the command line:

export GOOGLE_ADS_CLIENT_ID=1234567890
echo $GOOGLE_ADS_CLIENT_ID

The load_from_env method loads configuration data from the environ attribute on Python's built-in os module. For example: os.environ["GOOGLE_ADS_CLIENT_ID"]

Here's an example of how to initialize a client instance with configuration from environment variables:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

In order to configure logging through environment variables, the configuration value must be a JSON object that matches the structure of the YAML keys in the sample google-ads.yaml configuration file.

Here's an example of how this could be set using a .bashrc file:

export GOOGLE_ADS_LOGGING='{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "default_fmt": {
      "format": "[%(asctime)s - %(levelname)s] %(message).5000s",
      "datefmt": "%Y-%m-%d %H:%M:%S"
    }
  },
  "handlers": {
    "default_handler": {
      "class": "logging.StreamHandler",
      "formatter": "default_fmt"
    }
  },
  "loggers": {
    "": {
      "handlers": ["default_handler"],
      "level": "INFO"
    }
  }
}'

Key point: If the environment variable GOOGLE_ADS_CONFIGURATION_FILE_PATH is set when the load_from_env method is called, then configuration values are retrieved from the google-ads.yaml file located at the specified path, not from the environment variables described earlier.

Configuration using a YAML string

If you have read a YAML file into memory, you can provide it directly to the client on initialization. To do this, use the load_from_string method:

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "r", encoding="utf-8") as handle:
    yaml_content = handle.read()

client = GoogleAdsClient.load_from_string(yaml_content)

Configuration using a dict

You can pass a dict directly to the load_from_dict method. For example:

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "use_proto_plus": True,
}

client = GoogleAdsClient.load_from_dict(credentials)

Configuration fields

The client library configuration supports the following fields.

Authentication

Only use one of these groups of fields, depending on which authentication approach you're using:

  • Single-user with application default credentials (documentation)
    • use_application_default_credentials: Whether the library should use application default credentials (ADC) for authentication (supported in google-ads v28.3.0 and later).
  • Single-user with OAuth tokens (documentation)
    • client_id: Your OAuth client ID.
    • client_secret: Your OAuth client secret.
    • refresh_token: Your OAuth refresh token.
  • Service-account (documentation)
    • json_key_file_path: A path to a local private key file. This is used for authenticating using a service account.
    • impersonated_email: Optional email address of the account to impersonate when using Google Workspace domain-wide delegation.

Library behavior

These fields dictate the behavior of the library:

Request-level configuration

Environment variables

To configure the library using environment variables, use the following:

  • GOOGLE_ADS_ADS_ASSISTANT
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_ENDPOINT
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_IMPERSONATED_EMAIL
  • GOOGLE_ADS_JSON_KEY_FILE_PATH
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_USE_PROTO_PLUS
  • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS (supported in v28.3.0 and later)

Log configuration

Log fields, which are fields underneath the logging configuration field, are derived directly from the logging.config built-in module because the library passes all fields under the logging namespace directly to the logging.config.dictConfig method. See the logging guide for complete details.

  • version: An integer value representing a schema version.
  • disable_existing_loggers: Whether loggers configured elsewhere in the application should be disabled.
  • formatters: Dictionaries defining different kinds of formatters.
  • handlers: Dictionaries defining different handlers, which control where logs are written to and which formatters should be used.
  • loggers: Dictionaries defining different types of loggers, which include a handler and a log level.