Posted:

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.

Posted:
We’ve completed the last round of the AdWords API Workshops, and you can check out all the content online by visiting the official website, www.adwordsapiworkshops.com, and clicking on Resources.

Be sure to also check out our YouTube channel for the recorded presentations.

If you have any questions about the AdWords API Workshops, you can post them on our forums. Check out our Google+ page for Ads APIs updates.

Posted:
What’s new?

The validation for AppConversions will become stricter starting on November 9, 2015. If you’re using AppConversions in v201509 or v201506 with AppPlatform: ITUNES, you’ll need to make sure that you’re using the correct AppConversionType.

What was the old behavior?

When v201509 was first released, the API would not throw an error if the incorrect value was sent in a request for an iTunes AppConversion. The API automatically converted to the correct AppConversionType. For example, if the value DOWNLOAD was passed into v201509 for an iTunes AppConversion, then that value would automatically be converted to FIRST_OPEN.

What is the new behavior?

In v201509, AppConversionType DOWNLOAD changed to FIRST_OPEN for iTunes apps. Here’s what you will need to do:
  • For v201506 or earlier, you must pass in AppConversionType DOWNLOAD rather than FIRST_OPEN.
  • For v201509 or later, you must pass in FIRST_OPEN instead of DOWNLOAD.
Passing in the incorrect value will result in the error DOMAIN_EXCEPTION from the API starting on November 9.

Note: This only impacts iTunes conversions. There will be no changes to the validation for AppConversions with an AppPlatform of ANDROID.

Where can I learn more?

For more information on mobile apps and conversions, check out these guides: Questions? Visit us on the AdWords API Forum or our Google+ page.

Posted:
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.

Posted:

In preparation for improvements to CPA bidding in AdWords, starting October 26, 2015, we'll perform a one-time removal of inactive ad group-level CPA bids.

What's an inactive ad group CPA bid, you ask? An ad group-level CPA bid is inactive if the ad group's effective bidding strategy is not a CONVERSION_OPTIMIZER strategy. This includes CPA bids on ad groups whose effective bidding strategy is TARGET_CPA, since the target for such ad groups is specified at the strategy level. The effective bidding strategy is the ad group-level strategy, if specified. Otherwise, it’s the bidding strategy set at the campaign-level.

How this change impacts the AdWords API

After the one-time removal of inactive CPA bids, there are two categories of ad groups you'll want to review:
  • Ad groups from which inactive CPA bids were removed: For these ad groups, the AdGroup object will no longer have a CpaBid in the bids attribute of its ad group-level BiddingStrategyConfiguration. Therefore, if you change the effective bidding strategy of these ad groups back to a CONVERSION_OPTIMIZER strategy, you will have to add a new CpaBid to the ad group’s BiddingStrategyConfiguration for your ads in the ad group to serve. You will only have to make this change once.
  • Ad groups you change from TARGET_CPA to CONVERSION_OPTIMIZER: AdWords will no longer copy the TargetCpaBiddingScheme.targetCpa value to a CpaBid on the ad group's bidding strategy configuration. Therefore, you will not automatically get the TARGET_CPA strategy bid if you transition to CONVERSION_OPTIMIZER. If the ad group's bidding strategy configuration already has a CpaBid, then CONVERSION_OPTIMIZER will use that bid. Otherwise, you will have to add a new CpaBid to the ad group BiddingStrategyConfiguration before ads in your ad group will serve.

How this change impacts bidding

Since the CPA bids being removed are inactive, this change will have no impact on bidding or ad serving.

What you should do

If you are interested in inactive CPA bids for CONVERSION_OPTIMIZER bidding strategies, download the current bids using AdGroupService before the removal date.

More bidding resources

Still have questions? Feel free to visit us on the AdWords API Forum or our Google+ page.

Posted:
Last year, we announced upgraded location extensions, a more efficient way to manage and use business locations in ads by linking Google My Business and AdWords accounts. To help you manage your business locations more easily at scale, we’re now releasing the Google My Business API.

Google My Business will be the central repository for managing your business locations. The creation of manual location extensions as feed items through the AdWords API has been deprecated and will sunset in Q2 2016. Please update your code before March 31, 2016 to avoid being impacted by this transition.

Supported features
The first version of the Google My Business API allows you to read, create, update and delete unverified business locations. Supported attributes are name, address, contact numbers, URL, categories, and business hours. Unverified locations can be used as location extensions in AdWords, but have to be verified to be eligible to show up on Google Maps.

Future releases of the Google My Business API will support additional functionality that will allow you to fully manage your location data across Google Ads and Maps.

Getting started with the Google My Business API
If you already use the AdWords API and manage more than 50 business locations, you can apply for access to the Google My Business API. Once granted, you will have access to the Google My Business API documentation and you can follow the steps there to get started. For accounts with 50 or fewer locations, please use Google My Business Locations for now.

Linking locations to accounts, campaigns or ad groups as location extensions
Users managing multi-location businesses (chains) must have a separate Google My Business account for each chain for bulk-verification. If you already manage locations under bulk-verified accounts in Google My Business today, you can link those accounts to AdWords to have your location extensions in sync.

For developers managing AdWords accounts with a large number of locations for small and medium businesses, we recommend creating one Google My Business account as a central repository for all locations. Each physical location should be created only once. If different owners and managers are involved per location or for sets of locations, we suggest using Business Accounts.

Once the AdWords accounts are linked to your shared Google My Business account, the locations will be available as feed items in AdWords. You are responsible for creating a CustomerFeed and using an appropriate matching function to make sure only locations that actually belong to the customer are linked to their related AdWords account. You can use CampaignFeeds or AdGroupFeeds for additional filtering based on campaigns or ad groups.

The best way to filter locations from a shared Google My Business account is to create location labels through the Google My Business API and use a matching function that uses these labels for selection. For example, you can label each location with its AdWords Customer ID in Google My Business and use these Customer ID labels for filtering in AdWords. Or you can label each location with a unique ID, as long as you keep track of these IDs.

Please see our guide for managing location extensions for further details, which also includes an end-to-end code example.

Migration of existing location extensions
If you are using manual location extensions through the AdWords API, we recommend migrating your locations to Google My Business before March 31, 2016. After this date, the creation of manual location extensions will sunset. All unmigrated locations stored in AdWords will be auto-migrated to Google My Business at a later date. Further details about the timeline and process will be announced in this blog.

Posted:
AdWords API v201502 will be sunset on November 12, 2015, after which all v201502 API requests will begin to fail. This version was deprecated on June 25, 2015. If you are still on v201502, we recommend that you migrate directly to v201509 (released last week) and skip v201506. Please be sure to migrate soon to ensure your API access is unaffected.

We have prepared various resources to help 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.

Posted:

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.

Posted:

Fall 2015 AdWords API Workshop registration is now open. Access the registration forms on the workshop website at www.adwordsapiworkshops.com.

Once you choose a location we'll send you an email confirming your registration.

Workshops will be held on the following dates and locations:

  • New York City: October 20
  • San Francisco: October 22
  • London: October 27
  • Hamburg: October 29
  • Tokyo: October 29
  • Amsterdam: November 3

These workshops are technical in nature and are ideal for API developers. We hope to see you at these events. Register today!

If you have any questions about the AdWords API Workshops, you can post them on our forum. Check out our Google+ page for AdWords API updates.

Posted:

The AdWords API Workshops are back, and the registration form and agenda will be available on the website soon: www.adwordsapiworkshops.com. In the meantime, you may review the site Resources section for previous event presentations.

These workshops are a series of technical events, ideal for those who are working with the AdWords API.

Workshops will be held on the following dates and locations:

  • New York City - October 20
  • San Francisco - October 22
  • London - October 27
  • Hamburg - October 29
  • Tokyo - October 29
  • Amsterdam - November 3

Stay tuned and keep an eye on the website for more details on how to register.

--AdWords API Team

Posted:
Have you ever wanted to advertise to people who previously visited your site or mobile app? This remarketing strategy can be implemented using the AdWords API. For example, you can target ads to people who left your website without buying anything to encourage them to return and make a purchase.

We recently updated our Remarketing and Rule-based Remarketing guides to more clearly show you how to use the API to get started quickly and implement some of the most common remarketing strategies.

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

Posted:
Following the release of AdWords API v201506, we've added a few additional features that are available immediately:
  • Android App ‘first open’ conversion tracking. Recently available in AdWords, this new conversion tracking solution measures when a user first opens an app after clicking on an ad and completing an Android app install. Check out the new FIRST_OPEN conversion type in the AppConversion tracker that also supports Postback URLs for Android.
  • A new report specific to final URLs: FINAL_URL_REPORT. The report replaces the deprecated DESTINATION_URL_REPORT and provides statistics aggregated at the final URL level.
We also launched account hiding support recently—see this announcement if you missed it. If you have any questions, feel free to reach us on the forum or via the Ads Developers Plus Page.

Posted:
Starting with v201506 of the AdWords API, you can: With these new features, you can hide old or inactive accounts to reduce clutter in your managed account's dashboard, as well as detect and exclude hidden accounts using the AdWords API.

As with the AdWords user interface, you can only hide or unhide AdWords accounts. Any attempt to hide a manager account will result in a ManagedCustomerServiceError.CANNOT_HIDE_OR_UNHIDE_MANAGER_ACCOUNTS error.

Don't worry -- hiding an account doesn’t affect serving:
  • You can always unhide an account by setting the isHidden attribute of its ManagedCustomerLink back to false.
  • You can retrieve all of your accounts by setting ExcludeHiddenAccounts to false in your selector, or by not specifying a predicate on ExcludeHiddenAccounts.
  • Ads in hidden accounts will continue to serve.
More manager account resources Still have questions? Feel free to visit us on the AdWords API Forum or our Google+ page.

Posted:
Have you ever found it frustrating that you can never reuse an AdGroup name after removing the AdGroup, since a removed AdGroup cannot be modified? We have awesome news for you!

Now, AdGroupService doesn’t consider REMOVED AdGroup names when verifying that an AdGroup name is unique within a Campaign. If an AdGroup is in a REMOVED state, then the name of that AdGroup can be reused. This is already the case for Campaigns, and we’ve extended this relaxation of constraints to AdGroups.

If you have questions or need clarification, visit us on the AdWords API Forum or our Google+ page.

Posted:
For those of you who’d prefer to generate an OAuth refresh token using only a browser, there's a new guide on how to use the OAuth 2.0 Playground:

https://developers.google.com/adwords/api/docs/guides/oauth_playground

The guide walks you through the authorization setup required by the AdWords API for a Web application--via a browser session--without the need to execute any command-line scripts.

More OAuth resources
Still have questions? Feel free to visit us on the AdWords API Forum or our Google+ page.

Posted:
What's changing?
Starting on or after July 23, 2015, if you are using v201506 of the AdWords API, then FeedMappingService.get and FeedMappingService.query will return FeedMapping objects created for location targeting. These FeedMapping objects will have criterionType 77, and will not have a value for placeholderType. There will be no change in behavior for v201409 or v201502.

You will start seeing these objects if either of the following is true:
  • You created a Feed linked to your Google My Business account.
  • You created a Location targeting feed through the AdWords user interface, under Shared library -> Business data.
Why the change?
Starting with v201506, LocationGroups.feedId is required if your matching function includes a LocationExtensionOperand.

Specifying a feedId in this situation allows AdWords to target the areas surrounding the locations in a location targeting feed. This may be the same feed you are using for location extensions, or a separate feed containing additional locations you want to use strictly for targeting. The key point is that the Feed referenced by LocationGroups.feedId must have a FeedMapping with criterionType 77.

What should you do?
If your application retrieves FeedMapping objects, make sure it will properly handle objects where placeholderType is null and criterionType is set.

If you want to create LocationGroups objects that use a LocationExtensionOperand, you can now use FeedMappingService to find the ID of feeds that have a FeedMapping with criterionType 77.

Learn more
Check out the following resources for more information on Location Groups: Still have questions? Feel free to visit us on the AdWords API Forum or our Google+ page.

Posted:
On or shortly after August 24th, we will remove the BROAD_SESSION match type label from the MatchType column in the Search Query Performance and Paid & Organic Query reports. Instead, rows that formerly returned "broad (session-based)" will begin returning "broad".

To simplify the way we report on match types, this label will be removed from all of our reports, including historical reports. If you'd like to see how your keywords are currently matching to this label, download a copy of your Search terms report before August 24th, 2015.

This is a reporting change and will have no impact on the broad match serving behavior. You can learn more about the MatchType column in the AdWords Help Center.

As always, if you have any questions, comments, or concerns, please contact us via the forum or the Ads Developers Plus Page.

- Michael Cloonan, AdWords API Team

Posted:
Waiting to see whether or not your ads have been approved can be time-consuming. That's why we're improving the validation logic during ad creation to “fail fast” for one common invalid URL case.

Currently, with new Upgraded URLs, an ad with a final URL domain that doesn't match the display URL domain will be disapproved. Starting on August 12th, 2015, rather than allowing these ads to be submitted for approval, the AdWords API will return an error for any request attempting to create an ad where the final URL domain doesn't match the display URL domain. This will allow you to fix these issues faster and get your ads up and running sooner.

As usual, if you have any questions, comments, or concerns, please contact us via the forum or the Ads Developers Plus Page.


- Michael Cloonan, AdWords API Team

Posted:
AdWords API v201409 will be sunset on July 28, 2015, after which all v201409 API requests will begin to fail. This version was deprecated on March 5, 2015. With the release of v201506, you now have less than 5 weeks to migrate directly to v201506 and skip v201502 entirely. Please make sure to migrate soon to ensure your API access is unaffected.

We have prepared various resources to help 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.

Posted:
Today we're announcing the release of AdWords API v201506. Here are the highlights:
  • Location extensions within a geographic area is now configurable through the API, which in previous versions was a read-only feature. LocationGroups provides a feedId that is now required when specifying a LocationExtensionOperand in the matching function.
  • Updates to reporting. Gmail Sponsored Promotion stats are now available in reporting. We’ve added new columns to existing reports, including the Final Url column to the Search Query report and start and end dates to Campaign Performance report. See the release notes for the complete list.
  • Improved ConstantDataService. CriterionUserInterest objects now have a new parent ID attribute that allows for navigation of the user interest taxonomy hierarchy.
  • AWQL improvements. You can now explicitly include or exclude zero impression rows when requesting reports using AWQL. Also, the DURING clause became optional when defining ALL_TIME reports. Shared set services were extended with the AWQL query() method. 
  • Improvement to labels. You can now programmatically set label descriptions and colors using the API.
If you're using v201409 of the AdWords API, please note that it's being sunset on July 28th, 2015. We encourage you to skip v201502 and migrate straight to v201506. If you're using v201502, be aware it's now marked deprecated and will be sunset on November 5th, 2015.

As with every new version of the AdWords API, we encourage you to carefully review all changes in the release notes and the v201506 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.