Tag Archives: adwords_api_v201509

AdWords API v201509 sunset reminder

AdWords API v201509 will be sunset on June 21, 2016, after which all v201509 API requests will begin to fail. This version was deprecated on February 2, 2016. If you are still on v201509, we recommend that you skip v201601 and migrate directly to v201603. Please be sure to migrate prior to sunset to ensure your API access is unaffected.

We've prepared various resources to help you with the migration: As always, if you have any questions about this migration, please contact us via the forum or the Ads Developers Plus Page.

Reach your most valuable customers with Customer Match

Did you know that you can reach past website visitors and app users? Let's say you’re a travel brand. You can now reach people who have joined your rewards program as they plan their next trip. For example, when these rewards members search for “non-stop flights to new york” on Google.com, you can show relevant ads at the top of their search results on any device right when they’re looking to fly to New York. And when those members are watching their favorite videos on YouTube or catching up on Gmail, you can show ads that inspire them to plan their next trip.

Behind the scenes, this works by adding people to a UserList.

Prior to v201509 there were four different types:

  • BasicUserList: Remarketing to people who took specific actions (such as purchasing shoes) on your website or app.
  • RuleBasedUserList: Remarketing to people who follow advertiser-defined rules. The rule can be as simple as all visitors to your website (which is the easiest way to start remarketing).
  • LogicalUserList: Combining two or more user lists. For example, customers who purchased shoes and/or visited specific pages of your website at specific times.
  • SimilarUserList: Remarketing to people that share similar interests and behaviors with those in other user lists. For example, you can reach new potential customers that share similar interests and behaviors with those who purchased shoes on your website.

A SimilarUserList is automatically created by Google for each UserList based on a variety of factors, such as the number of people on the original list, how recently these people joined the original list, the types of sites that these people browsed and whether the original list is your own. This process may take up to 4 days once the seed list is created.

You can target or exclude user lists at the ad group level, but you can only exclude them at the campaign level.

As a reminder, please have a look at the policy for advertising based on interests and location and the policy for remarketing lists for search ads.

Customer Match

v201509 introduced a new user list type: CrmBasedUserList. It enables you to create a user list using your customers’ email addresses.

Suppose you have an existing database of email addresses of your newsletter subscribers for “people who love shoes”. With a CrmBasedUserList you can reach these subscribers and adjust your bidding accordingly, present different ads, and more. You can use a SimilarUserList of your subscribers list to potentially find new customers who share similar behaviors and interests.

Each CrmBasedUserList must have an optOutLink to provide a link to the page where people can manage their preferences for receiving email messages from the advertiser, including opting out of the advertiser email messages.

Before using this targeting strategy, please take the time to read our policy page.

A CrmBasedUserList can be used for targeting on the Search network, YouTube and Gmail, whereas a SimilarUserList of a CrmBasedUserList can only be used for targeting on YouTube and Gmail.

Keep the following points in mind when using a CrmBasedUserList:

  • Advertisers must collect email addresses as 1st party. For example, an agency can submit email addresses on behalf of an advertiser if the advertiser collected the email addresses directly from its customers.
  • Email addresses can be from Gmail or non Gmail addresses as long as they are associated with a Google account. We recommend adding all available email addresses to maximize the size of the result.
  • Ads will serve only when the user list has at least 1,000 active members. Active members are those who have used Google Search, YouTube, or Gmail at least once over the last 30 days.

If you want to read more about CrmBasedUserList, have a look at our guide and code examples.

As always, feel free to visit us or ask questions on the AdWords API Forum or our Google+ page.

Reporting changes in AdWords API v201509

AdWords API v201509 introduces some changes to reporting columns, particularly Clicks. Recently, AdWords introduced new columns called Engagements and Interactions. It also added reporting columns related to video campaigns such as VideoViews, which have previously been unavailable via API reporting. AdWords API version v201509 has updated its reporting to match these changes.

The new Interactions field, available in API performance reports, can be thought of as the main action a user takes with the ad format: clicks for text ads, engagements for Lightbox ads, and views for video ads. Previously, views for video ads were not returned in API reporting, so having access to this data is new.

Prior to v201509, the Clicks field always included both clicks and engagements. Starting in v201509, the Clicks field includes only click actions, like clickthroughs to a landing page or clicks to call. This means that clicks on video ads, which are unpaid, will be included in this field. However, engagements for Lightbox ads will not be counted.

If measuring performance across multiple ad formats, you might consider using Interactions to view the total number of primary user actions on ads, all in the same column. Clicks, Engagements, and VideoViews are available as well for more fine-grained reporting by ad format.

The table below summarizes the changes in each field for various ad formats.

Field
v201506
v201509
Clicks
Text ads: clickthrough to a landing page

Lightbox ads: hover to expanded ad format
Text ads: clickthrough to a landing page or clicks to call

Lightbox ads: clickthrough to a landing page

Video ads: clickthrough to a landing page
Engagements
N/A
Lightbox ads: hover to expanded ad format
VideoViews
N/A
Video ads: view
Interactions
N/A
Text ads: clickthrough to a landing page or clicks to call

Lightbox ads: hover to expanded ad format

Video ads: views

Please note that reporting in v201506 and previous versions is unaffected; they return the same data that they always have, represented the same way. This means that when comparing the data you receive from older versions of the API to user interface reports, or to v201509 reports, the numbers will not directly match up. Video-related stats will still be excluded from v201506. The Clicks column in v201506 will match the Interactions column from v201509 if you subtract out video interactions.

For ease of reporting, it’s recommended to migrate to v201509 as soon as possible.

Keep in mind these aren’t the only reporting changes in v201509 — for more details on conversion-related reporting changes, please see the release notes.

If you have any questions about this or other aspects of the AdWords API, please contact us via the forum or the Ads Developers Plus Page.

Announcing v201509 of the AdWords API

Today we’re announcing the release of AdWords API v201509. Here are the highlights:

  • Improved batch processing. The new BatchJobService supports all of the same operations as MutateJobService, but offers additional features such as support for creating dependent objects using temporary IDs, better error reporting, improved performance, and a much higher limit on the number of operations per job. Check out the accompanying guide to get started.
  • AdWords for video and TrueView video campaigns in reports. The AdWords API now supports TrueView campaigns that have migrated from AdWords for video, and several reports now include statistics and new metrics for these campaigns. See the release notes for the complete list of changes and additions.
  • New reporting columns for multi-channel advertisers are available on multiple reports making it easier to track interactions vs. clicks.
  • Customer Match. Build and target user lists from email addresses using the new CrmBasedUserList.
  • Structured snippets can now be created using extension setting services.
  • Conversion column changes. Conversion columns have been modified, added, or removed on multiple reports to coincide with the upcoming conversion reporting changes in AdWords. See the release notes for the complete list of changes.
  • HTML5 ads can now be added as TemplateAds using template ID 419. In addition, MediaService now supports uploading media bundles for use with this new template.
  • Geo targeted ad customizers. Target each ad customizer feed item to a specific geographic location.
  • Gmail sponsored promotions. The AdWords API now fully supports the Gmail image, single promotion, and multi-product ad formats via template ads.
  • Dynamic remarketing ads have new placeholder fields for setting upgraded URL attributes such as tracking templates, custom parameters, and final URLs.
  • Active View reporting. New fields for Active View viewable impressions, measurable impressions, measurable cost, and measurability are now available in multiple reports.

If you’re using v201502 of the AdWords API, please note that it’s being sunset on November 12th, 2015. We encourage you to skip v201506 and migrate straight to v201509. If you’re using v201506, be aware it’s now marked deprecated and will be sunset on April 11th, 2016.

As with every new version of the AdWords API, we encourage you to carefully review all changes in the release notes and the v201509 migration guide. The updated client libraries and code examples will be published shortly. With this release, we’ve also updated the Required Minimum Functionality document to include some of the newly added features. If you have any questions or need help with migration, please post on the forum or the Ads Developers Plus Page.