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

Report fields

With the unification of reporting and queries, you no longer need to define a report. You can directly query the resources for the data using a SearchGoogleAdsRequest.

Start your report migration planning by consulting the appropriate field mapping tables below. These tables show the AdWords API field name and its equivalent in the Google Ads API.

Example

The Ad Group Performance Report and the Campaign Performance Report are two of the most frequently used AdWords API reports. We provide for comparison the equivalent queries in the AdWords Query Language (AWQL) and the Google Ads Query Language (GAQL):

Ad Group Performance Report
# AWQL
SELECT CampaignId, AdGroupId, Impressions, Clicks, Cost
FROM ADGROUP_PERFORMANCE_REPORT
DURING LAST_7_DAYS

# Google Ads Query Language
SELECT campaign.id, ad_group.id, metrics.impressions, metrics.clicks,
       metrics.cost_micros
FROM ad_group
WHERE segments.date DURING LAST_7_DAYS
Campaign Performance Report
# AWQL
SELECT CampaignName, CampaignStatus, Device, Impressions, Clicks,
       Ctr, AverageCpc, Cost
FROM CAMPAIGN_PERFORMANCE_REPORT
DURING LAST_30_DAYS

# Google Ads Query Language
SELECT campaign.name, campaign.status, segments.device, metrics.impressions,
       metrics.clicks, metrics.ctr, metrics.average_cpc, metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Single versus multiple attribution reports

During migration, certain criteria specific reports in the AdWords API may require special consideration such as the Keywords Performance Report or the Age Range Performance Report. There are two kinds of such reports:

  • Single attribution reports, such as Criteria Performance Report or Keywords Performance Report, where only one of the triggering criteria (such as placement, age, keyword, etc.) is recorded for a given impression: An impression may be triggered by multiple criteria, but on a single attribution report the impression and all of its stats are attributed only to a single criterion.

  • Multiple attribution reports, such as Gender Performance Report or Placement Performance Report, where up to one criterion in each dimension that triggered the impression has the impression recorded for it: Multiple attribution reports can be thought of as criteria type-specific reports. Unlike single attribution where a row can contain different criteria types, each multiple attribution report contains criteria for only one criteria type.

In the Google Ads API, there are no single attribution reports. All Google Ads API criteria-level reports are multi-attribution in the sense that each report is specific to one criterion type group, and summarizes statistics according to criteria of that type. Do not add statistics together from different criteria_view resources, as that would lead to double-counting and incorrect totals.

includeZeroImpressions HTTP header

AdWords API

In the AdWords API, you can use the includeZeroImpressions header to control whether report rows where all specified metrics fields in the query have zero values are to be returned.

Set the header to true, the report output includes such rows; for false, it doesn't.

Although the name of the header mentions "Impressions", a report row must have zero in all specified metrics fields in the request (not just impressions) in order to be excluded when the header is set to false.

There is no such header in the Google Ads API, so you cannot map the AdWords API queries directly to queries in the Google Ads API.

As an approximation, you can specify the predicate metrics.impressions > 0 in your query to exclude report rows whose impressions are zero. For most cases, this produces equivalent results as setting the AdWords API includeZeroImpressions header to false since when impressions are non-zero, other metrics values are often non-zero as well.

However, be aware of cases where metrics.impressions is zero but other metrics values (such as the prediction-based metrics.search_impression_share) might not be, and so a report row could still be returned.