Google Ads Developer Blog: adwords

Subscribe to our RSS feed to get blog posts via email

Friday, February 8, 2019

(If you want to continue getting email updates about our blog posts, read on. If you don't want email updates from this blog, you can skip this post.)

For some products, the Google Ads Developer team has used Google groups as a way to allow API users to subscribe and get new relevant blog posts delivered to their email address. Starting now, the way you can get email updates about blog posts is changing. We will no longer send an email to the Google group for each new blog post. We will continue to use the Google groups for other important updates, however.

For users who still want email updates, we've introduced new FeedBurner links on the right-hand panel of our blog homepage. You can subscribe to the RSS feed by clicking on the link for the product you're interested in, or subscribe by email by clicking on the [+] link to the right of the product name.

If you use any of the APIs that we discuss on this blog, make sure you subscribe to the feed to keep up with the latest news and updates:

- Mike Cloonan, Ads Developer Relations Team

Support for v201809 reports in Google Ads Scripts

Monday, January 28, 2019

We have added support for AdWords API v201809 reports in Google Ads Scripts. The key changes in this release include:

The DESTINATION_URL_REPORT has been removed. Use the FINAL_URL_REPORT instead.
New conversion fields have been added to multiple reports:
- ConversionAttributionEventType (CAMPAIGN_PERFORMANCE_REPORT only)
- ConversionAdjustment
- ConversionAdjustmentLagBucket

Read the AdWords API release notes for complete details, including additional features not listed here.

If you use API versioning in your reports, you need to modify your code to use v201809:

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

If you don't use API versioning, no code changes are required. We are updating the default reporting version to v201806 along with this change, and your reports will upgrade automatically.

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

- Mike Cloonan, Google Ads Scripts Team

AdWords scripts is now Google Ads scripts

Tuesday, November 27, 2018

With the recent rebrand of AdWords to Google Ads, AdWords scripts has also been renamed to Google Ads scripts. As a result of this change, we have renamed AdWordsApp and MccApp within the scripts themselves to reflect the new naming. Your existing scripts are not affected and will continue to run as they always have.

Going forward, you should use AdsApp instead of AdWordsApp. Similarly, you should use AdsManagerApp instead of MccApp. We are updating all of our documentation, samples, and solutions to reflect these new names.

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

- Mike Cloonan, Google Ads scripts Team

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

Wednesday, November 7, 2018

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

Upcoming changes to HTML5 template ads in AdWords API & Scripts

Thursday, August 2, 2018

Starting August 27, 2018, creating TemplateAds with IDs 419 (HTML5 Ads) may result in an error in AdWords API and Scripts. AdWords API users will see the error AdError.Reason.USER_DOES_NOT_HAVE_ACCESS_TO_TEMPLATE when creating HTML5 ads using various services.AdWords Scripts users may see an error that the ad cannot be saved when using the HTML5AdBuilder class to create a new HTML5 ad.

Existing accounts that have used or are currently using HTML5 ads will be whitelisted, and will continue to be able to upload HTML5 ads. Existing HTML5 ads will also continue to serve after this date.

If your account is new, or has never used HTML5 ads before, you may be affected by this change. We recommend one of the following options to fix this error:

You may apply for HTML5 access in your account by filling in the whitelist request form
You can use an AMPHTML instead of a regular HTML file in your HTML5 bundle. AMPHTML ads won’t trigger the above error.
You will automatically be approved for HTML5 access once you have spent more than $9000 USD on AdWords and your account is more than 90 days old

If you have questions about this change, please reach out to us on the AdWords API forum or AdWords Scripts forum.
- Anash Oommen, AdWords API Team

Changes to YouTube placements in AdWords scripts

Thursday, July 26, 2018

We are rolling out a change to the way placements work when specifying YouTube URLs. Starting on August 14, 2018, using generic placements to specify YouTube channels or videos is going to be disallowed and will result in an error.

For more accurate video targeting, even when videos are played across platforms, use the new specific YouTubeChannel and YouTubeVideo placement criteria when you want to target specific channels or videos in AdWords scripts.

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

- Mike Cloonan, AdWords Scripts Team

Campaign drafts and experiments now available in AdWords scripts

Thursday, July 26, 2018

Today we’re announcing the release of campaign drafts and experiments in AdWords scripts. Drafts and experiments (also known as Trials) will allow you to prepare, test, and apply improvements to your Search and Display Network campaigns using AdWords scripts.

An experiment runs simultaneously with the original campaign, showing its ads to the percentage of traffic that you have configured. Using the experiment to understand the impact of your changes, you can apply the changes directly to the original campaign, or even establish the experiment as an independent, fully operating campaign while retaining the original.

For more information, please refer to our guide to drafts and experiments in AdWords scripts and code samples.

If you have any questions about these changes or AdWords scripts in general, you can post them on our developer forum.
- Niousha Jafari and Rohan Dhoopar on behalf of AdWords Scripts team

New features in AdWords scripts

Wednesday, July 18, 2018

Today we're announcing the launch of a few new features in AdWords scripts:

Support for reporting version v201806
Multi-file script support
Support for final URL suffix for parallel tracking

Reporting
Support for v201806 of reports has been added. The main features in this reporting version are:

Read the AdWords API release notes for complete details, including additional features not listed here.

If you use API versioning in your reports, you need to modify your code to use v201806:

var report = AdWordsApp.report(query, {
  apiVersion: 'v201806'
});

We will also be updating the default reporting version from v201710 to v201802 on July 23, 2018. This will affect you if you do not use API versioning as outlined above.

Multi-File Support
Over the next few weeks, we will be rolling out support for scripts with multiple files. This lets you separate your utility logic from your business logic, organize your code however you see fit, and generally produce more maintainable scripts. Please try it out and let us know what you think on the forum!

Parallel Tracking Support
We have added methods to support the final URL suffix for parallel tracking. You can use the new getFinalUrlSuffix, setFinalUrlSuffix, and clearFinalUrlSuffix methods on objects that have final URLs.

As announced earlier this year, starting October 30, 2018, parallel tracking will be required for all AdWords accounts. You can consult the AdWords API documentation on click tracking for more details on how to migrate, as the same concepts apply to scripts. Please make sure to update your scripts before the deadline.

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

- Mike Cloonan, AdWords Scripts Team

Click measurement changes in AdWords

Monday, May 7, 2018

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

Support for v201802 reports in AdWords scripts

Wednesday, March 28, 2018

We have added support for AdWords API v201802 reports in AdWords scripts. The key changes in this release include:

A new report type, LANDING_PAGE_REPORT, to provide performance stats for the pages that receive traffic from your ads.
ConversionLagBucket field added to various reports to help you determine how long it takes customers to convert.
New fields added to support Gmail ads.

Read the AdWords API release notes for complete details, including additional features not listed here.

If you use API versioning in your reports, you need to modify your code to use v201802:

var report = AdWordsApp.report(query, {
  apiVersion: 'v201802'
});

If you don't use API versioning, no code changes are required. We are updating the default reporting version to v201710 along with this change, and your reports will upgrade automatically.

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

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

Tuesday, February 20, 2018

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

AdWords Scripts now integrated with Google Slides API

Friday, July 28, 2017

Today we’re excited to announce that the Google Slides API has been added as an Advanced API to AdWords scripts. Our Advanced APIs allow you to work with other Google services within the scripts you write. The Google Slides API allows you to create and write presentations programmatically, and with AdWords scripts it can be used to publish your campaign data in a ready-to-be-shown format.

To learn more about using the Google Slides API in your scripts, please refer to our guide to working with Advanced APIs and code snippets. We encourage you to try Slides and our other Advanced APIs and let us know of other APIs you would like to see added.

As always, please leave feedback on our forum so that we may handle bugs and improve usability.

- Rohan Dhoopar, AdWords Scripts Team

Register now for the AdWords scripts workshops!

Monday, July 10, 2017

We’re pleased to announce a new set of workshops for AdWords scripts in 2017. The workshops will be held at the following locations:

Hamburg, Germany: 10 August 2017
London, UK: 15 August 2017
Singapore: 15 August 2017
Sydney, Australia: 18 August 2017
São Paulo, Brazil: 20 September 2017
Buenos Aires, Argentina: 22 September 2017

This round of workshops will cater to both novice and experienced scripters. We'll have code labs where you’ll build your own scripts from scratch with help from the scripts team. Bring your laptop and some scripting ideas, and we’ll turn them into reality!

Whether you’re an advertiser who wants to learn how to use scripts to automate your account management tasks, a developer who wants to polish your skills, or you'd just like to bounce around some ideas, you can find it all in these workshops.

Availability is limited, so be sure to visit our website early to check out the full agenda and sign up.

If you have any questions about the workshops, you can post them on our forum.

- Mike Cloonan, AdWords API Team

Support for new extension types in AdWords scripts

Wednesday, May 3, 2017

We're excited to announce support for additional extension types in AdWords scripts starting today. The newly supported extension types are:

Message extensions, supported at the campaign and ad group level. These allow mobile users to send a text to your business directly from the ad.
Structured snippet extensions, supported at the campaign and ad group level. These allow you to highlight specific aspects of your products.

In addition, we're adding support for account level sitelink extensions, which were already supported at the campaign and ad group levels.

You can see all the technical details for how to implement these over on our AdWordsApp.Extensions documentation, or you can check out some example code using these extension types on our examples page.

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

Support for BudgetOrders and UserLists in AdWords Scripts

Wednesday, April 19, 2017

We are excited to announce support for two new features in AdWords Scripts: BudgetOrders and UserLists. BudgetOrders: We are introducing read-only support for BudgetOrders. You can now access your BudgetOrders to retrieve information like account-level spending limit and credits from Google (note that your account must be on consolidated billing to use these features). UserLists: You now have the opportunity to read and write some of the fields associated with the UserLists in your shared library. You can retrieve member counts, update membership lifespan, and open or close your user lists to new members. When you're ready to try it out or learn more, check out the BudgetOrder and UserList sections of the left navigation bar under our AdWordsApp documentation. If you have any questions about this new feature or AdWords scripts in general, you can post them on our developer forum.

Allison Greene, AdWords API Team

Support for v201702 reports in AdWords scripts

Tuesday, March 28, 2017

We have added support for AdWords API v201702 reports in AdWords scripts. The major changes in this release are:

New conversion fields to help when changing attribution models: CostPerCurrentModelAttributedConversion, CurrentModelAttributedConversions, CurrentModelAttributedConversionValue, and ValuePerCurrentModelAttributedConversion
Fields of type Double that don't represent percentages now return without a thousands separator and with two decimal places.
The AdGroupName and AdGroupStatus fields of the Audience Performance Report now behave as segments
All fields in the Call Metrics Call Details Report now behave as attributes

See the AdWords API release notes for more details.

v201609 will remain the default version for reports until the week of April 24, 2017. This gives you enough time to verify your scripts and make sure they work with the latest report version.

If you use API versioning in your reports, you need to modify your code to use v201702:

var report = AdWordsApp.report(query {
  apiVersion: 'v201702'
});

If you don't use API versioning, no code changes are required. Your reports will continue using v201609 for now, and switch to v201702 when we make v201702 the default version the week of April 24, 2017.

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

Announcing support for video campaigns in AdWords scripts

Tuesday, December 13, 2016

Today we're announcing the release of video campaign management support in AdWords scripts. You can now create and manage in-stream, video discovery, and bumper ads in your existing video campaigns, set targeting for your video campaigns and ad groups, and report on performance including views and view rate.

To get started, visit our Video Campaigns guide for an overview of the new functionality. You can also view a variety of samples both in the docs and by using the Show examples button in the script editor. These are pre-built functions that may be useful to drop into your code or use as the basis for expansion into your own custom script.

When you're ready to dig in or when you're ready to learn more, check out the "Video" section of the left navigation bar under our AdWordsApp documentation.

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

- Mike Cloonan, AdWords Scripts Team

Save time creating expanded text ads with the ETA Transition Helper

Monday, November 21, 2016

Since we introduced expanded text ads (ETA) earlier this year, we’ve recommended that advertisers create and test multiple ETAs to determine what messages perform best for their business. To help you do this at scale, we’ve created the ETA Transition Helper, a powerful tool that allows you to easily create ETAs in bulk using AdWords Scripts and Google Sheets.

This tool helps you save time by using your existing standard text ads (STAs) as a blueprint for your new ETAs. The ETA Transition Helper ensures your expanded text ads are formatted according to the new character limits and that their display URLs use the final URL's domain. After creating the new ETA, the tool displays your current STA and the new ETA side-by-side in a Google Sheet so you can easily compare the two ads. Please note that the tool's interface is only offered in English at this time, but it supports exporting STAs and creating ETAs in all languages.

As a reminder, starting January 31st, 2017, you will no longer be able to create or edit STAs, though existing STAs will continue to serve alongside ETAs.

Get started by checking out the user guide. You can also contribute to the ETA Transition Helper project on GitHub today. If you have any questions or would like to provide feedback, feel free to contact us on the AdWords Scripts Forum.

Herlen Zoljargal, AdWords API Team

Support for v201609 reports in AdWords Scripts

Wednesday, November 2, 2016

We have added support for AdWords API v201609 reports in AdWords Scripts. The major changes in this release are:

The ClickType column is no longer compatible with fields for other types of interactions, such as AverageCpe, AverageCpv, VideoViewRate, and more. See a complete list in the v201609 migration guide.
The ExternalConversionSource field was added to several reports to allow segmentation of conversions by source.
The AUDIENCE_PERFORMANCE_REPORT no longer returns rows for excluded criteria.
All fields related to AdWords Campaign Experiments have been removed, as the feature is being sunset.

See the AdWords API release notes for more details.

The v201607 will remain the default version for reports until the week of November 28, 2016. This gives you enough time to verify your scripts and make sure they work with the latest report version.

If you use API versioning in your reports, you need to modify your code to use v201609:

var report = AdWordsApp.report(query {
  apiVersion: 'v201609'
});

If you don't use API versioning, no code changes are required. Your reports will continue using v201607 for now, and switch to v201609 when we make v201609 the default version the week of November 28, 2016.

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

Changes to ClickType field compatibility in AdWords API & Scripts Reports

Thursday, October 20, 2016

We are marking the ClickType column in AdWords API and Scripts reports as incompatible with the following engagement and video-related fields in version v201607 and earlier:

AverageCpe
EngagementRate
VideoQuartile25Rate
VideoQuartile50Rate
VideoQuartile75Rate
VideoQuartile100Rate
VideoViews
VideoViewRate
AverageCpv

These fields refer to engagement and video view interactions, and aren’t compatible with the ClickType column, a click interaction metric. This restriction is already enforced in v201609 reports, see our migration guide for more details.

Starting Dec 1, 2016, you will get a ReportDefinitionError.INVALID_FIELD_NAME_FOR_REPORT error if ClickType column is requested with any of these fields.

Questions? Visit us on the AdWords API Forum or our Google+ page.

- Anash P. Oommen, AdWords API Team

Ads Developer Blog

Subscribe to our RSS feed to get blog posts via email

Support for v201809 reports in Google Ads Scripts

AdWords scripts is now Google Ads scripts

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

Upcoming changes to HTML5 template ads in AdWords API & Scripts

Changes to YouTube placements in AdWords scripts

Campaign drafts and experiments now available in AdWords scripts

New features in AdWords scripts

Click measurement changes in AdWords

Support for v201802 reports in AdWords scripts

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

AdWords Scripts now integrated with Google Slides API

Register now for the AdWords scripts workshops!

Support for new extension types in AdWords scripts

Support for BudgetOrders and UserLists in AdWords Scripts

Support for v201702 reports in AdWords scripts

Announcing support for video campaigns in AdWords scripts

Save time creating expanded text ads with the ETA Transition Helper

Support for v201609 reports in AdWords Scripts

Changes to ClickType field compatibility in AdWords API & Scripts Reports

Labels

Archive

Feeds

Google Ads API [+]

AdWords API [+]

Google Ads scripts [+]

Content API for Shopping [+]

Google Ad Manager API [+]

DCM API [+]

Mobile Ads [+]

IMA SDK [+]

More Google blogs