Today, we’re announcing the publishing of a new pre-written Script for reporting on Performance Max campaign performance in Google Ads scripts. This script will report on your conversions and other performance related metrics for your campaigns. The only thing needed to get it running is to copy the source code into your account and schedule the script to run daily.

How can I get started?
Find the script here.

If you have any questions or need additional help, contact us via the forum.
David Stevens, Google Ads Scripts Product Manager

The Google Ads Developers Channel is your video source for release notes, best practices, new feature integrations, code walkthroughs, and video tutorials. Check out some of the recently released and popular videos and playlists below, and remember to subscribe to our channel to stay up to date with the latest video content.

Google Ads API Best Practices - Error Handling and Debugging
In this episode of the Google Ads API Best Practices Series, we discuss how to handle errors that may occur when interacting with the Google Ads API, along with tools that may help you debug your applications, such as logging and the REST interface.
Meet the Team with David Wihl
In this video, David Wihl shares a bit about his role as a Developer Relations Engineer at Google and discusses his work in supporting the Performance Max campaign API integration.

[Live Demo] Building a Google Ads API Web App
Getting started with the Google Ads API? In this 8-episode series, we take a deep dive into developing web apps with the Google Ads API, with a focus on the OAuth flow, by building a multi-tenant app entirely from scratch.

Logging & Monitoring
This miniseries covers the basics of adding logging and monitoring to your Google Ads API integration and then goes into more advanced topics, with a special focus on Cloud tooling.

• Introduction
• Logging and Monitoring in the Cloud
• Sending Client Logs to Google Cloud
• Creating and Monitoring Custom Metrics

Google Ads Query Language (GAQL)
In this series, we cover everything you need to know about the Google Ads Query Language to make reporting requests against the Google Ads API. We begin with the basics and build in subsequent episodes to cover various nuances of GAQL. We even dive into the various tools available to help you structure your queries. This playlist will equip you with the information you need to know to become a GAQL power user.

• Getting Started with GAQL
  • Intro to Reporting & the Google Ads Query Language
  • Query Structure & Grammar
  • Segmentation
  • GoogleAdsRow
  • GetKeywordStats Coding Example
• Using the GoogleAdsFieldService
  • Retrieving Field Metadata
  • GAQL Fields and Clauses
• Query Validation
  • Understanding Field Compatibility
  • The SELECT Requirement
  • Date Range Validation
  • Constructing Filtering Conditions in the WHERE Clause
  • Validating GAQL Queries

For additional topics, including Authentication and Authorization and Working with REST, check out the Google Ads API Developer Series.

As always, feel free to reach out to us with any questions via the Google Ads API forum or at googleadsapi-support@google.com.
- Devin Chasanoff, on behalf of the Google Ads API Team

On January 5, 2022, we removed all App campaign placement data from the following reports:

Google Ads API

• Group Placement View
• Detail Placement View

AdWords API / Google Ads scripts

• Automatic Placements Performance Report
• Placement Performance Report

We made this change because the data provided didn’t fully represent the complete view of the placements that help developers monitor brand safety for their advertisers. If you use these reports, see the App Campaigns Brand Safety Placement report in the Google Ads UI.

If you have AdWords API or Google Ads API related questions about this change, please reach out to us on the API forum or at googleadsapi-support@google.com. Note: AdWords API developers must migrate to Google Ads API by April 27, 2022

If you have any Google Ads scripts related questions, please reach out to us on the scripts forum.
Ian Ballantyne, Google Ads API Team

With the updates listed below, we're improving the search term reports returned from both the Google Ads API and the AdWords API across all active versions.

Starting Sep 9, 2021, you'll be able to see more queries that meet our privacy standards in the search terms report for Search and Dynamic Search Ads campaigns. This new data will return for all searches on or after February 1st, 2021 when using the following reports and resources:

• Google Ads API - search_term_view Resource
• AdWords API - Keywordless Query Report
• AdWords API - Search Query Performance Report

This update can help you identify more relevant keyword themes, making it easier to optimize your ads, landing pages, and more. Metric totals from search terms reports will now be consistent with other reports, such as campaign, ad group, and ad reports in Google Ads.

As part of our ongoing commitment to privacy, we’re working to make our privacy thresholds consistent across Google. Over the next few months, you’ll see more changes across our other tools–including how we handle historical data. In Google Ads, this means that historical query data in your account that was collected prior to September 1st, 2020 will be available until February 1st, 2022. At that point, any historical queries that no longer meet our current privacy thresholds will be removed from your search terms report.

If you have any questions about this change or any other API feature, please contact us via the forum.

- Cory Liseno, Google Ads API Team

Beginning on August 4, 2021, all video-related performance reports will begin filtering out campaigns, ad groups, and ad group ads that are not part of video campaigns (advertising_channel_type = VIDEO). This change will cause performance metrics retrieved from the video resource to change across all supported Google Ads API versions.

If you would like to generate reports that combine metrics from video and non-video resources, you should use the respective resource-specific performance report, for instance: campaign, ad_group, or ad_group_ad.

If you have any questions or need additional help, contact us through the forum or at googleadsapi-support@google.com.
- Ben Karl, on behalf of the Google Ads API Team

On February 23rd, Google Ads API will be changing the way Hotel price buckets returns data by utilizing two new values in the hotel_price_bucket segment. Those new values will be added as enums in v6_1, “Lowest Unique” and “Only partner shown”.

Because there is overlap between the two new values and the existing “Lowest tied” value, after February 23rd developers using API versions earlier than v6_1 will see reports with the “Unknown” value wherever the two new values would be shown. This can result in one or two rows with the “Unknown” value.

Example:
Currently, data for ONLY_PARTER_SHOWN and LOWEST_UNIQUE are not returned, instead data is only shown for LOWEST_TIED.

LOWEST_TIED

12

Once the changes are released on February 23rd, developers on API versions v6_1 and greater will see the two new ONLY_PARTER_SHOWN and LOWEST_UNIQUE values, with the two new price buckets being displayed.

LOWEST_UNIQUE	3
ONLY_PARTER_SHOWN	4
LOWEST_TIED	5

After the changes are released on February 23rd, any developers on API versions lower than v6_1 will see “UNKNOWN” where the new values would have otherwise been shown.

UNKNOWN	3
UNKNOWN	4
LOWEST_TIED	5

If you have any questions about this change or any other API feature, please reach out to your account team directly, or contact us via the forum.
- Cory Liseno, Google Ads API Team

The Google Ads API Developer Relations team will be hosting a live webinar, Intro to Reporting & the Google Ads Query Language, on December 4 at 10 AM EST (3 PM GMT).

Mark your calendar

Agenda
The webinar will cover the topics below and include code walkthroughs to demonstrate how to perform different actions with the Google Ads API client libraries. We will also host a live Q&A at the end.

• Reporting in the Google Ads API vs. the AdWords API
• Types of search requests you can perform with the Google Ads API
• The syntax and structure of Google Ads Query Language queries
• How to discover available fields to construct Google Ads Query Language queries

Prerequisites
In order to get the most out of this webinar, we suggest you develop a basic understanding of the Google Ads API. To learn more, please visit our API Overview documentation or check out this Google Ads API Overview workshop from 2019. In addition, you may find this guide useful to learn about reporting with the Google Ads API, though much of this information will be covered in the webinar.

Reminders
Feel free to add the event to your calendar. In addition, you can set a reminder for the event on YouTube by clicking the “Set reminder” button on the YouTube event page.

We look forward to sharing our knowledge of the Google Ads API with you and answering your questions. If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
- Devin Chasanoff, on behalf of the Google Ads API Team

What’s changing?

We are changing how stats for Search campaigns with Display Expansion (previously known as Search campaigns with Display Select) are reported by the AdWords API, the Google Ads API, and Google Ads scripts.

Starting the week of Feb 17, 2020, we will no longer return display keyword stats for Search campaigns with Display Expansion in

• Display Keyword Performance Report in the AdWords API and Google Ads scripts
• Display_keyword_view in the Google Ads API.

Why is this changing?

Search campaigns with Display Expansion historically used keywords to perform Display Expansion. As we strive to improve targeting for Display Expansion, it is no longer possible to meaningfully and consistently attribute stats to keywords. As a result, this view has been removed from the Google Ads UI. The changes in this announcement aim to create parity between APIs and UI.


What should I do?

Before the sunset date, we recommend switching to alternate reports for fetching stats for Search campaigns with Display Expansion.

• Automatic Placement Performance reports and Display Topics Performance report can be used in the AdWords API and Google Ads scripts to get granular performance data about these campaigns in the Display Network. If you use the Google Ads API, you can use group_placement_view and topic_view instead.
• Reports such as Campaign Performance report or Ad Group Performance report can be used in the AdWords API and Google Ads scripts to fetch aggregate performance stats for these campaigns. You need to filter by AdNetworkType2 = CONTENT for Display Network stats. If you use the Google Ads API, you can use the campaign or ad_group view instead.

If you have any questions or need help, please contact us via the Google Ads scripts forum or the AdWords API and Google Ads API forum.

 - Anash P. Oommen, Google Ads API Team

Update (Nov 27, 2019 15:00 PST): An issue that impacted Google Ads reporting for conversions occurring between Nov 11 and Nov 20 (Pacific Time) for advertisers using non-last click attribution models has been fixed and the data is now correct in all reports, including the Search Query Performance, Geo Performance, Keywordless Query, and Keywordless Category reports.

An issue that impacted Google Ads reporting for conversions occurring between Nov 11 and Nov 20 (Pacific Time) for advertisers using non-last click attribution models has been fixed and the data is now correct.

If you downloaded any of the fields in the table below or any derivative custom columns using the AdWords API, Google Ads API or Google Ads scripts since November 20th 9:00 PM PST, you may have incorrect data in your systems. Please re-download the affected fields to ensure accurate conversions reporting.

We appreciate your patience as we worked to resolve this issue.

AdWords API

Google Ads API beta

Conversions ConversionValue ConversionRate ValuePerConversion CostPerConversion AllConversions AllConversionValue AllConversionRate ValuePerAllConversion CostPerAllConversion CurrentModelAttributedConversions CurrentModelAttributedConversionValue ValuePerCurrentModelAttributedConversion CostPerCurrentModelAttributedConversion

metrics.all_conversions metrics.all_conversions_from_click_to_call metrics.all_conversions_from_interactions_rate metrics.all_conversions_from_interactions_value_per_interaction metrics.all_conversions_value metrics.all_conversions_value_per_cost metrics.conversions metrics.conversions_from_interactions_rate metrics.conversions_from_interactions_value_per_interaction metrics.conversions_value metrics.conversions_value_per_cost metrics.cost_per_all_conversions metrics.cost_per_conversion metrics.cost_per_current_model_attributed_conversion metrics.cross_device_conversions metrics.current_model_attributed_conversions metrics.current_model_attributed_conversions_from_interactions_rate metrics.current_model_attributed_conversions_from_interactions_value_per_interaction metrics.current_model_attributed_conversions_value metrics.current_model_attributed_conversions_value_per_cost metrics.value_per_all_conversions metrics.value_per_conversion metrics.value_per_current_model_attributed_conversion

--Stan Grinberg, Google Ads API Team

Update (Jul 30, 2019): clarified the sunset schedule.

Starting 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.
David Wihl, Google Ads API Team

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.
- Cory Liseno, Google Ads API Team

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: Happy reporting!
- Cory Liseno, Google Ads API Team

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.
Nadine Sundquist, Google Ads API Team

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.
- Josh Radcliff, AdWords API Team

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.

- Josh Radcliff, AdWords API Team

Update (5/17): Starting October 30, 2018, parallel tracking will be required for all AdWords accounts. See the AdWords blog post for details.
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.
 - Anash P. Oommen, AdWords API Team

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.
 - Anash P. Oommen, AdWords API Team

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.
- Mike Cloonan, AdWords API Team

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.

- Mike Cloonan, AdWords API Team.

If you use AdWords API reports to retrieve performance statistics for AdWords Express campaigns, please read on as these changes will affect you.

What's changing?
In preparation for upcoming improvements, an ongoing migration process is modifying campaigns managed by AdWords Express.

Currently, when you enable an AdWords Express promotion, it creates up to two AdWords campaigns:

• A Search Network campaign with:
  • AdvertisingChannelType = SEARCH (appears as Search)
  • AdvertisingChannelSubType = SEARCH_EXPRESS (appears as Search Express)
• A Display Network campaign with:
  • AdvertisingChannelType = DISPLAY (appears as Display)
  • AdvertisingChannelSubType = DISPLAY_EXPRESS (appears as Display Express)

As part of the migration, the two campaigns above will be paused and replaced by a single AdWords campaign with:

• AdvertisingChannelType = EXPRESS (appears as Express)
• AdvertisingChannelSubType = UNKNOWN (appears as an empty string)

After the campaigns for a promotion are migrated, performance statistics for the AdWords Express promotion will be available in reports as follows:

• Performance statistics for dates prior to the migration will be attributed to the original campaigns with SEARCH / SEARCH_EXPRESS and DISPLAY / DISPLAY_EXPRESS.
• Performance statistics for dates after the migration will be attributed to the new campaign with EXPRESS / UNKNOWN. The new campaign will only appear in the CAMPAIGN_PERFORMANCE_REPORT.

For example, assume an AdWords Express promotion manages the following two AdWords campaigns today:

Campaign ID	Campaign Status	Advertising Channel Type	Advertising Channel Sub Type
1000	ENABLED	SEARCH	SEARCH_EXPRESS
2000	ENABLED	DISPLAY	DISPLAY_EXPRESS

After the migration, the account will contain the following campaigns for the AdWords Express promotion:

Campaign ID	Campaign Status	Advertising Channel Type	Advertising Channel Sub Type	Performance statistics
1000	PAUSED	SEARCH	SEARCH_EXPRESS	Before the migration
2000	PAUSED	DISPLAY	DISPLAY_EXPRESS	Before the migration
3000	ENABLED	EXPRESS	UNKNOWN	After the migration

What should you do?
Ensure that your application properly handles all three combinations of AdvertisingChannelType and AdvertisingChannelSubType. For example:

• If your application inspects AdvertisingChannelType or AdvertisingChannelSubType to handle AdWords Express campaigns, please adjust the logic to handle the new combination of EXPRESS / UNKNOWN.
• If you use predicates on AdvertisingChannelType or AdvertisingChannelSubType to include or exclude AdWords Express campaigns, make sure that your predicate takes the new combination into account.

Reminder: The AdWords API only supports retrieving AdWords Express entities. You cannot modify AdWords Express entities in your account using the AdWords API.

If you have any questions about this change, please contact us via the forum.
- Josh Radcliff, AdWords API Team