Tag Archives: reporting

Sunset of the Average Position Metric in AdWords and Google Ads APIs

In the week of September 30, 2019, the average position metric will be sunset. This change was announced this past February in the Google Ads Help Center. The new alternatives were described in this November 2018 blog post. Once the sunset occurs, requests for the average position (AdWords API, Google Ads API) will return NULL values.

In the AdWords API v201809, NULL values are returned as two dashes. In the Google Ads API, NULL values are returned as NullValues.

If you use ValueTrack parameters, we encourage you to remove the ValueTrack parameter {adposition} from your tracking templates. When average position is sunset, the ValueTrack parameter {adposition} will begin returning the empty string.

Note that average position has already been removed from the current beta version of the Google Ads API, but is accessible in the earlier V1_x versions.

In lieu of average position, we recommend you use the new metrics of Impression (Absolute Top) %" and "Impression (Top) %. These are the new metrics:

Absolute Top Metrics
AdWords API Google Ads API
AbsoluteTopImpressionPercentage absolute_top_impression_percentage
SearchAbsoluteTopImpressionShare search_absolute_top_impression_share
SearchBudgetLostAbsoluteTopImpressionShare search_budget_lost_absolute_top_impression_share
SearchRankLostAbsoluteTopImpressionShare search_rank_lost_absolute_top_impression_share


Top Metrics
AdWords API Google Ads API
TopImpressionPercentage top_impression_percentage
SearchTopImpressionShare search_top_impression_share
SearchBudgetLostTopImpressionShare search_budget_lost_top_impression_share
SearchRankLostTopImpressionShare search_rank_lost_top_impression_share


As always, don't hesitate to reach out to us on the developer forum with any questions.

Sunsetting the creation of target spend field for Maximize Clicks strategies in Google Ads API

On July 31st, 2019 we will begin to sunset the target spend field for Maximize Clicks bidding strategies in the API. This will affect all versions of both the AdWords API and Google Ads API. The following behaviors will be blocked:
  • Populating the target spend field on existing standard and portfolio strategies.
  • Attaching portfolio strategies that have the deprecated field set to campaigns.
Later this year, our systems will start ignoring the target spend field and instead use your daily budget to manage spend. In order to prepare for this change, you should start using your budgets to specify how much you’d like to spend for Maximize Clicks bidding strategies and migrate your campaigns off this field today.

Read on to see how this will affect your API usage.
Affected Target Spend Fields
Google Ads API campaign.target_spend.target_spend_micros
bidding_strategy.target_spend.target_spend_micros
AdWords API Campaign.BiddingStrategyConfiguration.TargetSpendBiddingScheme.spendTarget
SharedBiddingStrategy.TargetSpendBiddingScheme.spendTarget


Change Description
Any mutate operations that set a target spend field for the first time will return an error. You will be able to update a target spend field that currently contain a value, but you cannot set previously empty fields to a new value. Additionally, any operation attaching a bidding strategy to a campaign, where that bidding strategy has a value set for a target spend field, will throw an error. To manage Target Spend on any new campaigns, we recommend using a campaign budget. In each of these disallowed cases an error will be thrown.

Performing any of the disallowed actions above will generate one of the following errors:
  • OPERATION_NOT_PERMITTED_FOR_CONTEXT
  • UNSUPPORTED_FIELD_IS_SET
If you have any questions about this change or any other API feature, please contact us via the forum.

Introducing the Google Ads Query Builder tool

Today we are excited to announce that the Google Ads Query Builder tool is now available on the Google Ads API Developer Site.

The Google Ads API has a robust reporting system that utilizes our new Google Ads Query Language. The language’s syntax allows you to select from all the resources that are available for reporting, and also filter or sort the result set on the server before they are returned to your application.

This tool provides a friendly web interface for you to explore our API’s reporting capabilities, and generate queries that you can copy and paste right into your applications. You can visit the site and try out the tool today!

Example usage of the Google Ads Query Builder: A screenshot showing a sample usage of the Google Ads Query Builder UI, including both filtering and ordering. Happy reporting!

Change to the Google Ads API and the AdWords API Showcase Ads Clicks Reporting

Update (Feb 21, 2019): clarified wording of the Clicks impact.
On February 27, 2019, the data returned in the Clicks metric for Showcase ads will change in order to more accurately show you the interactions with products via Showcase ads in reporting.

In the AdWords API and the Google Ads API, the Clicks metric (clicks for Google Ads API) will change for the Shopping Performance Report and the Product Partition Report (product_group_view for Google Ads API) as follows:
  • Current reporting: Clicks only include charged clicks.
  • New reporting: Clicks will report all clicks, including free clicks. As a result, you may see a change in the number of reported clicks.
If you have questions, please reach out to us on the forum.

Top metrics, absolute top metrics, and average position in the AdWords API and Google Ads scripts

What's new
Starting November 12, 2018, the fields below will be available in AdWords API and Google Ads scripts reports.

Absolute top metrics:
  • AbsoluteTopImpressionPercentage
  • SearchAbsoluteTopImpressionShare
  • SearchBudgetLostAbsoluteTopImpressionShare
  • SearchRankLostAbsoluteTopImpressionShare
Top metrics:
  • TopImpressionPercentage
  • SearchTopImpressionShare
  • SearchBudgetLostTopImpressionShare
  • SearchRankLostTopImpressionShare
AbsoluteTopImpressionPercentage and TopImpressionPercentage are specific indicators of page location. You can use these metrics to determine when and where your impressions are showing above the organic search results.

SearchAbsoluteTopImpressionShare and SearchTopImpressionShare are your share of the eligible top impressions. They are the best indicators of the headroom available to show your ads in more prominent positions. If your goal is to bid on page location, you should use these metrics. Bidding by average position is not recommended since:
  • Average position doesn't actually describe position on the page but position in the auction.
  • Sometimes, average position may decrease as bids increase. This happens as higher bids sometimes allow you to enter more competitive auctions lower on the page.
See our post on the New features & announcements page for more details.

What you should do
Whenever you are using AveragePosition as a proxy to bid to a page location, switch to using the new SearchAbsoluteTopImpressionShare or SearchTopImpressionShare metrics in your bidding logic.

If you have any questions or need help, please contact us via the forum.

Changes to the URL Performance Report for YouTube video placements

What's changing?
The URL_PERFORMANCE_REPORT in the AdWords API will exclude information for YouTube video placements starting October 30, 2018, in keeping with our data retention policies. As a result, placements where the Url field has a domain of www.youtube.com will no longer appear in the report. New and improved placement reports will be available in one of the upcoming releases of the new Google Ads API.

What you should do
Review your application and workflows and make the necessary changes to ensure that the exclusion of video placements in this report will not cause problems. Watch this blog for updates regarding new placement reports in the Google Ads API.

If you have any questions or need help, please contact us via the forum.

Click measurement changes in AdWords

AdWords now allows you to enable parallel tracking for all advertisers from frontend and API. People who click your ads will go directly to your landing page while their browser handles click measurement requests in the background. This helps reduce lost visits which can happen if a customer clicks on your ad but never sees your landing page because they navigate away before the redirect from your tracking URL completes.

All ads using third-party click measurement will begin using parallel tracking at a later date. However, you should start developing for compatibility as soon as possible to give yourself enough time for the migration. If you implement your own click measurement server or provide this service to your customers, refer to our newly published guide for help with implementation. If you are an advertiser who uses a third-party measurement solution, reach out to your service provider to prepare for the switch.

If you need additional support, please email us at ads-clicktracking-support@google.com.

Upcoming changes to ad network type columns in AdWords API and Scripts reports

On March 19, 2018, we are updating how AdNetworkType1 and AdNetworkType2 columns report zero impression rows related to video networks.

Currently, if you request AdNetworkType1 or AdNetworkType2 columns and request zero impression rows by setting the includeZeroImpressions flag to true, you get back zero impression rows for YOUTUBE_SEARCH and YOUTUBE_WATCH values only if you target these networks in your Advertiser account. After this change, we will always return zero rows corresponding to these network types irrespective of whether you advertise on these networks. Other network types are not affected by this change.

This change makes the behavior of YOUTUBE_SEARCH and YOUTUBE_WATCH network types consistent with the behavior of other network types. Once this change goes live, you may start seeing a higher number of zero impression rows than what you see today when requesting AdNetworkType1 or AdNetworkType2 columns along with zero impression rows.

If you have any questions about these changes, post them in our developer forum.

Update to Engagement Reporting for Bumper Ads

Historically, AdWords API reporting has not included engagements for bumper ads. Bumper ads are video ads that are 6 seconds or shorter, appear at the beginning of a YouTube video, and can't be skipped.

Bumper ads support “drawer open” engagements, where a user can mouse over the ad to expand a widget with more information. These engagements were previously not included in the Engagements and EngagementRate fields in reports. Starting in mid-February 2018, we are going to be changing this behavior for all historical and future bumper ad reporting to include these engagements. This brings bumper ads in line with other types of video ads, which already reported these engagements.

This means that your historical reporting data, starting up to two years ago in January 2016, will be updated to include this statistic to bring it inline with future data.

If you have any questions about this migration, please contact us via the forum.

AdWords scripts now supports v201708 and v201710 in reports

We have added support for AdWords API v201708 and v201710 reports in AdWords scripts.

The major changes in v201708 are:
  • New fields in various report types.
  • The TABLE_EXTENSION enum value for ClickType was renamed to PRICE_EXTENSION.
  • See the full AdWords API release notes for more details.
The major changes in v201710 are:
  • The Automated field was added to the AD_PERFORMANCE_REPORT.
  • The EnhancedCpvEnabled field was removed from all reports.
  • See the full AdWords API release notes for more details.
In addition to these changes, v201705 is now the default version for reports. You can use one of the newly supported versions instead by specifying the apiVersion in your report request:
var report = AdWordsApp.report(query, {
apiVersion: 'v201710'
});

If you have any questions about these changes or AdWords scripts in general, you can post them on our developer forum.