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

On Monday, November 30, 2015, in accordance with the deprecation schedule, v201408 of the DFP API will be sunset. At that time, any requests made to v201408 will return errors.

If you're still using v201408, now's the time to upgrade to the latest release and take advantage of new features like line item level reconciliation (see our guide here). To do so, check the release notes to identify any breaking changes, grab the latest version of your client library and update your code.

Some changes to look out for:

• Flash creatives have been updated to use CreativeAssets.
• Report DimensionFilters have been replaced by PQL equivalents.
• The ReportService's getReportJob has been replaced with getReportJobStatus. The new method returns only the ReportJobStatus.
• The ForecastService was given a facelift, adding support for a new kind of forecast and more granular breakdowns.
• LineItem.startDateTime and LineItem.endDateTime now require a timeZoneID. You can retrieve all of the supported time zone IDs from the Time_Zone PQL table.
• Type fields have been removed from all entities. Use class names, instance of, or xsi:type instead.

This is not an exhaustive list, so as always, don't hesitate to reach out to us with any questions. To be notified of future deprecations and sunsets, join the DFP API Deprecation Announcements group and adjust your notification settings.

 - Chris Seeley, DFP API Team

On Monday, August 31, 2015, in accordance with the deprecation schedule, v201405 of the DFP API will be sunset. At that time, any requests made to v201405 will return errors.

If you're still using v201405, now's the time to upgrade to the latest release and take advantage of fresh new features like DeliveryForecasts. To do so, check the release notes to identify any breaking changes, grab the latest version of your client library and update your code.

Some changes to look out for:

• The endpoint URL for requests has changed from https://www.google.com to https://ads.google.com. We updated this in the default settings of our client libraries, but double check your local configuration files as well.
• LineItem.startDateTime and LineItem.endDateTime now require a timeZoneID. You can retrieve all the supported time zone IDs from the Time_Zone PQL table.
• The ForecastService was given a facelift, adding support for a new kind of forecast and more granular breakdowns.
• All MERGED_* reporting metrics have been deprecated and removed.
• The ReportService's getReportJob is now getReportJobStatus. The new method returns only the ReportJobStatus, not the entire ReportJob.

This is not an exhaustive list, so as always, don't hesitate to reach out to us with any questions.

 - Chris Seeley, DFP 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

It's that time again - time to say goodbye to another version of the DFP API. In accordance with our deprecation schedule, v201403 has been deprecated and is scheduled for sunset on Tuesday, June 30 2015. At that time, any requests made to v201403 will return errors.

If you're currently using v201403, there's still time to migrate to the latest and greatest v201502. To do so, check the release notes to identify any breaking changes, grab the latest version of your client library, and update your code!

Things to look out for include:

• OAuth SOAP headers are no longer supported. You'll need to pass authentication information in HTTP headers instead. If you're using a client library, we took care of this for you.
• Line item fields unitsBought and unitType have moved into the Goal object.
• The endpoint URL for requests has changed from https://www.google.com to https://ads.google.com. We updated this in the default settings of our client libraries, but double check your local configuration files as well.
• LineItem.startDateTime and LineItem.endDateTime now require a timeZoneID. You can retrieve all the supported time zone IDs from the Time_Zone PQL table.
• The ForecastService got a facelift, including renaming existing methods and adding support for a new kind of forecast.

This is not an exhaustive list, so as always don't hesitate to reach out to us on our API forum with any questions.

 - Chris Seeley, DFP API Team

Now that it’s spring again (in the Northern Hemisphere at least), it’s time for DFP’s annual spring cleaning! In this edition, we’ll be doing some pruning of our ReportService. What does this mean for you? We’re sunsetting some reporting dimensions, attributes, and metrics in existing versions (before the version is fully sunset), so your reports will break if you don’t migrate before the shutoff dates. I know what you’re wondering: “should I panic?”. Absolutely not. This type of behavior rarely occurs, so as long as you phase out usage for these particular fields, you should be fine moving forward.

Merged Metrics

Remember when Doubleclick for Publishers was called DART? I, too, get nostalgic about our old ad server, but it’s been a couple of years since we transitioned to the new DFP platform, and it’s just about time when the merged reporting columns are no longer useful (these columns only existed so you could continue reporting on delivery that spanned DART and DFP). In all versions after v201502, we will no longer provide merged reporting columns and dimension attributes in the API, that is, anything starting with 'MERGED_' or contains '_LIFETIME_MERGED_.' After August 1, 2015, these columns and dimension attributes will stop returning data entirely and will return INVALID_COLUMNS in all versions that still include them.

There are three scenarios in which you’re using these columns:

1. Just for fun.
2. Because you forgot you’re using them.
3. Because you have lifetime line items that have carried over from DART (in which case you’ll have to recreate these). To give you an example, if the metric you care about is impressions, you can get the DART delivery portion by subtracting the portion of delivery from DFP Premium (AD_SERVER_IMPRESSIONS) from the MERGED value (MERGED_AD_SERVER_IMPRESSIONS) which represents the aggregate DART and DFP Premium volume. Additionally, you should make the switch to the non-merged columns and dimension attributes as soon as possible.

Dimension Filters

But wait, there’s more! Our next API version (v201505) will be the last to support some of our infrequently used dimensionFilters.

• MOBILE_LINE_ITEMS
• WEB_INVENTORY_UNITS
• MOBILE_INVENTORY_UNITS
• WHOLE_NETWORK
• PARTNER_STATS_TYPE_ESTIMATED
• ACTIVE_ADVERTISERS
• PARTNER_STATS_TYPE_RECONCILED
• WEB_LINE_ITEMS
• ALL_SALESPEOPLE

In each of the cases above, the filters either no longer provide meaningful information (as is the case with mobile vs. web line items and ad units with platform unification complete), or weren’t being used at all.

Similar to the changes above, after August 1, 2015, these dimension filters will return an INVALID_DIMENSION_FILTERS error in any version that still includes them.

So if you’re using any of the reporting features above, consider this an early heads up (and an opportunity) to refactor some of your code for spring cleaning.

As usual, if you have any questions, comments, or concerns, don’t hesitate to let us know on the forums.

 - Nicholas Chen, DFP API Team

AdWords API v201406 will be sunsetted on April 6th, 2015, after which all v201406 API requests will fail.

This version was deprecated on October 8th, 2014. There are less than 4 weeks left before the sunset, so make sure to migrate to v201502 (recommended) or v201409 as soon as possible to ensure that your access to the API is unaffected.

We have prepared various resources to help the transition to a newer version of the API:

• v201502 migration guide
• v201409 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

We'd like to remind you that the AdWords API v201402 was deprecated on July 9th and will be sunset on November 6th, 2014. With the sunset deadline only a few weeks away, if you haven't already migrated to v201406 or v201409, please do so as soon as possible.

As with each sunset, we have the following resources available for you:

• v201406 migration guide
• v201409 migration guide
• Release notes
• Sunset schedule

If you have any questions or need help with the migration, please post on the forum or the Ads Developers Plus Page.
 - Danial Klimkin, AdWords API Team.

On November 5, 2014, we'll be sunsetting the login field in the ManagedCustomer class. We understand this may impact your applications and are recommending the following options to account for this change:

Maintaining customer contacts

You should not use the login field to manage your clients' contacts and email addresses. You should always maintain your own client contacts. If your application currently relies on the login field, you can use ManagedCustomerService.get() to create a mapping between customer IDs and login emails before November 5, 2014.

Identifying client accounts

CustomerId should be used instead of the login field to uniquely identify an account. To provide a friendly name for an account, you can use the name field. You may set the name field when creating a new account using the ManagedCustomerServer.mutate() method.

AdWords allows users to invite multiple users to manage their applications as well as change their AdWords sign-in information. However, the login field is not updated to reflect changes in AdWords sign-in information. So relying on the login field makes your application error prone if a user changes their AdWords sign-in information.

Determining the access level of a user

Your application runs with the same access levels as the user whose OAuth2 access token you send in your API calls. To determine if a user is authorized to make a particular change, you can make API calls with the validateOnly header set to true. If the user isn’t authorized to make changes, the call will fail with an AuthorizationError.

Login field information doesn't convey the access level the user has within AdWords. If you rely on a user’s login email to determine their access level, your application may run into errors if the user’s account access levels change.

If you have questions or feedback about this change, or encounter a use case we’ve missed, let us know on our developer forum or Google+ page.

- Anash P. Oommen, AdWords API Team

We removed the PrimaryUserLogin column from all our reports in AdWords API v201406. To keep the rest of our API consistent, we will also remove the login field from ManagedCustomer class in the next AdWords API release. Existing versions of the AdWords API will stop returning values for this field starting November 5, 2014.

If you’re currently using the login field to identify an account, you can use the customerId or name field instead. The AdWords API uses OAuth 2.0 as its authentication mechanism, which allows users to grant access to your application to manage their AdWords accounts, without sharing their email addresses.

To ensure your applications continue to work properly, stop using this field before November 5, 2014. If you have any further questions about this change, let us know via our forum or Google+ page.

Anash P. Oommen, AdWords API Team

Update: All new location extensions created on or after October 16th, 2014 can only be created as new account-level feed-based location extensions.

On July 14th, 2014, AdWords announced upgraded location extensions, a more efficient way to manage and use business locations in ads by linking Google My Business and AdWords accounts.

The upgrade is taking place in phases for AdWords accounts throughout the coming months. The next phase of account upgrades is scheduled to start on August 25, 2014. All AdWords accounts will to be upgraded by November, 2014.

The upgrade has direct impact to AdWords API client applications. If you are using the CampaignAdExtensionService to manage LocationExtensions or LocationSyncExtensions, then you’re using the legacy location extensions that are being phased out. After an account is upgraded, you’ll need to use the new account-level feed-based location extensions.

How will existing location extensions be upgraded by Google?

Please review the AdWords Help Center article for all upgrade scenarios. For AdWords API developers, most accounts will fall into one of these scenarios:

• Accounts that don’t have any existing legacy location extensions.
• Accounts that have existing legacy location extensions not sourced from a Google My Business account (i.e., using LocationExtensions only).
• Accounts that have existing legacy location extensions sourced from a Google My Business account (i.e., using LocationSyncExtensions).

If you programmatically create AdWords accounts that are not associated with any user, please get in touch with your Google representative for migration support.

Accounts that don’t have any existing legacy location extensions

For accounts that aren’t using any LocationExtensions or LocationSyncExtensions but will begin using location extensions, you should use feed-based location extensions instead.

Accounts that have existing legacy location extensions not sourced from a Google My Business account

If you’re using LocationExtension entities to manage individual locations, the automatic upgrade process will perform the following:

1. A Google My Business account will be created and linked with the AdWords account. All administrators of that AdWords account will have access to locations in the linked Google My Business account.
2. A CustomerFeed with the Location placeholder type will be created.
3. Existing locations in LocationExtension entities will be copied into the Google My Business account. Existing LocationExtension entities will then be removed.
4. Ads in all campaigns will be served with locations from the linked Google My Business account (you can create a CampaignFeed to further filter or disable location extensions served for a given campaign).

Accounts that have existing legacy location extensions sourced from a Google My Business account

If you’re using LocationSyncExtension to link campaigns to a Google My Business account, then the automatic upgrade process will perform the following:

1. The campaign-level links to the Google My Business account will be switched to a single link at the account level.
   • A CustomerFeed with the Location placeholder type will be created for the account.
2. Any existing LocationExtension entities will be removed, so make sure they’re copied to the linked Google My Business account before the upgrade.
3. Ads in all campaigns will be served with locations from the linked Google My Business account (you can create a CampaignFeed to further filter or disable location extensions served for a given campaign).

If an AdWords account is already linked to Google My Business at the account level using CustomerFeed, any existing legacy location extensions will be removed during the upgrade process.

How do I know if an account has been upgraded?

An account is considered upgraded if either condition is true:

1. It has a CustomerFeed for the Location placeholder type. You can query CustomerFeedService to check:

   select FeedId, PlaceholderTypes where PlaceholderTypes = 7
   

2. It has neither a CustomerFeed nor legacy LocationExtension or LocationSyncExtension entities.

In an upgraded account, any attempts to create legacy location extensions using the CampaignAdExtensionsService will return the AdExtensionError.INVALID_ADEXTENSION_TYPE error.

How do I continue to manage locations?

There’s currently no API support for Google My Business. Locations are managed via the Google My Business Locations interface, which supports bulk management.

Can I start using upgraded location extensions before an account is upgraded?

Since the upgrade process is complicated for many accounts, the simplest approach is to allow accounts using legacy location extensions to be automatically upgraded (account owners will be notified 30 days before the upgrade).

What about reporting?

For upgraded accounts, you’ll need to use the Placeholder Feed Item Report rather than the Ad Extensions Performance Report to download statistics for each location.

We are here to help

If you have any questions about this upcoming change or anything else related to the AdWords API, please contact us on the AdWords API forum or via the Google Ads Developers Google+ page.

- Ray Tsang, AdWords API Team

ClientLogin authentication support for the AdWords API and the DoubleClick Ad Exchange API will sunset along with v201309 on July 21st, 2014. You only have 3 weeks left to migrate!

We have plenty of resources to help you migrate. It might take longer than you expect to migrate to OAuth 2.0, especially if you don't already use a single top-level MCC to manage your AdWords accounts or if you are a DoubleClick Ad Exchange customer.

Start your migration as soon as possible and reach out to us early on the AdWords API Forum or the DoubleClick Ad Exchange API Forum with any questions.

- Ray Tsang, AdWords API Team

The CONVERSION DURATION THRESHOLD placeholder was deprecated on April 28th, 2014. Starting July 21st, 2014, using this placeholder with the FeedMappingService will result in a FeedMappingError.INVALID_PLACEHOLDER_FIELD error for all AdWords API versions.

See this post for details on how to set your conversion duration going forward with the CONVERSION TYPE ID placeholder instead.

If you have any questions about this upcoming change or anything else related to the AdWords API, please contact us on the AdWords API forum or via the Google Ads Developers Google+ page.

- Ray Tsang, AdWords API Team

ClientLogin authentication support for the AdWords API and the DoubleClick Ad Exchange SOAP API will sunset along with v201309 on July 21st, 2014. You only have two months left to migrate - don’t wait until the last minute!

We have plenty of resources to help you migrate. It might take longer than expected to migrate to OAuth2, especially if you don't already use a single top-level MCC to manage your AdWords accounts or if you are a DoubleClick Ad Exchange customer.

Start your migration as soon as possible and reach out to us early on the AdWords API Forum or the DoubleClick Ad Exchange API Forum with any questions.

- Ray Tsang, AdWords API Team

ClientLogin authentication support for the AdWords API will sunset along with v201309 on July 21st, 2014. But it doesn’t mean you should wait till the last minute to migrate!

We have plenty of resources to help you migrate. It might take longer than expected to migrate to OAuth2, especially if you don't already use a single top-level MCC to manage your AdWords accounts.

Start your migration as soon as possible and reach out to us early on the AdWords API Forum with any questions.

- Ray Tsang, AdWords API Team

As we have previously announced, if you're using the AdWords API or Ad Exchange Buyer SOAP API v201306, please note that support for this version will end on March 31st, 2014. If you are still using v201306 after that date, all requests will fail and your application will cease working until you migrate to a supported version. You can reference either the v201309 or v201402 migration guides for help upgrading to one of these versions.

In addition, remember that ClientLogin support is deprecated and you will have to migrate to OAuth 2.0 in order to authenticate starting in version v201402. It may be best to get this out of the way now, because with the sunset of v201309 on July 21st, 2014, all support for ClientLogin will go away and OAuth 2.0 will be required to access the API. Please reference our OAuth 2.0 migration guide for help with this process.

If you have any questions about this upcoming change or anything else related to the AdWords API, please contact us on the forum or via our Google+ page.

- Michael Cloonan, AdWords API Team

In AdWords API v201309 we released a new Google Click ID field (GCLID) in the Click Performance report. Originally, this field value was limited to 26 characters. We will be extending the maximum length of this field in order to support improvements to our advertising system. Starting March 31st 2014, the value of GCLID can be up to 100 characters long.

Since this value is used in many client systems, we’re giving you advance warning of this change. Make sure your log, storage and redirecting systems can handle the extended size of the GCLID value.

Note: as a result of this change, the Click Performance report will only be available for dates up to 90 days before the time of a request. If you need the older click data, download and store these details before March 31st, 2014.

If you have any questions about the change, reach out to us on the forum or via the Google+ page.

- Danial Klimkin, AdWords API Team

We’d like to remind you the AdWords API v201302 was deprecated on July 10th and will be sunset on November 8th, 2013. With the sunset deadline only a few weeks away, if you haven’t already migrated to v201306 or better yet v201309, please do so as soon as possible.

Make sure to review the following resources available to aid the migration:

• v201309 release notes -- for every API change and version diffs
• v201309 migration guide -- for the list of breaking changes
• Client libraries page -- for updated official client libraries
• v201306 and v201309 announcement blog posts -- for feature highlights.

Subscribe to our forum and plus page to stay up to date with all of our important announcements. Also, feel free to contact us there with any questions related to API migration.

- Danial Klimkin, AdWords API Team

With the release of v1.2 (and the subsequent v1.3) of the AdSense Management API, older versions became deprecated, and we announced we would be retiring them later this year. The turnoff date will be August 12, 2013.

If your application is still using v1 or v1.1, please be sure to update it to use v1.2 ‒ or preferably, v1.3. The new versions build on top of the old ones, so all previous functionality will still be available and work exactly the same, which should make for an easy upgrade.

If you have any questions or need any help, be sure to join us in the forum!

 - Sérgio Gomes, AdSense Management API Team