Share your feedback about the Google Ads (AdWords) API. Take the 2021 AdWords API and Google Ads API Annual Survey.

Part 4 - Reporting overview

We now go over how reporting works in the Google Ads API, how it differs from reporting in the AdWords API, and how we'll use it in this codelab.

All reports in the Google Ads API go through the SearchStream and Search methods on the GoogleAdsService. These methods accept a GAQL string that specifies which resources should be retrieved, how they should be segmented, filtered, and ordered. The SearchStream and Search methods are also the recommended way to retrieve individual entities from the API.

In the AdWords API, you would use a GET method, for example, CampaignService.get. There are GET methods in the Google Ads API as well, but they're meant only for testing and debugging.

The Google Ads API reporting interface is the same whether you want to retrieve resource attributes or performance data for entities, and in most cases you can retrieve this information with a single query.

When migrating a report from the AdWords API, start with the Report migration guide. It contains a query migration tool that converts AWQL queries into GAQL queries that you can pass into a search request. There's even a page that maps each AdWords report Google Ads resources and fields.

Here is a typical AdWords API report query:

4.0.0: An AWQL Query Example (AdWords API)
SELECT
  CampaignId,
  AdGroupId,
  Impressions,
  Clicks,
  Cost
FROM ADGROUP_PERFORMANCE_REPORT
DURING LAST_7_DAYS
      

Using the query migration tool we can see that in Google Ads we should use:

4.0.1: A GAQL Query Example (Google Ads API)
SELECT
  campaign.id,
  ad_group.id,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM ad_group
WHERE segments.date DURING LAST_7_DAYS
      

We can then pass that query into a SearchStream request as a string:

4.0.2: Reporting Example in the Google Ads API
googleads_service = client.get_type("GoogleAdsService")

query = """
    SELECT
      campaign.id,
      ad_group.id,
      metrics.impressions,
      metrics.clicks,
      metrics.cost_micros
    FROM ad_group
    WHERE segments.date DURING LAST_7_DAYS"""

stream = googleads_service.search_stream(customer_id=_CUSTOMER_ID, query=query)

for response in stream
    for row in response:
        print(
            f"AdGroup with ID {row.ad_group.id} and campaign ID {row.campaign.id} "
            f"has {metrics.impressions} impressions, {metrics.clicks} clicks, "
            f"and has cost {metrics.cost_micros} micros over the past seven days."
        )