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.

Timo Bozsolik, AdWords API Team

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:

• v201509 migration guide
• v201506 migration guide
• Release notes

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

- Michael Cloonan, AdWords API Team

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.

- Josh Radcliff, AdWords API Team

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.

—AdWords API Team.

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

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

• Remarketing guide
• Rule-based Remarketing guide
• Remarketing product overview

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

- Andrew Kallem and Amir Lazarovich, AdWords API Team

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.
 - Danial Klimkin, on behalf of AdWords API Team.

Starting with v201506 of the AdWords API, you can:

• Hide or unhide an AdWords account under your manager account by setting the isHidden attribute of its ManagedCustomerLink to true or false, respectively.
• Exclude hidden accounts in ManagedCustomerService.get and ManagedCustomerService.query calls by specifying ExcludeHiddenAccounts = true in your predicate or AWQL WHERE clause.

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

• Guide on managing customer accounts.
• Latest docs on ManagedCustomerLink and ManagedCustomer.

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

- Josh Radcliff, AdWords API Team

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.

Nadine Sundquist, AdWords API Team

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

• OAuth 2.0 Authentication for the AdWords API
• Using OAuth 2.0 to Access Google APIs

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

- Josh Radcliff, AdWords API Team

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:

• The updated placeholders documentation describes the required fields for a location targeting feed.
• The AddCampaignTargetingCriteria example in the targeting folder of each client library shows how to set up a LocationGroups object using the ID of your location targeting feed.
• The AdWords Help Center has an overview of using Location Groups.

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

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

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

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:

• v201506 migration guide
• v201502 migration guide
• Release notes
• Sunset schedule

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

- Michael Cloonan, AdWords API Team

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.
 - Danial Klimkin, on behalf of AdWords API Team.

Update: As of July 9th, 2015, this temporary limit has been removed.

To ensure reliable performance for all advertisers during advanced URL upgrades, the AdWords API has placed a temporary limit on the number of AdGroupAd ADD operations that can be performed on an advertiser account per day. Other types of requests are not affected by this change. Please review the RateLimit documentation and make sure your code handles the RateExceededError properly.

During most normal operations, you won’t run into these limits. However, if you are uploading a very large amount of new ads in a short period of time and find yourself running into this error frequently, let us know on our forum and we will work with you to address the issues.

Anash P. Oommen, AdWords API Team

This release of AwReporting introduces new command-line arguments that can be used to import CSV files into AwReporting without using the AdWords API. So you can download reports from the AdWords user interface, even reports not available via the AdWords API like the Video Campaign Report, and import them into your database.

Offline reports

The command-line arguments that allow the tool to import reports directly from downloaded files are:

• onFileReport, where you specify the Report Type (same ones used in the API).
• csvReportFile, where you specify the absolute path of the CSV file that will be imported to the database.

Here is a command-line example including the new arguments:

$ java -Xmx1G -jar aw-reporting/target/aw-reporting.jar \
      -startDate YYYYMMDD -endDate YYYYMMDD \
      -file aw-reporting/src/main/resources/aw-report-sample.properties \
      -onFileReport CAMPAIGN_PERFORMANCE_REPORT \
      -csvReportFile 

Keep in mind that AwReporting will only be able to import reports that are mapped in the aw-reporting-model module. You can check out the supported types on the project's GitHub source code page.

The CSV files must be in the same format as the ones downloaded by AwReporting via the API:

• The first line of the file must contain a string with the file description.
• The second line must contain the column headers with the field names.
• The remaining lines contain the report data.
• The last line will be ignored if it's a Total line.

Here is an example:

"ACCOUNT_PERFORMANCE_REPORT (May 1, 2015-May 10, 2015)"
Customer ID,Day,Account,Cost,Clicks,Impressions
1234,2015-05-01,Test Account,1420000,10,1978
1234,2015-05-02,Test Account,550000,4,2209
1234,2015-05-03,Test Account,1290000,6,3458
1234,2015-05-04,Test Account,320000,2,714
1234,2015-05-08,Test Account,1380000,5,2955
1234,2015-05-09,Test Account,1200000,6,2602
1234,2015-05-10,Test Account,750000,4,2793
Total, --, --,6.91,37,16709

Video Campaign Performance Reports

The AdWords API doesn't support video campaign performance reports, but you can still access the web interface and download the CSV files manually.

With the new offline import feature described above, we have added support for video campaign reports in AwReporting, allowing you to import all available fields in the web interface to the same database where the other reports are stored. We hope that this feature will make it easier to integrate systems and dashboards to the database, including video campaign performance data of clients.

To import a video campaign report CSV file, you just need to specify the report type in the onFileReport property as VIDEO_CAMPAIGN_REPORT, and point to the absolute path of the file in the csvReportFile property. The properties can be found in the source code of the project, in the ReportVideoCampaign.java entity.

Before importing the CSV files downloaded from the web interface, you will need to make sure that they are following the format described above, so AwReporting can understand it. You can find an example that we used on our unit tests in the project's source code.

You can check out these new features and the latest released version on the project's main GitHub page. And because AwReporting is open source, you can experiment with the code itself, by adding new types of reports as you need them. The project's GitHub page also includes the complete installation instructions.

If you have any questions about the tool, have ideas for new features, or find any bugs, you can post them as issues in GitHub. We maintain the tool, and the list of issues on GitHub is our first option when planning for next releases.

And of course, make sure to check out our Google+ page for client library and Ads APIs updates.

Gustavo M. P. Moreira, Ads API Team

With destination URLs becoming read-only on July 1, 2015, we’re making your migration to Upgraded URLs simpler. If you come across some extra attributes in Feed and FeedMapping, there’s a good reason for that.

We’re helping you skip the approvals process for existing site links during migration by modifying your Feeds and FeedMappings behind the scenes. The changes are already available, and you should see extra attributes in each of your Feeds and FeedMappings.

Expect to see attributes in Feeds with these FeedAttribute names:

• SitelinkFinalUrls
• SitelinkFinalMobileUrls
• SitelinkTrackingUrl

The FeedMapping attributeFieldMappings now have extra AttributeFieldMappings related to these Sitelinks Placeholders:

• FINAL URLS
• FINAL MOBILE URLS
• TRACKING URL

Your sitelink feeds are now compatible with the new Upgraded URLs.

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

Nadine Sundquist, AdWords API Team

We are updating the Paid and Organic report to include only text ad statistics. Impressions and clicks for mobile app install ads and Product Listing Ads will be excluded from this report starting July 13, 2015.

These formats serve in places other than on search results, so we are excluding them to provide you a better comparison across paid and organic listings at the query level. If you use data from the Paid and Organic report in any of your AdWords API or Scripts applications, then make sure you update them to adjust for this data change. Historic stats for mobile app install ads and Product Listing Ads will continue to be available from this report type up to the following report dates:

• Product Listing Ads - up to and including March 23, 2015
• Mobile app install ads - up to and including July 13, 2015

If you have any further questions about this change, let us know via the API or scripts forum, or Google+ page.

Anash P. Oommen, AdWords API Team

We would like to remind you that as previously announced, destination URL fields in AdWords will become read-only on July 1, 2015. Starting on that date, we will also begin upgrading your URLs (if eligible) to the new Upgraded URLs structure.

Once this change goes live, you will get the following errors from the AdWords API:

• EntityAccessDenied.WRITE_ACCESS_DENIED error if you try to modify:
  • destinationURL field of BiddableAdGroupCriterion
  • appUrl field of AppFeedItem
  • sitelinkUrl field of SitelinkFeedItem
  • attributeValues field of FeedItem that corresponds to a column with mapping for a sitelink URL, app URL or a dynamic remarketing destination URL
• AdError.CANNOT_SET_FIELD error if you try to modify the url field of various ad types

In AdWords scripts, all methods that set the destination URL of various entities have been marked deprecated, and will generate a user error after July 1, 2015.

Before then, be sure to update your AdWords API and scripts code. Use the Upgraded URL fields instead of the destination URL field when creating entities such as ads, keywords, or sitelinks. You can refer to our migration guide to learn how to upgrade your URLs, or our feature guide to learn more about Upgraded URLs. All our client libraries fully support upgraded URLs, and provide code examples that show you how to use this feature and upgrade your URLs.

If you have any further questions about this change, let us know via our API or scripts forum, or Google+ page.

Anash P. Oommen, AdWords API Team