This project hosts the Python client library for the Google Ads API.
- Distributed via PyPI.
- Easy management of credentials.
- Easy creation of Google Ads API service clients.
- Python 2.7.13+ / 3.5.3+
- pip
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
To authenticate your API calls, you must specify your client ID, client secret, refresh token, developer token, and, if you are authenticating with a manager account, a login customer id. 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.
You can run the following to retrieve a GoogleAdsClient instance using a configuration file named google-ads.yaml stored in your home directory:
client = google.ads.google_ads.client.GoogleAdsClient.load_from_storage()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')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 v0 use the
following:
google_ads_service = client.get_service('GoogleAdsService', version='v0')The currently available list of versions is:
'v0''v1'
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. 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.logIt'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.