pyaw-reporting 0.0.7

AdWords API Reporting in Python

Google Ads Reporting in Python

An AdWords API large scale reporting tool written in Python. Reports are downloaded as plaintext files but connectivity with a database engine such as MySQL, PostgreSQL, or MongoDB can be implemented upon request.

Overview

pyaw-reporting is an open-source Python package suitable for large scale Google Ads reports. Output reports are comma-separated values (CSV) plaintext files. By default, the package uses 10 threads to download reports simultaneously from different accounts. The number of threads used can be modified using the -n parameter. It has been successfully tested using +100 threads making it useful for heavy load AdWords Manager Accounts.

Supported AdWords API version

The latest API version supported by this package is v201809 with googleads 28.0.0. Older versions of the API are not supported, nor the newer Google Ads API.

Quick Start

Prerequisites

You will need Python 3.6+; this package installs googleads as a dependency. Note that that support for Python 2.7 ended in 2019. Using a virtual environment is recommended to avoid running the package with sudo.

An access token YAML file with the corresponding AdWords credentials is also necessary. By default, the package will look for ~/googleads.yaml unless a different path is passed. The optional parameter client_customer_id must be included in this YAML file, you should enter your AdWords Manager Account id (formerly known as MCC id). This way, all accounts linked to the Manager Account will be retrieved. The sample file example.yaml shows how your token should look like.

AWQL queries could be either passed in the command line with the -a/--awql parameter or stored in a plaintext file and passed via the -q/--query parameter. The module includes a sample query which will retrieve clicks and impressions per ad for the last 7 days. Refer to Report Types and The AdWords Query Language (AWQL) for more information about these queries.

Installation

$ pip install pyaw-reporting

Usage

Command line

usage: awreporting [-h] (-a AWQL | -q QUERY_FILE) [-t TOKEN] [-o OUTPUT]
                   [-n NUM_THREAD] [-v]

AwReporting - Large scale AdWords reporting tool in Python

optional arguments:
  -h, --help                              show this help message and exit
  -t TOKEN, --token TOKEN                 specify AdWords YAML token path
  -o OUTPUT, --output OUTPUT              define output file name
  -n NUM_THREAD, --num-thread NUM_THREAD  set number of threads
  -v, --verbose                           display activity

required arguments:
  -a AWQL, --awql AWQL                    pass AWQL query
  -q QUERY_FILE, --query-file QUERY_FILE  ...or use a query file

For example:

$ awreporting -t example.yaml -a \
  "SELECT ExternalCustomerId, CampaignId, AdGroupId, Id, Date, Clicks, Impressions \
  FROM AD_PERFORMANCE_REPORT WHERE Impressions > 0 DURING LAST_7_DAYS" \
  -o adperformance.csv -n 100

Or, with a query file:

$ awreporting -t example.yaml -q query.txt -o adperformance.csv -n 100

If you experience problems downloading reports, check the resulting logs in awreporting.log or use the -v/--verbose parameter to verify if something is wrong with your token or AWQL query.

Code

If you prefer embedding this package in your own code, you could do like so:

from awreporting import get_report

query = (
    "SELECT ExternalCustomerId, CampaignId, AdGroupId, Id, Date, Clicks, Impressions "
    "FROM AD_PERFORMANCE_REPORT "
    "WHERE Impressions > 0 "
    "DURING LAST_7_DAYS"
)
get_report('example.yaml', query, 'adperformance.csv', 100)

About the YAML token

The example token file provided example.yaml is not valid. Refer to this guide if you are using the AdWords API for the first time.

Disclaimer

This is neither an official AdWords API repository nor a clone of AwReporting. Consider using AwReporting if you are a Java developer. This framework no longer supports Python 2.7; only Python 3.6 or greater are compatible since googleads requires it.

Troubleshooting

We recommend that you try the app with a few number of threads first (the default is 10) and increase the amount accordingly. The Google Ads server may complain when many API calls are made at the same time, but those exceptions are handled by the app. We have successfully generated huge report files using 200 threads.

When using this tool it might be necessary to enable a DNS cache in your system, such as nscd. This should eliminate DNS lookup problems when repeatedly calling the AdWords API server. For example, if you find many URLError: <urlopen error [Errno -2] Name or service not known> in your logs, enable the DNS cache.

In some Linux systems nscd is not enabled by default, but it can be started with:

# systemctl start nscd

Useful links

• https://developers.google.com/adwords/api/
• https://github.com/googleads/googleads-python-lib
• https://github.com/googleads/aw-reporting