Reporting Samples

The code samples below provide examples of common reporting functions using the AdWords API. Client Library.

Download a criteria performance report with selector

#!/usr/bin/env python
#
# Copyright 2016 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""This example downloads a criteria performance report.

To get report fields, run get_report_fields.py.

The LoadFromStorage method is pulling credentials and properties from a
"googleads.yaml" file. By default, it looks for this file in your home
directory. For more information, see the "Caching authentication information"
section of our README.

"""


import logging
import sys
from googleads import adwords

logging.basicConfig(level=logging.INFO)
logging.getLogger('suds.transport').setLevel(logging.DEBUG)


def main(client):
  report_downloader = client.GetReportDownloader(version='v201710')

  report = {
      'reportName': 'Last 7 days CRITERIA_PERFORMANCE_REPORT',
      'dateRangeType': 'LAST_7_DAYS',
      'reportType': 'CRITERIA_PERFORMANCE_REPORT',
      'downloadFormat': 'CSV',
      'selector': {
          'fields': ['CampaignId', 'AdGroupId', 'Id', 'CriteriaType',
                     'Criteria', 'FinalUrls', 'Impressions', 'Clicks', 'Cost']
      }
  }

  # You can provide a file object to write the output to. For this demonstration
  # we use sys.stdout to write the report to the screen.
  report_downloader.DownloadReport(
      report, sys.stdout, skip_report_header=False, skip_column_header=False,
      skip_report_summary=False, include_zero_impressions=True)


if __name__ == '__main__':
  adwords_client = adwords.AdWordsClient.LoadFromStorage()
  main(adwords_client)

Download a criteria performance report with AWQL

#!/usr/bin/env python
#
# Copyright 2016 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""This example downloads a criteria performance report with AWQL.

To get report fields, run get_report_fields.py.

The LoadFromStorage method is pulling credentials and properties from a
"googleads.yaml" file. By default, it looks for this file in your home
directory. For more information, see the "Caching authentication information"
section of our README.

"""

import sys
from googleads import adwords


def main(client):
  # Initialize appropriate service.
  report_downloader = client.GetReportDownloader(version='v201710')

  # Create report query.
  report_query = (adwords.ReportQueryBuilder()
                  .Select('CampaignId', 'AdGroupId', 'Id', 'Criteria',
                          'CriteriaType', 'FinalUrls', 'Impressions', 'Clicks',
                          'Cost')
                  .From('CRITERIA_PERFORMANCE_REPORT')
                  .Where('Status').In('ENABLED', 'PAUSED')
                  .During('LAST_7_DAYS')
                  .Build())

  # You can provide a file object to write the output to. For this
  # demonstration we use sys.stdout to write the report to the screen.
  report_downloader.DownloadReportWithAwql(
      report_query, 'CSV', sys.stdout, skip_report_header=False,
      skip_column_header=False, skip_report_summary=False,
      include_zero_impressions=True)


if __name__ == '__main__':
  # Initialize client object.
  adwords_client = adwords.AdWordsClient.LoadFromStorage()

  main(adwords_client)

Get report fields

#!/usr/bin/env python
#
# Copyright 2016 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""This example gets report fields.

The LoadFromStorage method is pulling credentials and properties from a
"googleads.yaml" file. By default, it looks for this file in your home
directory. For more information, see the "Caching authentication information"
section of our README.

"""

from googleads import adwords


REPORT_TYPE = 'INSERT_REPORT_TYPE_HERE'


def main(client, report_type):
  # Initialize appropriate service.
  report_definition_service = client.GetService(
      'ReportDefinitionService', version='v201710')

  # Get report fields.
  fields = report_definition_service.getReportFields(report_type)

  # Display results.
  print 'Report type "%s" contains the following fields:' % report_type
  for field in fields:
    print ' - %s (%s)' % (field['fieldName'], field['fieldType'])
    if 'enumValues' in field:
      print '  := [%s]' % ', '.join(field['enumValues'])


if __name__ == '__main__':
  # Initialize client object.
  adwords_client = adwords.AdWordsClient.LoadFromStorage()

  main(adwords_client, REPORT_TYPE)

Stream criteria report results

#!/usr/bin/env python
#
# Copyright 2016 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""This example retrieves the report download stream.

To get report fields, run get_report_fields.py.

The LoadFromStorage method is pulling credentials and properties from a
"googleads.yaml" file. By default, it looks for this file in your home
directory. For more information, see the "Caching authentication information"
section of our README.

"""


import logging
import StringIO
import sys
from googleads import adwords


logging.basicConfig(level=logging.INFO)
logging.getLogger('suds.transport').setLevel(logging.DEBUG)

# The chunk size used for the report download.
CHUNK_SIZE = 16 * 1024


def main(client):
  report_downloader = client.GetReportDownloader(version='v201710')

  # Create report definition.
  report = {
      'reportName': 'Last 7 days CRITERIA_PERFORMANCE_REPORT',
      'dateRangeType': 'LAST_7_DAYS',
      'reportType': 'CRITERIA_PERFORMANCE_REPORT',
      'downloadFormat': 'CSV',
      'selector': {
          'fields': ['CampaignId', 'AdGroupId', 'Id', 'CriteriaType',
                     'Criteria', 'FinalUrls', 'Impressions', 'Clicks', 'Cost']
      }
  }

  # Retrieve the report stream and print it out
  report_data = StringIO.StringIO()
  stream_data = report_downloader.DownloadReportAsStream(
      report, skip_report_header=False, skip_column_header=False,
      skip_report_summary=False, include_zero_impressions=True)

  try:
    while True:
      chunk = stream_data.read(CHUNK_SIZE)
      if not chunk: break
      report_data.write(chunk.decode() if sys.version_info[0] == 3
                        and getattr(report_data, 'mode', 'w') == 'w' else chunk)
    print report_data.getvalue()
  finally:
    report_data.close()
    stream_data.close()


if __name__ == '__main__':
  adwords_client = adwords.AdWordsClient.LoadFromStorage()
  main(adwords_client)

Download criteria report as a stream with AWQL

#!/usr/bin/env python
#
# Copyright 2016 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""This example downloads a criteria performance report as a stream with AWQL.

To get report fields, run get_report_fields.py.

The LoadFromStorage method is pulling credentials and properties from a
"googleads.yaml" file. By default, it looks for this file in your home
directory. For more information, see the "Caching authentication information"
section of our README.

"""


import logging
import StringIO
import sys

from googleads import adwords


logging.basicConfig(level=logging.INFO)
logging.getLogger('suds.transport').setLevel(logging.DEBUG)

# Specify where to download the file here.
PATH = '/tmp/report_download.csv'
# The chunk size used for the report download.
CHUNK_SIZE = 16 * 1024


def main(client):
  # Initialize appropriate service.
  report_downloader = client.GetReportDownloader(version='v201710')

  # Create report query.
  report_query = (adwords.ReportQueryBuilder()
                  .Select('CampaignId', 'AdGroupId', 'Id', 'Criteria',
                          'CriteriaType', 'FinalUrls', 'Impressions', 'Clicks',
                          'Cost')
                  .From('CRITERIA_PERFORMANCE_REPORT')
                  .Where('Status').In('ENABLED', 'PAUSED')
                  .During('LAST_7_DAYS')
                  .Build())

  print report_downloader.DownloadReportAsStringWithAwql(
      report_query, 'CSV', skip_report_header=False, skip_column_header=False,
      skip_report_summary=False, include_zero_impressions=True)

  # Retrieve the report stream and print it out
  report_data = StringIO.StringIO()
  stream_data = report_downloader.DownloadReportAsStreamWithAwql(report_query,
                                                                 'CSV')

  try:
    while True:
      chunk = stream_data.read(CHUNK_SIZE)
      if not chunk: break
      report_data.write(chunk.decode() if sys.version_info[0] == 3
                        and getattr(report_data, 'mode', 'w') == 'w' else chunk)
    print report_data.getvalue()
  finally:
    report_data.close()
    stream_data.close()


if __name__ == '__main__':
  # Initialize client object.
  adwords_client = adwords.AdWordsClient.LoadFromStorage()

  main(adwords_client)

Download criteria performance report as a string

#!/usr/bin/env python
#
# Copyright 2016 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""This example downloads a criteria performance report as a string.

To get report fields, run get_report_fields.py.

The LoadFromStorage method is pulling credentials and properties from a
"googleads.yaml" file. By default, it looks for this file in your home
directory. For more information, see the "Caching authentication information"
section of our README.

"""


import logging
from googleads import adwords

logging.basicConfig(level=logging.INFO)
logging.getLogger('suds.transport').setLevel(logging.DEBUG)


def main(client):
  report_downloader = client.GetReportDownloader(version='v201710')

  # Create report definition.
  report = {
      'reportName': 'Last 7 days CRITERIA_PERFORMANCE_REPORT',
      'dateRangeType': 'LAST_7_DAYS',
      'reportType': 'CRITERIA_PERFORMANCE_REPORT',
      'downloadFormat': 'CSV',
      'selector': {
          'fields': ['CampaignId', 'AdGroupId', 'Id', 'CriteriaType',
                     'Criteria', 'FinalUrls', 'Impressions', 'Clicks', 'Cost']
      }
  }

  # Print out the report as a string
  print report_downloader.DownloadReportAsString(
      report, skip_report_header=False, skip_column_header=False,
      skip_report_summary=False, include_zero_impressions=True)


if __name__ == '__main__':
  adwords_client = adwords.AdWordsClient.LoadFromStorage()
  main(adwords_client)

Download criteria performance report as a string with AWQL

#!/usr/bin/env python
#
# Copyright 2016 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""This example downloads a criteria performance report as a string with AWQL.

To get report fields, run get_report_fields.py.

The LoadFromStorage method is pulling credentials and properties from a
"googleads.yaml" file. By default, it looks for this file in your home
directory. For more information, see the "Caching authentication information"
section of our README.

"""

from googleads import adwords


# Specify where to download the file here.
PATH = '/tmp/report_download.csv'


def main(client):
  # Initialize appropriate service.
  report_downloader = client.GetReportDownloader(version='v201710')

  # Create report query.
  report_query = (adwords.ReportQueryBuilder()
                  .Select('CampaignId', 'AdGroupId', 'Id', 'Criteria',
                          'CriteriaType', 'FinalUrls', 'Impressions', 'Clicks',
                          'Cost')
                  .From('CRITERIA_PERFORMANCE_REPORT')
                  .Where('Status').In('ENABLED', 'PAUSED')
                  .During('LAST_7_DAYS')
                  .Build())

  print report_downloader.DownloadReportAsStringWithAwql(
      report_query, 'CSV', skip_report_header=False, skip_column_header=False,
      skip_report_summary=False, include_zero_impressions=True)


if __name__ == '__main__':
  # Initialize client object.
  adwords_client = adwords.AdWordsClient.LoadFromStorage()

  main(adwords_client)

Parallel report download

#!/usr/bin/env python
#
# Copyright 2016 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""This example downloads an adgroup performance report for all child accounts.

To get report fields, run get_report_fields.py.

The LoadFromStorage method is pulling credentials and properties from a
"googleads.yaml" file. By default, it looks for this file in your home
directory. For more information, see the "Caching authentication information"
section of our README.

"""

import logging
import multiprocessing
from Queue import Empty
import time
import googleads

logging.basicConfig(level=logging.INFO)
logging.getLogger('suds.transport').setLevel(logging.DEBUG)

# Timeout between retries in seconds.
BACKOFF_FACTOR = 5
# Maximum number of processes to spawn.
MAX_PROCESSES = multiprocessing.cpu_count()
# Maximum number of retries for 500 errors.
MAX_RETRIES = 5
# Maximum number of items to be sent in a single API response.
PAGE_SIZE = 100
# Directory to download the reports to.
REPORT_DOWNLOAD_DIRECTORY = 'INSERT_REPORT_DOWNLOAD_DIRECTORY'


def main(client, report_download_directory):
  # Determine list of customer IDs to retrieve report for.
  input_queue = GetCustomerIDs(client)
  reports_succeeded = multiprocessing.Queue()
  reports_failed = multiprocessing.Queue()

  # Create report definition.
  report_definition = {
      'reportName': 'Custom ADGROUP_PERFORMANCE_REPORT',
      'dateRangeType': 'LAST_7_DAYS',
      'reportType': 'ADGROUP_PERFORMANCE_REPORT',
      'downloadFormat': 'CSV',
      'selector': {
          'fields': ['CampaignId', 'AdGroupId', 'Impressions', 'Clicks',
                     'Cost'],
          # Predicates are optional.
          'predicates': {
              'field': 'AdGroupStatus',
              'operator': 'IN',
              'values': ['ENABLED', 'PAUSED']
          }
      },
  }

  queue_size = input_queue.qsize()
  num_processes = min(queue_size, MAX_PROCESSES)
  print 'Retrieving %d reports with %d processes:' % (queue_size, num_processes)

  # Start all the processes.
  processes = [ReportWorker(client, report_download_directory,
                            report_definition, input_queue, reports_succeeded,
                            reports_failed)
               for _ in range(num_processes)]

  for process in processes:
    process.start()

  for process in processes:
    process.join()

  print 'Finished downloading reports with the following results:'
  while True:
    try:
      success = reports_succeeded.get(timeout=0.01)
    except Empty:
      break
    print '\tReport for CustomerId "%d" succeeded.' % success['customerId']

  while True:
    try:
      failure = reports_failed.get(timeout=0.01)
    except Empty:
      break
    print ('\tReport for CustomerId "%d" failed with error code "%s" and '
           'message: %s.' % (failure['customerId'], failure['code'],
                             failure['message']))


class ReportWorker(multiprocessing.Process):
  """A worker Process used to download reports for a set of customer IDs."""

  _FILENAME_TEMPLATE = 'adgroup_%d.csv'
  _FILEPATH_TEMPLATE = '%s/%s'

  def __init__(self, client, report_download_directory, report_definition,
               input_queue, success_queue, failure_queue):
    """Initializes a ReportWorker.

    Args:
      client: An AdWordsClient instance.
      report_download_directory: A string indicating the directory where you
        would like to download the reports.
      report_definition: A dict containing the report definition that you would
        like to run against all customer IDs in the input_queue.
      input_queue: A Queue instance containing all of the customer IDs that
        the report_definition will be run against.
      success_queue: A Queue instance that the details of successful report
        downloads will be saved to.
      failure_queue: A Queue instance that the details of failed report
        downloads will be saved to.
    """
    super(ReportWorker, self).__init__()
    self.report_downloader = client.GetReportDownloader(version='v201710')
    self.report_download_directory = report_download_directory
    self.report_definition = report_definition
    self.input_queue = input_queue
    self.success_queue = success_queue
    self.failure_queue = failure_queue

  def _DownloadReport(self, customer_id):
    filepath = self._FILEPATH_TEMPLATE % (self.report_download_directory,
                                          self._FILENAME_TEMPLATE % customer_id)
    retry_count = 0

    while True:
      print ('[%d/%d] Loading report for customer ID "%s" into "%s"...'
             % (self.ident, retry_count, customer_id, filepath))
      try:
        with open(filepath, 'wb') as handler:
          self.report_downloader.DownloadReport(
              self.report_definition, output=handler,
              client_customer_id=customer_id)
        return (True, {'customerId': customer_id})
      except googleads.errors.AdWordsReportError, e:
        if e.code == 500 and retry_count < MAX_RETRIES:
          time.sleep(retry_count * BACKOFF_FACTOR)
        else:
          print ('Report failed for customer ID "%s" with code "%d" after "%d" '
                 'retries.' % (customer_id, e.code, retry_count+1))
          return (False, {'customerId': customer_id, 'code': e.code,
                          'message': e.message})
      except Exception, e:
        print 'Report failed for customer ID "%s".' % customer_id
        print 'e: %s' % e.__class__
        return (False, {'customerId': customer_id, 'code': None,
                        'message': e.message})

  def run(self):
    while True:
      try:
        customer_id = self.input_queue.get(timeout=0.01)
      except Empty:
        break
      result = self._DownloadReport(customer_id)
      (self.success_queue if result[0] else self.failure_queue).put(result[1])


def GetCustomerIDs(client):
  """Retrieves all CustomerIds in the account hierarchy.

  Note that your configuration file must specify a client_customer_id belonging
  to an AdWords manager account.

  Args:
    client: an AdWordsClient instance.

  Raises:
    Exception: if no CustomerIds could be found.

  Returns:
    A Queue instance containing all CustomerIds in the account hierarchy.
  """
  # For this example, we will use ManagedCustomerService to get all IDs in
  # hierarchy that do not belong to MCC accounts.
  managed_customer_service = client.GetService('ManagedCustomerService',
                                               version='v201710')

  offset = 0

  # Get the account hierarchy for this account.
  selector = {'fields': ['CustomerId'],
              'predicates': [{
                  'field': 'CanManageClients',
                  'operator': 'EQUALS',
                  'values': [False]
              }],
              'paging': {
                  'startIndex': str(offset),
                  'numberResults': str(PAGE_SIZE)}}

  # Using Queue to balance load between processes.
  queue = multiprocessing.Queue()
  more_pages = True

  while more_pages:
    page = managed_customer_service.get(selector)

    if page and 'entries' in page and page['entries']:
      for entry in page['entries']:
        queue.put(entry['customerId'])
    else:
      raise Exception('Can\'t retrieve any customer ID.')
    offset += PAGE_SIZE
    selector['paging']['startIndex'] = str(offset)
    more_pages = offset < int(page['totalNumEntries'])

  return queue


if __name__ == '__main__':
  adwords_client = googleads.adwords.AdWordsClient.LoadFromStorage()
  main(adwords_client, REPORT_DOWNLOAD_DIRECTORY)

Send feedback about...

AdWords API
AdWords API
Need help? Visit our support page.