Google Ads API Client Library for Python

This project hosts the Python client library for the Google Ads API.

Build Status

Features

Distributed via PyPI.
Easy management of credentials.
Easy creation of Google Ads API service clients.

Requirements

Python 3.7+
- NOTE: Python 2 support has ceased as of v4.0. See this blog post for more detail.
pip

Documentation

This README has general information to get you started with the library, but more extensive documentation can be found on our Developer Site.

Getting started

Installation

This library is distributed via PyPI. If you have not already done so, install pip, the following command to install this client library:

pip install google-ads

Configuration file setup

To authenticate your API calls, you must specify your client ID, client secret, refresh token, developer token, or, if you are authenticating via a service account you will instead need to specify a path_to_private_key_file and delegate_account. If you are authenticating with a manager account you will need to provide a login customer id configuration value.

If you have not yet created a client ID, see the Authorization guide and the authentication samples to get started. Likewise, see Obtain your developer token if you do not yet have one.

When initializing a GoogleAdsClient instance via the load_from_storage class method, the default behavior is to load a configuration file named google-ads.yaml located in your home directory. Included in this repository is a template you can use.

For a complete walk-through of how to configure this library, please refer to our configuration documentation.

OAuth2 Options

This client library can authenticate using one of three different OAuth2 flows, either the Installed Application Flow, the Web Application Flow or the Service Account Flow. The Installed Application Flow and Web Application Flow use the same credentials and are functionally identical in terms of configuring this library. When retrieving the configuration for these authentication flows, if configuration is present for _both_ types of flows the library will default to using the Installed/Web Application Flow. If you wish to use the Service Account Flow you must make sure that the Installed/Web Application Flow configuration values are not present in your configuration.

Create a GoogleAdsClient

Using YAML file

You can run the following to retrieve a GoogleAdsClient instance using a configuration file named google-ads.yaml stored in your home directory:

from google.ads.google_ads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

Using environment variables

You can also retrieve it by exporting environment variables.

Required:

export GOOGLE_ADS_DEVELOPER_TOKEN=INSERT_DEVELOPER_TOKEN_HERE

Required for OAuth2 Installed Application Flow

export GOOGLE_ADS_CLIENT_ID=INSERT_OAUTH2_CLIENT_ID_HERE
export GOOGLE_ADS_CLIENT_SECRET=INSERT_OAUTH2_CLIENT_SECRET_HERE
export GOOGLE_ADS_REFRESH_TOKEN=INSERT_REFRESH_TOKEN_HERE

Required for OAuth2 Service Account Flow:

export GOOGLE_ADS_PATH_TO_PRIVATE_KEY_FILE=INSERT_PRIVATE_KEY_PATH_HERE
export GOOGLE_ADS_DELEGATED_ACCOUNT=INSERT_DELEGATED_ACCOUNT_HERE

Optional:

export GOOGLE_ADS_LOGIN_CUSTOMER_ID=INSERT_LOGIN_CUSTOMER_ID_HERE
export GOOGLE_ADS_LOGGING=INSERT_GOOGLE_ADS_LOGGING

GOOGLE_ADS_LOGGING should be a JSON with logging configuration. Example:

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

Then run the following to retrieve a GoogleAdsClient instance:

from google.ads.google_ads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

The configuration documentation has more information on how these different sets of variables are set and retrieved.

Get types and service clients

You can use a GoogleAdsClient instance to retrieve any type or service used by the API. To retrieve a type such as a CampaignOperation, provide its name to the get_type method:

campaign_operation = client.get_type('CampaignOperation')

Likewise, you can provide the name of a service to get_service in order to retrieve the corresponding service client instance:

google_ads_service = client.get_service('GoogleAdsService')

More details can be found in our proto getters documentation.

API versioning

With the release of Google Ads API v1_0 it's now possible to specify an API version when getting services and types. The get_service and get_type client methods accept a second named parameter, version that refers to a valid API version. For example, to request an instance of the GoogleAdsService that uses Google Ads API version v2 use the following:

google_ads_service = client.get_service('GoogleAdsService', version='v2')

The currently available list of versions is:

'v1'
'v2'

Enabling and Configuring logging

The library uses Python's built in logging framework. You can specify your configuration via the configuration file (see google-ads.yaml for an example) or GOOGLE_ADS_LOGGING environment variable. The library logs to stderr by default. You can easily pipe log messages to a file; when running an example:

python example.py args 2> example.log

It's also possible to configure logging programmatically using Python's built-in logging library by setting a logging configuration before initializing the client. You can retrieve the client logger instance and configure it with the following example:

logging.basicConfig(level=logging.INFO, format='[%(asctime)s - %(levelname)s] %(message).5000s')
logging.getLogger('google.ads.google_ads.client').setLevel(logging.INFO)

NOTE: The client logger is configured when the client is initialized, so if you have logger configurations in your google-ads.yaml file and you want to override them programmatically, you will need to call the above lines _before_ initializing the client, otherwise the configuration from yaml will take precedent as it's provided first.

The client generates logs at a few different levels and you can set your configuration to see some or all of the below:

Level	Successful Request	Failed Request
`DEBUG`	A detailed log with complete request and response objects as JSON.	None
`INFO`	A concise summary with specific request and response fields.	A detailed log with complete request and exception objects as JSON.
`WARNING`	None	A concise summary with specific request information, the exception state and message.

Since the Python logging framework ignores log messages that are less severe than the configured level, setting to WARNING means you will only see concise messages related to failed requests, but setting to DEBUG means you will see all possible types of logs in the above table.

erniegerdie/google-ads-python