We have just launched a new backend for bulk uploads in Google Ads Scripts. Starting today, you can opt into the new experience by specifying the useLegacyUploads flag when creating a new bulk upload:

var upload = AdsApp.bulkUploads().newCsvUpload(columns,
    {useLegacyUploads: false});

For now, if you don't specify a value, the default will be true, which will result in no change of behavior from before this feature. Starting on July 12, 2021 we will change the default to false, but you can still opt out for a time by explicitly passing useLegacyUploads as true. On February 1, 2022, we will disable the use of legacy uploads altogether.

We have tried to make the changes here as backwards-compatible as possible, so in most cases your existing uploads should continue to work fine even on the new backend. However, creating video ads which specify a media ID will cease working on the legacy uploads on or after July 12, when we change the default, so if those are important fields to you, make sure you do not manually override to use legacy uploads.

The new backend is exactly compatible with UI-based bulk uploads, which is an improvement over the existing bulk upload system where many columns have different names. This should make it significantly easier to set up bulk uploads by basing the format from the UI. Additionally, a few new features are available, including label manipulation and updating manager accounts.

If you have any questions, please leave a post on our forum so that we can help.
- Mike Cloonan, Google Ads Scripts Team

On February 4, 2021, we announced changes to phrase match and broad match modifier (BMM). As advised in that post, as of today all Google Ads languages have now been updated to use the new phrase match definition. Also as of today, all legacy BMM keywords will continue to serve but will now behave as phrase match keywords. Creation of new BMMs using the legacy BMM notation (+keyword) and modifications to existing BMM keyword text will no longer be permitted as of August 2, 2021 (AdWords API, Google Ads API, Google Ads scripts).

Updates of other targeting criteria fields (such as status, bid, url, labels) will still be permitted.

Partners are encouraged to follow the guidance in this article. As detailed in the article, if you choose to convert BMM keywords to phrase match, performance statistics will not carry over to the new instances. Smart bidding users are encouraged to use the broad match type.

Note: The changes to phrase match and BMM will not impact exact match, broad match, or negative keyword match types. Learn more about keyword matching options.

If you have any questions or need additional help, contact us via the forum.
David Wihl, Google Ads API Team

As previously announced, all ad extensions are migrating to the new Asset-based extension paradigm. You must update extensions support in your implementation and migrate existing Feed-based extensions to Asset-based extensions. See the migration schedule for important sunset dates.

What has changedThe following Asset-based extension types are now available to all accounts:

• Callout
• Promotion
• Sitelink
• Structured Snippet

Though originally scheduled for release later this year, Asset-based Image extensions will not be available in the Google Ads API until 2022. When available, we will publish an updated sunset timeline for Feed-based Image extensions to this blog and in our extension migration documentation.

Lastly, the new {extensionid} ValueTrack parameter will be available beginning June 24, 2021. You can use this parameter to track clicks on your Asset-based extensions. The {extensionid} parameter for Asset-based extensions mirrors the behavior of the existing {feeditemid} parameter for Feed-based extensions.

What you need to doMigrate Callout, Promotion, Sitelink, and Structured Snippet extensions in your accounts to Asset-based extensions using the Google Ads API. We encourage you to do so as soon as possible so as to continue to be able to modify your extensions; Callout, Promotion, Sitelink, and Structured Snippet Feed-based extensions will automatically migrate to Asset-based extensions on October 20, 2021. You will soon be able to opt individual Google Ads client accounts out of this auto migration; the opt out process will be announced on this blog when available. Please see our extension migration guide for the most up-to-date and relevant information. Note that Asset-based extensions are not supported in the AdWords API.

You can now use the {extensionid} ValueTrack parameter to track clicks on any Asset-based extensions that you have created. The {feeditemid} parameter does not apply to any clicks on Asset-based extensions, and {extensionid} does not apply to clicks on Feed-based extensions. To continue attributing clicks correctly, you should update any URLs that currently use the {feeditemid} ValueTrack parameter to also include the new {extensionid} ValueTrack parameter. You should therefore set both {feeditemid} and {extensionid} in the same URL, though only one will be populated depending on the source of the click.


If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.

- Andrew Burke, Google Ads API Team

Today we’re announcing the deprecation of Entity Read Files (ERFs). Users currently retrieving Display & Video 360 resource information from ERFs should begin migrating to using the Display & Video 360 (DV360) API or Structured Data Files (SDFs).

With this deprecation, we will no longer support ERFs through documentation updates or bug fixes. ERFs will continue to be generated and available for download for the immediate future. However, users should be prepared for ERFs to sunset at a later date. We will announce a sunset date in a future blog post and publish a notice on the ERF documentation page far in advance of the sunset.

Refer to our ERF to API Migration guide for more detailed information about the differences between ERFs and the DV360 API and how ERF information maps to the API resources and services.

If you run into issues, need help with your migration, or have any questions, please contact us using our support contact form.

- Trevor Mulchay, Display & Video 360 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

Starting on July 8, 2021, all standalone Gmail campaigns will become read-only. This means that you will not be able to create new campaigns or create ad groups in existing campaigns of this type after that date. This applies not only to the Google Ads and AdWords APIs, but also to any other interface you use to manage your Google Ads accounts.

Specifically, the types of campaigns that would be affected are those with an AdvertisingChannelSubType of DISPLAY_GMAIL_AD, where the following operations will fail with an OPERATION_NOT_PERMITTED_FOR_CONTEXT error and a trigger of DISPLAY_GMAIL_AD:

• Creating a new Gmail campaign.
• Creating a new Gmail ad group.
• Creating or updating Gmail ads.

Existing campaigns’ data will still be available.

There is no general workaround for API users to continue to be able to target Gmail specifically. If you would like to continue to target Gmail, you can use Discovery campaigns, which include Gmail ads, in the Google Ads web interface.

If you have any questions, please leave a post on our forum so that we can help.
- Mike Cloonan, Google Ads API Team

Update (Jun 21): Extended the deprecation date to Sep 13, 2021.

Starting September 13, 2021, we will be deprecating Url Performance Report and Automatic Placements Performance Report in the AdWords API. The two reports will return empty results in the AdWords API after the deprecation.

To continue accessing these two reports, please migrate to Google Ads API and use the following views:

• For Url Performance Report, use detail_placement_view in Google Ads API
• For Automatic Placements Performance Report, use group_placement_view in Google Ads API

For migrating reports to Google Ads API, refer to the report migration guide.

If you have any questions or need additional help, contact us via the forum.
Fei Xiang, Google Ads API Team

In the Google Ads API v8, Call Only Ads are replaced by Call Ads. You can still create Call Only Ads in the AdWords API v201809 and the Google Ads API v6 and v7, but we encourage you to use v8 to create new Call Ads.

Call Only Ads will continue to serve until the AdWords API Sunset on 27 April 2022.

Prior to v8, Call Only Ads only offered users the ability to call. Users and advertisers have said they want the ability to go directly to the website from these ads. The addition of the final URL in Call Ads enables advertisers to use calls as the primary (i.e. headline) action, while still providing users with a means to visit an advertiser’s website prior to or instead of calling.

What you need to do

• Use the ad type CallAd instead of CallOnlyAd to create new Call Ads.
• Filter on ad.type = 'CALL_AD' to retrieve information for existing ads regardless of what ad.type was used to create the ad. For example, using the Google Ads API to query

      SELECT ad_group_ad.ad.call_ad.country_code,
             ad_group_ad.ad.call_ad.phone_number
      FROM ad_group_ad
      WHERE ad_group_ad.ad.type = 'CALL_AD'

  will return ads created as CALL_ONLY_AD and CALL_AD.

What has changed
Fields added

ad_group_ad.ad.final_urls	This is where you specify the URL of your website.
path1	First part of text that may appear appended to the url displayed in the ad.
path2	Second part of text that may appear appended to the url displayed in the ad. This field can only be set when path1 is set.

Field removed

ad.display_url

We removed the display_url for Call Only Ads. The URL that will be displayed alongside your ad will now be based on ad_group.ad.final_urls if provided, or phone_number_verification_url if ad_group.ad.final_urls is blank, as well any additional text you specify in path1 and path2.

Field verification

phone_number_verification_url

This field is now required if ad_group.ad.final_urls is empty.

AdWords API Reporting: There is no change in the AdWords API.

Google Ads API Reporting: In the Google Ads API you can include these new fields in your queries

• ad.final_urls
• ad.path1
• ad.path2

Where to get help
If you have questions about Call Ads, please reach out to us on the forum or at googleadsapi-support@google.com.

Bob Hancock, Google Ads API Team

Today, we’re announcing the v8 release of the Google Ads API. To use v8 features, you will need to upgrade your client libraries and client code. The updated client libraries and code examples will be published next week. For more information on breaking changes, see the migration guide.
Here are the highlights:

• We’ve added cross-account bidding strategies, which allow for attaching manager-owned bidding strategies to client accounts. Also included is a new resource, AccessibleBiddingStrategy, which provides a read-only view of all bidding strategies accessible to the current customer (including portfolio strategies owned by the customer and cross-account bidding strategies shared with the customer).
• You can now retrieve labels managed by the manager account using CustomerClient.applied_labels.
• CallOnlyAdInfo is replaced with CallAdInfo to support more capabilities of this ad type. This includes the ability to append text after the URL displayed in the Ad using fields CallAdInfo.path1 and CallAdInfo.path2.
• ClickConversion now supports cart_data for uploading conversions with the additional information on the items sold.
• Several fields added to TransactionAttribute and UserAttribute allow you to associate more information about a sold item and a user’s purchase record, when uploading user data using UserDataService or OfflineUserDataJobService.
• We’ve added support for Smart campaigns, which allows for creating, monitoring and managing smart campaign types. Smart campaigns are highly automated, efficient campaigns designed to maximize returns with minimal ongoing management. For more details, visit our development guide.

Where can I learn more?
The following resources can help you get started:

• Release Notes
• Migration Guide
• Guides
• Reference

If you have any questions or need additional help, contact us via the forum.
Thanet Knack Praneenararat, on behalf of the Google Ads API Team

The Google Ads API Developer Relations team will be hosting a live webinar on Migrating to the Google Ads API, on June 16 at 10 AM EST (2 PM GMT).

Mark your calendar

AgendaThis webinar helps AdWords API developers jumpstart their migrations to the new and improved Google Ads API. The webinar builds upon our Migration Guide, so we recommend reading that guide before watching this webinar. We will also host a Q&A at the end with members of the Google Ads Developer Relations and Engineering teams. The webinar will cover the following topics:

• High level differences between the AdWords and Google Ads APIs
• Migrating Reporting
• Migrating Mutates
• New & Improved Features
• Migration Best Practices

RemindersFeel 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.

- Sasha Friedenberg, Google Ads API Team

On July 21, 2021, all existing recommendations of the type KEYWORD_MATCH_TYPE will be removed and no new recommendations of this type will be generated anymore.

What's changing?
The KEYWORD_MATCH_TYPE recommendations will no longer be returned by search for all versions of the Google Ads API and Google Ads scripts.

All requests sent to apply or dismiss KEYWORD_MATCH_TYPE recommendations will fail with RequestError.RESOURCE_NOT_FOUND errors for all versions of the Google Ads API.

What do you need to do?
Before July 21, 2021, ensure that the changes described above will not lead to any issues in your code or application.

Then, as soon as you can, remove any references of the field Recommendation.keyword_match_type_recommendation and the type KeywordMatchTypeRecommendation in your code. They will be deprecated and removed in future versions.

If you have any questions or need additional help, contact us through the forum or at googleadsapi-support@google.com.
Pierrick Voulet, Google Ads API Team

Following feedback from our merchants, we are relaxing our contact policy website requirements for merchants. Currently we require merchants to publicly display on their website at least two methods of contact information (such as an email, business address, or phone number).

To give merchants more flexibility in the information they share with customers, beginning August 2, 2021, we will require merchants to provide on their website a minimum of one form of customer-facing contact information, for example:

• A “contact us” form
• A link to a social media business profile
• An email address
• A phone number

In addition to this change, all new merchants will be required to provide their business address and phone number on creation of their Merchant Center account, as well as for any existing accounts that require a review. This private contact information can be entered manually in the Merchant Center user interface or via Content API for Shopping.

To update the private contact information using Content API for Shopping, provide both the address and phoneNumber fields via the AccountBusinessInformation object (nested under the Account object) using the following methods:

• Accounts.update (Existing Merchant Center accounts)
• Accounts.insert (New Merchant Center accounts)

Important: Take care when updating existing accounts. Any fields that are not provided to Accounts.update will be deleted from the resource.

Note: If you have made contact information changes to an existing Merchant Center account that has an account-level disapproval, you may need to request an account re-review. See the following article on Understanding account-level enforcement for product data quality violations to find the steps to make the request.
If you require further support implementing this change, please visit the Content API for Shopping forum.
Ian Ballantyne, Content API for Shopping Team

Today, we are releasing a Google Ads Query Language (GAQL) Query Validator, so you can validate GAQL queries directly in the browser via the developer documentation site. This new tool is integrated with the Interactive GAQL Query Builder to make for a streamlined workflow.
In order to use the new query validator, either visit the query validator page directly or click the Enter or edit a query button on any resource’s query builder page.



Upon successfully validating a query with the query validator, continue editing the query using the Interactive Query Builder by clicking the Continue Editing in Query Builder button.





The Query Validator will also provide feedback related to errors in invalid queries.




In addition, you can continue manually editing and validating queries built with the query builder in the query validator by clicking the Enter or Edit a Query button after constructing a query with the query builder.





As you get started with the new query validator, please feel free to share feedback by clicking the Send feedback button on the top right of the page.

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

In the coming weeks, we'll be changing how we update the default reporting version for search and report requests that use the Google Ads Query Language in Google Ads scripts. This will allow you access to new reporting features as they are released, rather than our previous cadence of holding off on new versions for up to a few months. If you are still using AdWords API based reporting in v201809, these changes will not affect you.

We will be updating the default reporting version for Google Ads API-backed reports to use the newest version of the Google Ads API within two weeks of that version's release. So for example, whenever v8 releases, we will be updating the default reporting version for report calls using GAQL, and all search calls, to use v8 within two weeks of that time.

If you think that this may negatively affect your scripts, and you want to pin to a specific version, you can still manually specify a version which will override the default and will not update until you are ready to move on to the next version. If you do this, be on the lookout for when Google Ads API sunsets versions, because that will cause your scripts to fail until you update to a newer version. Here are examples of setting an API version.

For reports:

var report = AdsApp.report(query, {apiVersion: 'v7'});

For search:

var results = AdsApp.search(query, {apiVersion: 'v7'});

As part of this rollout, we will be updating the default (which is currently v5) to v7 shortly after this post. You can find a full list of reporting upgrades made in v6 and v7 on the Google Ads API release notes page.

If you have any questions, please leave a post on our forum so that we can help.
- Mike Cloonan, Google Ads Scripts Team