To discuss and provide feedback on our products, join the official Google Ads Discord channel in the Google Advertising and Measurement Community server.

Configuration

AI-generated Key Takeaways

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.

There are multiple different ways to configure the client.

Authentication configuration

There are multiple ways to manage the OAuth credentials needed to access the Google Ads API. The approach you choose will affect which configuration fields you use. For more information see our 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 developer token, refresh token, client ID, and client secret.

If you don't provide a path, the library will look 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

os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
from google.ads.googleads.client import GoogleAdsClient
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 will prioritize the path passed into the method.

Configuration using environment variables

You can store all of your client configuration as environment variables, which will be 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 should 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. Note that these instructions assume you're using bash, if you're using a different shell you may need to consult documentation on how to set environment variables in the shell you're using.

Here are some basic steps to define an environment variable using a .bashrc file using 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.
$ src ~/.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
1234567890

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"
    }
  }
}'

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 just use the load_from_string method.

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "rb") as handle:
    yaml = handle.read()

client = GoogleAdsClient.load_from_string(yaml)

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 = {
    "developer_token": "abcdef123456",
    "refresh_token": "1//0abcdefghijklABCDEF",
    "client_id": "123456-abcdef.apps.googleusercontent.com",
    "client_secret": "aBcDeFgHiJkL"}

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.
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.

Library behavior

These fields dictate the behavior of the library:

logging: See logging configuration details.
http_proxy: See the proxy documentation.
use_proto_plus: Whether or not to use proto-plus messages. See the protobuf messages documentation.

Request-level configuration

developer_token: REQUIRED Your developer token for accessing the API.
linked_customer_id: See the linked-customer-id documentation.
login_customer_id: See the login-customer-id documentation.

Environment variables

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

GOOGLE_ADS_CLIENT_ID
GOOGLE_ADS_CLIENT_SECRET
GOOGLE_ADS_CONFIGURATION_FILE_PATH
GOOGLE_ADS_DEVELOPER_TOKEN
GOOGLE_ADS_HTTP_PROXY
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

Logging configuration

Logging fields, which are fields underneath the logging configuration field, are derived directly from the logging.config built-in module because the library will pass 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.