Google Ads Developer Blog

Python 2 Deprecation in Ads API Client Libraries

2019-04-02T10:21:00.001-07:00

As the official End of Life date for Python 2 approaches, we will be ending support for Python 2 in both the AdWords/Google Ad Manager and Google Ads Python client libraries in 2019. After deprecation the minimum required Python version for both libraries will be 3.6+.

Deprecation will begin with the AdWords/Google Ad Manager Python client library in May. Here’s a timeline for easy reference:

mid-May: version 19.0.0 is released to support Google Ad Manager API v201905. Python 2 users should not upgrade to any major version beyond this.
mid-May - late-June: Python 2 deprecation window.
Last week in June: version 20.0.0 is released that is incompatible with Python 2.
July 1: Support for Python 2-related issues in the library ends.

If you are a user of the AdWords/Google Ad Manager client library, please take note of the following:

Google Ad Manager Users:
- If you’re already using Python 3, no need to take action.
- If you’re using Python 2 you should remain on version 19.0.0 until you’ve migrated to Python 3.
AdWords Users:
- Please migrate to the new Google Ads API.
- If you’re using Python 2 you should remain on version 19.0.0 until you’ve migrated to the Google Ads API.
All Users:
- Beginning July 1, 2019 we will discontinue prioritizing work and triaging GitHub Issues related to compatibility with Python 2. Note that we will submit patches to version 19.0.0 if any major bugs arise after this deadline.

The Google Ads API client library will continue to be compatible with Python 2 until the end of 2019. We will post more information about that migration at a later date. In the meantime, Python 2 users should start planning their migration to Python 3 as soon as possible in order to avoid complications.

If you have questions about the Python 3 migration please submit an issue on the respective GitHub repository, and for general API support please reach out to us on the Google Ads API forum or the Google Ad Manager API forum.
Ben Karl, Google Ads API Team

Announcing v1_1 of the Google Ads API

2019-03-27T12:52:00.000-07:00

Today we’re announcing the v1_1 release of the Google Ads API. With this version, you’ll continue pointing to v1 as your endpoint; however, you'll need to update your client libraries in order to use v1_1 features. If you're still on the AdWords API, now is a good time to give the new API a try.

Here are the highlights:

Ads. Create assets for asset-based ads using AssetService.
Campaigns. Create App Campaigns (equivalent to Universal App Campaigns in AdWords API) by creating a Campaign and setting the advertising_channel_type to MULTI_CHANNEL and the advertising_channel_sub_type to APP_CAMPAIGN.
Conversions. Adjust conversions with the new ConversionAdjustmentUploadService. Upload call conversions with the UploadCallConversionsRequest in the ConversionUploadService.
Hotel Ads. Hotel Ads now includes more metrics and segments. See the release notes for details.
Recommendations. Added Recommendation types MoveUnusedBudgetRecommendation and KeywordMatchTypeRecommendation.
Reporting. Views were expanded to include more metrics and segments. See the Reporting section in the release notes for exact details.

What resources are available?
Check out these helpful resources:

The updated client libraries and code examples will be published by March 29, 2019. If you have any questions or need help, please contact us via the forum.
Nadine Sundquist, Google Ads API Team

Google Ads API Policy Notes

2019-03-05T10:49:00.000-08:00

In our recent blog post we announced the launch of Google Ads API v1. Since the Google Ads API and AdWords API can both be used in production systems, we'd like to clarify a couple of policy items.

Terms and Conditions
You will need to accept our updated Terms and Conditions to access production-ready versions of the Google Ads API. If you attempt to access v1 without accepting the new terms, your request will fail with the error AuthorizationError.MISSING_TOS. Existing AdWords API users will not be required to re-accept the new Terms and Conditions to access the legacy API. For instructions on how to accept the new terms, please take a look at this blog post.

Rate Limits
All Google Ads API rate limits are independent of a developer's use of the AdWords API. If a developer token with Basic Access sends a request to one Ads API, the daily request limit for the other API will not be affected.

Furthermore, daily limits for Basic Access developer tokens are different in the Google Ads API than in the AdWords API. They have been set to accommodate the new GoogleAdsService, which is the unified object retrieval and reporting service. Developer tokens with Basic Access can issue 15,000 requests per day. GoogleAdsService.Search requests with the page_token field set, will not count towards the Basic Access limit.

Note: All developer tokens are subject to the daily limit of 1,000 get requests.

Required Minimum Functionality (RMF)
Standard Access tools will continue to be subject to RMF policies. As these tools migrate their functionalities off of the legacy API, they can achieve RMF compliance by using either the AdWords API, Google Ads API or a combination of the two. Required features that are available in both APIs will be documented on both developer sites.

The Google Ads API RMF guide will contain the most up to date RMF list. This list will be made up of RMF items available in the AdWords API as well as new required functionalities that will be made available only in the Google Ads API. RMF due dates for new features will take into account migration efforts from the AdWords API to the Google Ads API.

Resources
For more information on these policy updates, please take a look at the following Google Ads API resources:

If you have any questions or need help, please contact us via the forum.
--Google Ads API Team

AdWords API v201806 sunset reminder

2019-03-05T08:31:00.000-08:00

AdWords API v201806 will be sunset on April 2, 2019. After this date, all v201806 API requests will begin to fail. You have the option of migrating directly to Google Ads API v1, which is ready for your production systems. If you’re not ready for the v1 migration, then please migrate to v201809 prior to April 2, 2019 to ensure your API access is unaffected.

We've prepared various resources to help you with the migration:

If you have questions while you’re upgrading, please reach out to us on the forum.
Nadine Sundquist, Google Ads API Team

Upgrade to the new Google Ads API to get the latest services

2019-03-04T11:16:00.000-08:00

Today we’re announcing the production-ready release of the Google Ads API. You should start using v1 in your production systems as we are now out of beta. The v0 beta version of Google Ads API will sunset on April 30, 2019. After this date, all v0 requests will begin to fail. You’ll be pointing to a new v1 endpoint which is different from the v0 endpoint. Please update your client libraries to use the v1 endpoint.

What is the Google Ads API?
The Google Ads API is the replacement of our AdWords API and brings significant advances in innovation and developer productivity. It can be accessed via gRPC with our client libraries and JSON REST for debugging. We are working on getting the last few features released so that all the features in the AdWords API also exist in the Google Ads API. In addition, new features are being added to the Google Ads API that will not be available in the AdWords API.

Google Ads Query Language makes querying more flexible.
Querying returns objects that can immediately be updated in the API.
Coding becomes easier as interacting with lists is more intuitive.
Querying and managing budgets is available to everyone for accounts using consolidated billing.
You can query, apply, and dismiss Recommendations.
Most resources can be mutated synchronously through a single service.
Querying change status in the API is more detailed.

How do I get started?
For existing AdWords API developers:

Use your existing developer token from the AdWords API.
Important: The Terms and Conditions have changed. You’ll need to accept the updated Terms and Conditions and update your contact information in API center. If you don’t, you will get an error when trying to access v1.
- Sign into the API Center of the manager account where you have your developer token at ads.google.com/aw/apicenter.
- Scroll down to API contact email, and update it.
- Scroll down to Principal place of business, accept the new conditions, and click Save.

For new API developers, sign up for a developer token.

Everyone should go through our Quickstart guide to enable Google Ads API and retrieve the newest client libraries.

What resources are available?
Check out these helpful resources:

The updated client libraries and code examples will be published by March 6, 2019. If you have any questions or need help, please contact us via the forum.

--Google Ads API Team

Change to the Google Ads API and the AdWords API Showcase Ads Clicks Reporting

2019-02-21T09:15:00.000-08:00

Update (Feb 21, 2019): clarified wording of the Clicks impact.
On February 27, 2019, the data returned in the Clicks metric for Showcase ads will change in order to more accurately show you the interactions with products via Showcase ads in reporting.

In the AdWords API and the Google Ads API, the Clicks metric (clicks for Google Ads API) will change for the Shopping Performance Report and the Product Partition Report (product_group_view for Google Ads API) as follows:

Current reporting: Clicks only include charged clicks.
New reporting: Clicks will report all clicks, including free clicks. As a result, you may see a change in the number of reported clicks.

If you have questions, please reach out to us on the forum.
Nadine Sundquist, Google Ads API Team

Changes to responsive ads in the AdWords API and Google Ads API

2019-02-20T10:53:00.000-08:00

What's changing?
Starting May 15, 2019, AdWords API and Google Ads API requests that attempt to create or modify a responsive ad will fail. Make sure you migrate to the new asset-based responsive display ad before the deprecation date.

Due to changes and improvements to ad types in Display campaigns, keeping track of the names in the UI and APIs can be tricky, so here's a quick overview:

Ad type in the UI	AdWords API type	Google Ads API type
Responsive ad	ResponsiveDisplayAd	ResponsiveDisplayAdInfo
Responsive display ad	MultiAssetResponsiveDisplayAd	Available in an upcoming release

After the deprecation date, behavior of the APIs will change as follows:

AdWords API
- AdGroupAdService requests that attempt to create a ResponsiveDisplayAd will fail with the error AdGroupAdError.CANNOT_CREATE_DEPRECATED_ADS. The API will continue to allow you to remove ResponsiveDisplayAds and modify the status of existing ads.
- AdService requests that attempt to modify a ResponsiveDisplayAd will fail with the error AdError.CANNOT_MODIFY_AD.
Google Ads API
- AdGroupAdService requests that attempt to create a ResponsiveDisplayAdInfo will fail with the error AdGroupAdError.CANNOT_CREATE_DEPRECATED_ADS. The API will continue to allow you to remove ResponsiveDisplayAdInfos and modify the status of existing ads.

Both APIs will continue to return performance statistics for the deprecated ad types.

Why is this happening?
In October, 2018, responsive display ads replaced responsive ads as the default asset-based ad type for the Display network. To simplify the product suite, we'll be deprecating creation and modification of responsive ads.

What should you do?
Before the deprecation date:

If you use the AdWords API, modify your code to use MultiAssetResponsiveDisplayAd wherever you currently use ResponsiveDisplayAd. Check out the guide and accompanying code example in the .NET, Java, Python, or Ruby client library to help you with the migration.
If you use the Google Ads API, modify your code to no longer use ResponsiveDisplayAdInfo, and keep an eye on this blog so you'll know when the equivalent to MultiAssetResponsiveDisplayAd becomes available in the Google Ads API.

If you have any questions or need help, please contact us via the forum.
- Josh Radcliff, Google Ads API Team

Upgrade Dynamic Search Ads in AdWords API and Google Ads API by March 6, 2019

2019-02-13T10:17:00.002-08:00

Upgrade your AdWords API and Google Ads API ads to use ExpandedDynamicSearchAd (EXPANDED_DYNAMIC_SEARCH_AD) instead of DynamicSearchAd (DYNAMIC_SEARCH_AD) by March 6, 2019. After March 6th, creating these ads through the APIs will fail with an AdGroupAdError.CANNOT_CREATE_DEPRECATED_ADS error, while updating them will result in an AdError.CANNOT_MODIFY_AD error. Existing DynamicSearchAds will continue to serve.

For AdWords API, upgrade DynamicSearchAd to ExpandedDynamicSearchAd.
For Google Ads API, upgrade DynamicSearchAdInfo to ExpandedDynamicSearchAdInfo.

An ExpandedDynamicSearchAd goes beyond automating just headlines and adds the advantage of automating display URLs, so that the subdomain of your ad matches the subdomain of your landing page. In addition, Google Ads will add a path when it expects the path to outperform a plain URL. In order to increase the performance for all our advertisers, Google Ads is moving everyone to the newer format.

If you have any questions while upgrading, please reach out to us on our forum.
Nadine Sundquist, Google Ads API Team

Subscribe to our RSS feed to get blog posts via email

2019-02-08T09:31:00.000-08:00

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

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

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

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

- Mike Cloonan, Ads Developer Relations Team

Register now for the upcoming Google Ads API Workshops!

2019-02-05T07:53:00.001-08:00

We're excited to announce that a new series of Google Ads API Workshops are coming this March and April! The technical sessions focus on migration from the current AdWords API so you can migrate quickly and efficiently. New users are welcome and will benefit as well.

The workshops will be presented in English, except for those in Taipei, Tokyo, and Shanghai. Details are listed below. Note that location names link to the registration websites:

New York - March 6, 2019
Munich - March 7, 2019
San Francisco - March 20, 2019
London - March 25, 2019
Taipei - April 1, 2019 (Chinese)
Tokyo - April 8, 2019 (Japanese)
Sydney - April 17, 2019
Shanghai - April 23, 2019 (Chinese)

Workshops in all locations will cover the same topics, so choose a location that works best for you. Once you register, we'll send you an email confirmation.

Stay tuned for more detailed agenda on the workshop websites!

If you have any questions about the workshops, you can post them on our forum.
- Thanet Knack Praneenararat, Google Ads API Team

Creating Smart Shopping campaigns with the local inventory ads setting enabled will be rejected

2019-01-31T08:55:00.000-08:00

Starting Feb 15, 2019, in all AdWords API versions and in the Google Ads API, we’re going to reject requests that attempt to create a Smart Shopping campaign with the local inventory ads setting enabled. The local inventory ads setting is equivalent to setting enableLocal to true in the AdWords API, and enable_local to true in the Google Ads API. Trying to set those fields to true when creating a Smart Shopping campaign will result in the OperationAccessDenied.OPERATION_NOT_PERMITTED_FOR_CAMPAIGN_TYPE error. Previously, those fields were ignored when passed to the API servers.

Why is this happening?
Throwing an error for the requests described above provides an alert to users that local inventory ads are not supported in Smart Shopping campaigns.

What should you do?
Make sure you do not have code that creates a Smart Shopping campaign with local inventory ads enabled. Specifically, when you create a ShoppingSetting object for a Smart Shopping campaign, take either of the following actions:

(Preferable) Do not set enableLocal (AdWords API) or enable_local (Google Ads API) at all
Set enableLocal (AdWords API) or enable_local (Google Ads API) to false

Follow the guides below for details on how to create a Smart Shopping campaign:

As always, if you have any questions or concerns, please post them on our forum.
- Thanet Praneenararat, Google Ads API Team

Announcing v0_7 of the Google Ads API

2019-01-30T13:21:00.000-08:00

Today we’re announcing the beta release of the Google Ads API v0_7. With this version, you’ll continue pointing to v0 as your endpoint; however, you'll need to update your client libraries. Here are the highlights:

Request Parameters. These parameters give you the ability to change how a request is processed.
- Set validate_only to true as a request parameter to only validate the request, but not perform it. This was added to all services including GoogleAdsService.Mutate().
- Set partial_failure to true as a mutate parameter to continue on failure and commit valid operations even if other operations in the same request failed.
Reporting. All segment fields are now in a segments, which means all queries must be updated to include segments. before the segment field name.
Manager accounts. We've added support for mutating your customer hierarchy with CustomerManagerLink and CustomerClientLink.
Client accounts. We’ve introduced fields to identify if a customer is a test account or a manager account. The conversion tracking settings of a customer are now available.
Ad formats. We’ve added support for managing ad parameters with the AdParameterService.
Audiences. The targeting setting in campaigns and ad groups is now available. We’ve added support for rule-based, logical, and basic user lists. You can now manage remarketing actions for a basic user list.
Criteria types. Creating criteria with CriterionType MOBILE_APP_CATEGORY, WEBPAGE, OPERATING_SYSTEM_VERSION, and APP_PAYMENT_MODEL is now possible.

To get started with the API, review these helpful resources:

The updated client libraries and code examples will be published within the next 2 business days. If you have any questions or need help, please contact us via the forum.
Nadine Sundquist, on behalf of the Google Ads API Team

Updating the minimum required PHP version for the Google Ads API client library for PHP (AdWords and Ad Manager)

2019-01-25T08:14:00.000-08:00

Starting March 2019, the composer file of all releases of the Google Ads API client library for PHP (AdWords and Ad Manager) will require PHP version 7.1 or later. The latest major version of the client library (v39.0.0) will be the last release that supports PHP 5, with the minimum required PHP version of 5.6. We’ll still fix critical bugs for this major version, but no new features will be added to it in the future.

PHP 5.6 and 7.0 were sunset at the end of 2018. The PHP development team no longer provides security fixes for these versions, so we highly recommend migrating to the latest version (7.3) if possible.

You can see some useful resources below:

As always, if you have any questions, feel free to drop us a line on the Google Ads API or Google Ad Manager API forums.
- Thanet Knack Praneenararat, Google Ads API Team

Configure Account-level Call Reporting

2019-01-14T08:33:00.001-08:00

In October 2018, we introduced the ability to configure account-level call reporting in the Google Ads UI. If a user has set account-level call reporting in their Google Ads account:

All values in CallOnlyAd.callTracked and CallFeedItem.callTracking are ignored.
All CallOnlyAds and CallFeedItems use the account-level setting.
All values for CallOnlyAd.conversionTypeId, CallOnlyAd.disableCallConversion, CallFeedItem.callConversionType, and CallFeedItem.disableCallConversionTracking are still used.

If your values are being ignored in the API, then your user may have decided to go to the Google Ads UI to enable account-level call reporting.

If you have questions, please reach out to us on the forum.
Nadine Sundquist, AdWords API Team

Recap of the latest Google Ads API webinar

2018-12-18T08:08:00.001-08:00

A huge thank you to the 300+ viewers from 44 different countries who joined recent Google Ads API: Roadmap and migration webinar on Tuesday, Dec 11. Also, a special mention to the great YouTube chat group in the second webinar who helped us sort out some technical issues at the start of the live stream!

We had tons of good questions to answer in the Q&A and hope the event proved helpful to everyone.

For those who couldn’t attend the live stream and anyone wanting a copy of the presentation, we’ve provided links to both the slide deck and YouTube recording of the 9am (GMT+8) webinar:

Webinar Video (Dec 11, 2018) [1 hr, 10 mins]
Slides

Please visit the Google Ads API developer site for technical docs, migration guides, or to give feedback.

And, as always, don’t hesitate to contact us via the forum if you have any questions.
Adam Ohren, on behalf of the Google Ads API Team

AdWords API v201802 sunset reminder

2018-12-17T08:30:00.000-08:00

AdWords API v201802 will be sunset on January 30, 2019. After this date, all v201802 API requests will begin to fail. We recommend that you skip v201806 and migrate directly to v201809. Please migrate prior to January 30, 2019 to ensure your API access is unaffected.

We've prepared various resources to help you with the migration:

If you have questions while you’re upgrading, please reach out to us on the forum.
Nadine Sundquist, Google Ads API Team

Connected TV Device Targeting, Reporting, & Management

2018-12-12T10:11:00.003-08:00

Starting on Jan 8, 2019 you will be able to target and generate reports for a new device category via the AdWords API - connected TV. The connected TV platform, (or “TV screens,” as it’s referred to in the new Google Ads experience), is a new Platform type similar to desktop, tablet, and mobile. It targets devices such as smart TVs, gaming consoles and standalone connected devices including Chromecast, Roku, and AppleTV.

Since connected TV shares the same functionality as the three existing platforms, you can target or exclude it using bid modifiers for Display/Video ad campaigns; the new criterion will have a platformName of “ConnectedTv” and an ID of 30004. You can also isolate it in reports using a Device segment named CONNECTED_TV. Note that even though bidding will only be supported for Display and Video ads, some residual traffic may appear in other kinds of reports so you should still pull the new segment for non Display/Video ad reports.

The new connected TV device segment will be available anywhere Device-level or Device-segmented reporting is available. Currently any reporting data related to this platform is consolidated under the Desktop platform.

For more background on device targeting see the Help Center.

If you have questions, please reach out to us on the AdWords API forum.
Ben Karl, AdWords API Team

Announcing v0_6 of the Google Ads API

2018-11-29T13:21:00.000-08:00

Updated on Nov 30: Added highlight for Billing.Today we’re announcing the beta release of Google Ads API v0_6. This release brings you the features listed in Required Minimum Functionality (RMF). Now that the core functionality of this new API is available, you should get started planning, designing, and coding against it. With this version, you’ll continue pointing to v0 as your endpoint, however, you'll need to update your client libraries. Here are the highlights:

Manager account authentication: If you’re authenticating as a manager account, the manager account you want for authorization must be in the header as login-customer-id. You then set the customer you want to interact with in the request as usual. This tells the API the level of manager account hierarchy you want to authenticate with.
Mix mutate operations: Pass in multiple kinds of operations with GoogleAdsService.Mutate.
Billing: A new service is available to manage billing. The read-only PaymentsAccountService allows you to view a list of all payment accounts. Refer to the BillingSetupService to designate a payment account for a billing setup.
Hotel Ads: We extended the GoogleAdsService to enable users to query hotel performance metrics that were previously available in the Travel Partner API with the HotelPerformanceView. Supported performance metrics are cost, clicks, impressions, and average lead values. Some derived metrics are also precomputed: average position, average cost per click, average cost per thousand impressions, and click-through rate. These metrics can be segmented by:
- Itinerary segments: check-in date, check-in day of week, booking window days, and date selection type
- Hotel segments: hotel center ID, hotel ID, class, city, state, and country
- Date segments: hour, date, day of week, week, month, quarter, and year
- Others: campaign, ad group, ad network, and device
Feeds: Manage and retrieve feeds with AdGroupFeedService, CustomerFeedService, FeedService, CampaignFeedService, and FeedMappingService.
Account management:
- We introduced CustomerClient, which provides the ability to get an expanded hierarchy of customer clients (both direct and indirect) for a given manager customer.
- This release also supports the creation of new customer clients under a manager using the CustomerService.CreateCustomerClient method.
- CustomerService now supports mutates.
Recommendations: Added the DismissRecommendation method to the RecommendationService, making it possible to dismiss the recommendations listed in our guide.
Ad formats: Gmail ads and image ads are now supported.
Search query reporting: The SearchTermView resource is now available, providing metrics aggregated at the search term level. SearchTermView provides functionality similar to the Search Query Performance Report of the AdWords API.
Audiences: Create audiences using UserListService.
Criteria types: You can now create criteria with CriterionType LANGUAGE, CARRIER, USER_LIST, USER_INTEREST and IP_BLOCK.

To get started with the API, review these helpful resources:

Smart Shopping campaigns are publicly available today

2018-11-27T09:39:00.000-08:00

Smart Shopping campaigns were released in AdWords API v201802 to whitelisted advertisers. Today, we’re releasing them to all developers in both the AdWords API and Google Ads API.

Smart Shopping campaigns combine automation and machine learning to maximize your conversion value across networks based on your budget. For end-to-end instructions in creating Smart Shopping campaigns, ad groups, and ads, visit our docs: AdWords API guide or Google Ads API guide.

For optimal performance, we recommend you have at least 20 conversions over the last 45 days across existing Shopping campaigns before creating a Smart Shopping campaign.

As always, if you have any questions or concerns, please post them on our forum.
- Thanet Praneenararat, Google Ads API Team

Update to Customer Match Requirements

2018-11-16T08:43:00.001-08:00

We announced an update to Customer Match requirements in October 2018 that affects member uploads and the usage of Customer Match for campaigns on Search, YouTube, and Gmail.

Creating a CrmBasedUserList through AdWordsUserListService now requires whitelisting. If the account is not whitelisted, your request returns an ADVERTISER_NOT_WHITELISTED_FOR_USING_UPLOADED_DATA error.
Uploading members to a CrmBasedUserList results in a CAN_NOT_MUTATE_SENSITIVE_USERLIST error if the account is not whitelisted.
Targeting CrmBasedUserLists in accounts that are not whitelisted using CampaignCriterionService or AdGroupCriterionService results in an INVALID_ID error.
Serving campaigns can be affected if they are using Customer Match and the account is not whitelisted. If a campaign is only targeting Customer Match, then the campaign stops serving. If the campaign has other audiences, then the campaign continues to serve with the other audiences.

Please see the requirements for whitelist eligibility. To apply for the whitelist, reach out to your account manager. Once whitelisted, Customer Match no longer results in errors and serves normally without any further changes needed.

If you have questions, please reach out to us on the AdWords API forum.

Nadine Sundquist, AdWords API Team

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

2018-11-07T12:47:00.000-08:00

What's new
Starting November 12, 2018, the fields below will be available in AdWords API and Google Ads scripts reports.

Absolute top metrics:

AbsoluteTopImpressionPercentage
SearchAbsoluteTopImpressionShare
SearchBudgetLostAbsoluteTopImpressionShare
SearchRankLostAbsoluteTopImpressionShare

Top metrics:

TopImpressionPercentage
SearchTopImpressionShare
SearchBudgetLostTopImpressionShare
SearchRankLostTopImpressionShare

AbsoluteTopImpressionPercentage and TopImpressionPercentage are specific indicators of page location. You can use these metrics to determine when and where your impressions are showing above the organic search results.

SearchAbsoluteTopImpressionShare and SearchTopImpressionShare are your share of the eligible top impressions. They are the best indicators of the headroom available to show your ads in more prominent positions. If your goal is to bid on page location, you should use these metrics. Bidding by average position is not recommended since:

Average position doesn't actually describe position on the page but position in the auction.
Sometimes, average position may decrease as bids increase. This happens as higher bids sometimes allow you to enter more competitive auctions lower on the page.

See our post on the New features & announcements page for more details.

What you should do
Whenever you are using AveragePosition as a proxy to bid to a page location, switch to using the new SearchAbsoluteTopImpressionShare or SearchTopImpressionShare metrics in your bidding logic.

If you have any questions or need help, please contact us via the forum.
- Josh Radcliff, AdWords API Team

Announcing v0_5 of the Google Ads API

2018-10-31T14:10:00.000-07:00

Today we’re announcing the beta release of Google Ads API v0_5. With this version, you’ll continue pointing to v0 as your endpoint, however, you'll need to update your client libraries. Here are the highlights:

Billing. Multiple services are available for managing billing.
- BillingSetupService
  - Create a new billing setup
  - Cancel an approved billing setup that is scheduled to start in the future
  - Cancel a pending billing setup that is not yet approved
- AccountBudgetService
  - View all approved account-level budgets, including budget adjustments
  - View currently pending account-level budget proposals (if any)
- AccountBudgetProposalService
  - Create account-level budget proposal to update a budget or create a new budget
  - View all account-level budget proposals. All approved values and proposed budget values are visible. Approved values will be exposed as fields prefixed with approved_.
Conversion tracking. Conversion tracking lets you measure the performance of your advertising against your business goals.
- Conversion actions - Set up and edit the settings associated with your conversion actions, including website tracking and call-conversion tracking
Shopping. The ProductGroupView resource provides Shopping campaign statistics aggregated at the product group level (also called listing group in the Google Ads API). Results always reflect the current set of product groups. An impression for a product will be attributed to all product groups that contain the product. ProductGroupView provides features equivalent to the Product Partition Report of AdWords API.
Location and Demographics. You can now create criteria with CriterionType AGE_RANGE, GENDER, INCOME_RANGE, PARENTAL_STATUS, PLACEMENT, PROXIMITY, TOPIC, YOUTUBE_CHANNEL, and YOUTUBE_VIDEO. The GeoTargetConstantService lets you input locations and receive suggested geos.
Account Management. CustomerService.ListAccessibleCustomers provides the capability to manage Google Ads accounts.

To get started with the API, review these helpful resources:

The updated client libraries and code examples will be published within the next 48 hours. If you have any questions or need help, please contact us via the forum.
Nadine Sundquist, on behalf of the Google Ads API Team

Share your feedback about the AdWords API and Google Ads API

2018-10-19T07:40:00.000-07:00

Since the early days of the AdWords API, we've continually evolved the platform to help you more efficiently and creatively manage large or complex Google Ads accounts and campaigns. This year, we’ve also announced the Google Ads API Beta, which was rebuilt to stay on the edge with advancements in our advertising platform.

To learn more about what's working well, and what could be improved, we're running our annual developer feedback survey on both the AdWords API and Google Ads API. Your answers will be completely anonymous, so we hope you'll take the opportunity to leave feedback on how we can make managing campaigns even easier.

SHARE YOUR FEEDBACK

The survey should take about 15 minutes to complete, and will close on November 15, 2018. Thank you in advance for helping us continue to improve developer experience for everyone.
Cory Liseno, Google Ads API Team

Changes to the URL Performance Report for YouTube video placements

2018-10-17T14:07:00.000-07:00

What's changing?
The URL_PERFORMANCE_REPORT in the AdWords API will exclude information for YouTube video placements starting October 30, 2018, in keeping with our data retention policies. As a result, placements where the Url field has a domain of www.youtube.com will no longer appear in the report. New and improved placement reports will be available in one of the upcoming releases of the new Google Ads API.

What you should do
Review your application and workflows and make the necessary changes to ensure that the exclusion of video placements in this report will not cause problems. Watch this blog for updates regarding new placement reports in the Google Ads API.

If you have any questions or need help, please contact us via the forum.

- Josh Radcliff, AdWords API Team

Announcing v0_4 of the Google Ads API

2018-09-24T10:50:00.000-07:00

Today we’re announcing the beta release of Google Ads API v0_4. With minor versions like this one, you’ll continue to point to v0 as your endpoint, but you will need to update your client libraries to use the new features. Here are the highlights:

Whitelist Removed. The whitelist has been removed for the Beta. All API users with an existing developer token in the AdWords API are now able to use the Google Ads API.
Billing. BillingSetupService and AccountBudgetProposalService introduce the ability to set up billing. Please note, this does not provide the ability to fully set up account budgets yet. See the release notes for details.
Campaigns.

Retrieve the AdGroupAdPolicySummary to determine why an ad has been disapproved.

Change History.

We’ve introduced ChangeStatus, allowing you to find the current status of changed resources in your account.
The six supported resources are:

AD_GROUP
AD_GROUP_AD
AD_GROUP_CRITERION
CAMPAIGN
CAMPAIGN_CRITERION

Search for changed resources using GoogleAdsService.Search.

Conversion tracking. Conversion tracking lets you measure the performance of your advertising against your business goals. The API allows you to set up and edit your conversion tracking setup. With ConversionActions, you can set up and edit the settings associated with your conversion actions supporting:

AD_CALL
CLICK_TO_CALL
GOOGLE_PLAY_DOWNLOAD
GOOGLE_PLAY_IN_APP_PURCHASE
UPLOAD_CALLS
UPLOAD_CLICKS
WEBPAGE
WEBSITE_CALL

Shopping. Shopping campaigns help you promote your online and local inventory, boost traffic to your website or local store, and find better qualified leads.

This release supports the creation of standard Shopping campaigns with Shopping Product Ads. Portfolio and campaign-local bidding strategies are supported types MANUAL_CPC, ENHANCED_CPC, TARGET_SPEND, TARGET_ROAS. Product offers can be subdivided into groups using the ListingGroupInfo criterion (equivalent to Product Groups in the Google Ads user interface), which currently supports the following dimension types: Product Condition, Product Type, Listing Brand, Listing Custom Attribute (L0-4), Product Channel, Product Channel Exclusivity, Product Offer Id.

Video.

Retrieve information about your video campaigns from GoogleAdsService.Search, which includes video-specific metrics including video views, video view rate, video quartiles, and view-through conversions.

Ruby client library. When upgrading your client library, please look at the ChangeLog as the require path and namespace have changed in this version.

To get started with the API, our team has put together these resources:

The updated client libraries and code examples will be published within the next 48 hours. If you have any questions or need help, please contact us via the forum.

Nadine Sundquist, on behalf of the Google Ads API Team