Google Ads Developer Blog

Adding New Resource Types to ChangeStatus in Google Ads API

2021-04-22T06:37:00.000-07:00

We're hard at work in bringing some new resource types to the change_status report. Some planned future improvements include changes to shared sets and assets. While these types will be fully supported in future versions of the Google Ads API, the infrastructure changes we're making to support them will have some effects on existing versions as well.

When we add support for new resource types, you will be able to fetch the new rows in all versions of the API, with the resource_type returning as UNKNOWN in already released versions. In some specific instances, rows that previously had a known resource_type, such as CAMPAIGN, may start returning a resource type of UNKNOWN. This will occur if, for example, a change that was previously reported as a CAMPAIGN change was actually a CAMPAIGN_ASSET change all along. The future version of the API will know about the CAMPAIGN_ASSET resource type, but existing versions do not, so we must use UNKNOWN. This row will also have a new resource_name associated with it, which now includes the asset's ID as well.

The new resource name for the row will include an identifier that tells what kind of change it is. We will keep an updated list of these identifiers on the change status guide. This lookup will only be necessary for rows with an UNKNOWN resource type, and corresponds to the resource type that would be returned from the future API version when that resource type is fully supported.

We are planning multiple new resource types for this report, so please expect UNKNOWN types to appear for various new resource types. Rest assured that when you see this, it's because an upcoming release will have a newly supported resource type for the change_status report. We won't make any changes until at least May 24, 2021, so you have time to ensure that your code can handle UNKNOWN resource type rows.

If you have any questions, please leave a post on our forum so that we can help.
- Mike Cloonan, Google Ads API Team

The Query Builder Blog Series: Part 3 - Creating a Resource Schema

2021-04-19T08:52:00.003-07:00

This blog series follows the journey of building the new and improved Interactive Google Ads Query Builder. Part 2 of this series described the design of the detailed JSON resource schema that will serve as the canonical data set for the Interactive Query Builder Angular application. Part 3 will focus on how we can use the GoogleAdsFieldService to create that schema.

Retrieving the data

We can retrieve most of the data for the schema described in Part 2 by making an API call to the GoogleAdsFieldService with the following query:

SELECT name, category, data_type, selectable, filterable, sortable, selectable_with, metrics, segments, is_repeated, type_url, enum_values, attribute_resources

The result contains an array of JSON objects for every field available in the Google Ads API. Each object in the array will contain the fields in the SELECT clause above. For example, the ad_group list item would look like this:


{
      "resourceName": "googleAdsFields/ad_group",
      "name": "ad_group",
      "category": "RESOURCE",
      "dataType": "MESSAGE",
      "selectable": false,
      "filterable": false,
      "sortable": false,
      "selectableWith": [...],
      "metrics": [...],
      "segments": [...],
      "isRepeated": false,
      "typeUrl": "com.google.ads.googleads.v6.resources.AdGroup",
      "enumValues": [],
      "attributeResources": [...]
}

We’ll restructure this into key-value pairs, where the keys are the entity names and the values are the metadata for each entity, making it easier to lookup the metadata for a given entity. For example, the ad_group entry would look like this:


{
    "ad_group": {
      "resourceName": "googleAdsFields/ad_group",
      "name": "ad_group",
      "category": "RESOURCE",
      "dataType": "MESSAGE",
      "selectable": false,
      "filterable": false,
      "sortable": false,
      "selectableWith": [...],
      "metrics": [...],
      "segments": [...],
      "isRepeated": false,
      "typeUrl": "com.google.ads.googleads.v6.resources.AdGroup",
      "enumValues": [],
      "attributeResources": [...]
}

As compared with the schema we designed in Part 2, this restructured object is missing several fields, which we’ll add in the following sections: attributes, fields, description, and display name.

Attributes

If you recall from the schema design, each resource should contain an array named attributes which contains the names of all fields present on the resource itself and any attributed resources. We can create this array by iterating through the results of our GoogleAdsFieldService query and adding the name of entries beginning with either our resource or one of its attributed resources, followed by a dot.

Fields

The fields entry in our schema is an object with an entry for each (a) item in the attributes array we just created, (b) metric on the resource, and (c) segment on the resource. The value of each entry will be each respective field’s value in the object we created earlier. However, we still need to add an incompatible_fields array to each field.

To construct the incompatible_fields array for each entry in our fields object, we’ll check to see if each of the fields, metrics, and segments present on the top level object is selectable_with the given field being evaluated. If not, we’ll add that field, metric, or segment to the incompatible_fields array.

Descriptions

Next, we need to add descriptions to each top level resource and item in its fields entry. It is important to note that a field may have a different description depending on the top level resource. For example, the description of ad_group.id is “Output only. The ID of the ad group.” but the description of campaign.id is “Output only. The ID of the campaign.” The REST discovery docs contain nested descriptions that we can use to create a canonical descriptions object, which we’ll use to populate our schema. This step entails parsing and formatting, the details of which we will not discuss here. We just want you to know that the REST discovery docs exist in case you ever need them. This is currently the best solution available, although it would be easier if the descriptions were returned from the GoogleAdsFieldService.

Display names

All that is left to do is populate the display names field in our resource schema. We can do this by simply replacing underscores with spaces and capitalizing the first letter of each word in the name.

Filtering for resources

Our resource schema is now fully populated. However, it contains every resource, field, segment, and metric returned from our GoogleAdsFieldService query. We can filter this schema to include only items with a category of RESOURCE.

Conclusion

We have now created an expanded resource schema containing detailed field information and a list of incompatible fields for each field, which we can use in our Angular application. In this post, we’ve covered:

How to use the GoogleAdsFieldService to retrieve field metadata.
Field compatibility in GAQL.
The REST discovery API.

Hopefully this has deepened your understanding of what is possible with the Google Ads API. If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.

- Devin Chasanoff, on behalf of the Google Ads API Team

The Query Builder Blog Series: Part 2 - Designing a Resource Schema

2021-04-12T09:12:00.000-07:00

This blog series follows the journey of building the recently released Interactive Google Ads Query Builder tool. Part 1 of this series outlined what we’ll be covering in the series as well as the rationale behind publishing this content. Part 2 will focus on designing a detailed JSON resource schema that will serve as the canonical data set for the Interactive Query Builder Angular application.

Background

As mentioned in Part 1, one of the major benefits of the new Interactive Query Builder is that it provides real-time feedback detailing why fields may or may not be selectable in a given clause of a Google Ads Query Language (GAQL) query.

For example, let’s say you are constructing a GAQL query with ad_group as the main resource in the FROM clause. Both segments.conversion_action and metrics.absolute_top_impression_percentage are selectable on the ad_group resource. However, taking a look at the detailed reference documentation for segments.conversion_action, we can see that there is a list of “Selectable With” fields, and that list does not include metrics.absolute_top_impression_percentage. Therefore, those two fields are incompatible. Regardless of what resource is in the FROM clause, if one of those two fields is present in the query, we know that the other cannot be. That is why metrics.absolute_top_impression_percentage is no longer selectable in the Interactive Query Builder once segments.conversion_action is selected.

Rather than trying to piece together all of this logic at runtime with various back-and-forth server calls, we thought it would be beneficial to feed that data into the application with static JSON files containing the resource schema. What might that optimal schema look like?

Schema Design (definition at the end of the blog post)

A GAQL string requires a single resource in the FROM clause. Given that constraint, the top level JSON schema will be a map from resources to detailed schemas for each resource. For example, the ad_group entry in our schema will look like this:


{

    "ad_group": {

        "name": "ad_group",
        "display_name": "Ad Group",
        "description": "An ad group.",
       // Array of all attribute and attributed resource fields.
        "attributes": [
            "ad_group.ad_rotation_mode",
            "ad_group.base_ad_group",
            "ad_group.campaign",
            ...
            "campaign.ad_serving_optimization_status",
            "campaign.advertising_channel_sub_type",
            "campaign.advertising_channel_type",
            ...
            "customer.auto_tagging_enabled",
            "customer.call_reporting_setting.call_conversion_action",
            "customer.call_reporting_setting.call_conversion_reporting_enabled",
            ...     
        ],
        // Array of all metrics selectable with ad_group.
        "metrics": [...],
        // Array of all segments selectable with ad_group.
        "segments": [...],
       // Expanded info for all items listed in attributes, metrics, and segments arrays.
        "fields": {...}

}

The crux of this enhanced schema is the fields entry. The keys of this object will be all of the attributes, metrics, and segments of the top level resource (e.g. ad_group). The value of each item in this object will be objects containing detailed information about that given field, as well as an additional field called incompatible_fields, an array of the fields that are incompatible with the given field. For example, the metrics.phone_impressions entry of the fields object would look like this:



            "metrics.phone_impressions": {
                "field_details": {
                    "name": "metrics.phone_impressions",
                    "category": "METRIC",
                    "selectable": true,
                    "filterable": true,
                    "sortable": true,
                    "data_type": "INT64",
                    "is_repeated": false,
                    "type_url": "",
                    "description": "Number of offline phone impressions.",
                    "enum_values": [],
                    "selectable_with": [
                        "ad_group",
                        "ad_group_ad",
                        "campaign",
                        "customer",
                        "extension_feed_item",
                        "segments.ad_network_type",
                        "segments.click_type",
                        "segments.date",
                        "segments.day_of_week",
                        "segments.interaction_on_this_extension",
                        "segments.keyword.ad_group_criterion",
                        "segments.keyword.info.match_type",
                        "segments.keyword.info.text",
                        "segments.month",
                        "segments.month_of_year",
                        "segments.quarter",
                        "segments.week",
                        "segments.year"
                    ]
                },
                "incompatible_fields": [
                    "segments.slot",
                    "segments.device",
                    "segments.external_conversion_source",
                    "segments.conversion_action_category",
                    "segments.conversion_lag_bucket",
                    "segments.hour",
                    "segments.conversion_action_name",
                    "segments.conversion_action",
                    "segments.conversion_adjustment",
                    "segments.conversion_or_adjustment_lag_bucket"
                ]
            },

The recursive nature of the schema may seem somewhat redundant, as some fields will appear in multiple resources. However, we will ultimately divide this main schema into individual JSON files for each resource to decrease load times, and we will only retrieve a single resource-specific schema depending on the resource in the FROM clause.

Schema Definition

For reference, the full schema definition is below:


interface ResourceSchema {
  name: string; // the name of the resource
  display_name: string; // the display name of the resource
  description: string; // the description of the resource
  attributes: string[]; // the resource's fields (including attributed resource fields)
  metrics: string[]; // available metrics when the resource is in the FROM clause
  segments: string[]; // available segments when the resource is in the FROM clause
  fields: { // detailed info about all fields, metrics, and segments
    [key: string]: {
        field_details: FieldDetails; // details about the field (defined below)
        incompatible_fields: string[]; // fields that are incompatible with the current field
    }
  };
}

interface FieldDetails {
  name: string; // the name of the field
  category: string; // the field's category (e.g. ATTRIBUTE, METRIC, SEGMENT)
  selectable: boolean; // whether or not the field is allowed to be placed in the SELECT clause
  filterable: boolean; // whether or not the field is allowed to be placed in the WHERE clause
  sortable: boolean; // whether or not the field is allowed to be placed in the ORDER BY clause
  data_type: string; // the field's data type
  is_repeated: boolean; // whether or not the field is a repeated field
  type_url: string; // the field's type_url
  description: string; // the field's description
  enum_values: string[]; // possible enum values if the field is of type ENUM
  selectable_with: string[]; // the list of field the current field is selectable with
}

Conclusion

With that, we now have designed an expanded resource schema containing detailed field information and a list of incompatible fields for each field, which we can use in our Angular application. In part 3, we’ll discuss how to create this schema using the GoogleAdsFieldService.
Hopefully this has deepened your understanding of and shown you what is possible with the Google Ads API. If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
- Devin Chasanoff, on behalf of the Google Ads API Team

The Query Builder Blog Series: Part 1 - Setting the Stage

2021-04-02T09:32:00.000-07:00

An important part of our role in Developer Relations is gathering your feedback, as developers using our APIs, so that we can improve products and create tools that will make for a better developer experience. This is particularly important now because the Google Ads API is now out of Beta. We have received several important pieces of feedback as it relates to the Google Ads Query Language (GAQL) and constructing GAQL queries. Specifically, we’ve learned that

GAQL is a powerful and flexible mechanism for retrieving data from the Google Ads API. In order to get the most out of it and construct queries efficiently, it is important to understand the details and nuances of this query language.
The previous version of the Interactive Google Ads Query Builder tool was useful for constructing GAQL query strings. However, there were opportunities to make the query building process faster while exposing some of the logic behind the tool to better understand how GAQL query string validation works.

As a result, we have released a new version of the Interactive Google Ads Query Builder tool that has several benefits, which you can view in the release blog post.

In developing this new tool, we approached the Google Ads API from a user's perspective to better understand developer use cases. Throughout the process, we documented our experience to share how we approach using the Google Ads API. This is the first in a series of blog posts following that journey. The Query Builder Blog Series will include the following topics.

Designing a resource schema: designing a detailed JSON resource schema that will serve as the canonical data set for the Interactive Query Builder Angular application.
Creating a resource schema: how we can use the GoogleAdsFieldService to create an enhanced resource schema that includes incompatible fields to make building this application easier.
Creating a resource service: how to create a resource service that determines which fields are displayed to users in various parts of the application.
Determining Field Selectability: how to create a selection service that determines whether a field is selectable or not in a given clause of a Google Ads Query Language (GAQL) query string.
Field Selection & Query Validation: how to update the selection service to select fields and validate the GAQL string.
Summary: a summary of key lessons learned from this process.

We hope you enjoy and learn from this blog series. Stay tuned for more interesting content.

If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.

- Devin Chasanoff, on behalf of the Google Ads API Team

Announcing the New and Improved Interactive Query Builder

2021-03-29T08:42:00.001-07:00

Today, we are releasing a new and improved version of the Google Ads Query Language (GAQL) interactive query builder. The new version is resource-centric and helps you build a GAQL query based on the resource in the FROM clause. There are two ways to to access the query builder:

Navigate to the developer documentation Reports tab. Expand the Query Builder on the left side of the page. Choose your resource.

Click the Help me build a query button for any resource in the reporting reference documentation.

Highlights

As users type, the new search bar filters fields dynamically.

We also designed this tool with a goal of educating developers about the Google Ads Query Language as they use it. The query builder dynamically surfaces hints (such as field compatibility)

and prompts (for example, to notify users of requirements to add fields to multiple clauses of a query).

The new query builder features “pretty print” mode to display queries in an easy to read format, as well as “interactive” mode, which provides the ability to remove and reorder fields directly within the query box.

As you get started with the new query builder, please feel free to share feedback by clicking the Send feedback button on the top right of any page.

If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.

- Devin Chasanoff, on behalf of the Google Ads API Team

Upcoming Change to the Enforcement of Temporary IDs with Product Partitions and Listing Groups

2021-03-23T06:36:00.000-07:00

Beginning in May, 2021 we will enforce a requirement that temporary IDs be unique for all objects in newly created listing groups (used for Hotel Ads and Shopping Ads in the Google Ads API) and product partitions (used for Shopping Ads in the AdWords API). This change will affect all versions of both the AdWords and Google Ads APIs.

Temporary IDs must be unique across an entire mutate request–even if the objects are in separate listing group trees or product partition trees.

In order to avoid unnecessary breakages, API users should update their applications to ensure that all temporary IDs used in individual requests are unique.

Here is a snapshot of the expected behavior for requests that continue using non-unique temporary IDs:

API and mutate method	Current Behavior	New Behavior
BatchJobService with the Google Ads API	Customers will receive a non-specific error, meaning it may not specify that the issue is related to temporary IDs.	Customers will start receiving failed operations that contain the error: `MutateError.MUTATE_ERROR_TEMP_ID_ALREADY_EXISTS`
BatchJobService with the AdWords API	Customers will receive a non-specific error, meaning it may not specify that the issue is related to temporary IDs.	Customers will start receiving failed operations that contain the error: `NewEntityCreationError.DUPLICATE_TEMP_IDS`
AdGroupCriterionService or GoogleAdsService.Mutate with the Google Ads API	Customers will not receive an error.	Customers will start receiving the error: `MutateError.MUTATE_ERROR_TEMP_ID_ALREADY_EXISTS`
AdGroupCriterionService with the AdWords API	Customers will not receive an error.	Customers will start receiving the error: `NewEntityCreationError.DUPLICATE_TEMP_IDS`

If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
- Ben Karl, on behalf of the Google Ads API Team

Reorganizing Similar Bid Strategies

2021-02-23T10:14:00.002-08:00

Update (March 12, 2021): Updated the language in this post to emphasize that this change is a reorganization of existing features.
The v6 release of the Google Ads API added support for Maximize conversions and Maximize conversion value bid strategies in Search campaigns. This includes a new read-only MaximizeConversions.target_cpa field. Bid strategies having either this new target_cpa field or the read-only MaximizeConversionValue.target_roas field act identically to TargetCpa and TargetRoas bid strategies, respectively. In the future, bid strategies for Search campaigns will be reorganized for simplification.

What’s changing
Starting in April 2021, the Google Ads UI will start allowing some users to create MaximizeConversions and MaximizeConversionValue bid strategies with their target_cpa and target_roas fields set, in lieu of the old-style TargetCpa and TargetRoas bid strategies. This change will gradually ramp-up to more accounts over time.

There will be no impact to bidding behavior due to these changes. The MaximizeConversions bid strategy using the new optional target_cpa setting will still behave like the TargetCpa strategy does today, and likewise, MaximizeConversionValue using the new optional target_roas setting will behave like TargetRoas.

Before	After
`TargetRoas`	`MaximizeConversionValue.target_roas`
`TargetCpa`	`MaximizeConversions.target_cpa`

The target_roas and target_cpa fields will remain read-only to API users until a future version of the API enables mutate functionality. Be on the lookout for such an announcement in the API’s release notes.

What to do
Developers should ensure their code treats Search campaigns that have MaximizeConversions with a set target_cpa field and MaximizeConversionValue with a set target_roas field the same way it treats TargetCpa and TargetRoas bid strategies, respectively.

Developers can continue to create TargetCpa or TargetRoas bid strategies or manage existing TargetCpa or TargetRoas bid strategies, even after we introduce the new representations in April. We will publish an update on the blog when the above fields are mutable, along with several months' notice before we start moving to the new representations of the bid strategies for existing Search campaigns.

If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
Adam Ohren, Google Ads API Team

New Personalized Advertising Policies Enforcement in Google Ads API and AdWords API

2021-02-11T08:07:00.000-08:00

Starting March 25, 2021, we are rolling out a change in the Google Ads API and AdWords API, to require advertisers who apply to the latest Personalized advertising policies to acknowledge these changes in the Google Ads UI. Campaign creation requests via the API will be rejected for these advertisers until they click to accept the changes.

Who will be impacted?
Advertisers promoting housing, employment, or credit products or services to audiences in the U.S. and Canada will be impacted.

What's changing?
You will receive the following errors when trying to create new campaigns via the API if the new policies have not been acknowledge:

API Version	Error Code	Error Message
Google Ads API v6.1	`CampaignError.HEC_AGREEMENT_REQUIRED`	`Customers with Housing, Employment, or Credit ads must accept updated personalized ads policy to continue creating campaigns`
Google Ads API (older versions)	`CampaignError.UNKNOWN`	Same as above.
AdWords API (v201809)	`CampaignService.OperationAccessDenied`	Same as above.

What should you do?

Before March 25, 2021, make sure to add support for the new policy errors in your application.
Ensure that the account administrators have accepted the policy changes in the Google Ads UI following this guide.

If you have any questions or need additional help, contact us through the Google Ads API and AdWords API forum or at googleadsapi-support@google.com.
Fan Wang, Google Ads API Team

Announcing v6.1 of the Google Ads API

2021-02-10T15:44:00.001-08:00

Today, we’re announcing the v6.1 release of the Google Ads API. To use some of the v6.1 features, you will need to upgrade your client libraries and client code. The updated client libraries and code examples will be published next week. This version has no breaking changes.

Here are the highlights:

Retrieving and managing recommendations for adding responsive search ads.
Added support for managing user invitations for a Google Ads account.
Added Feed, FeedItem, CampaignFeed, AdGroupFeed, and AdGroupAd resources to the list of resource types returned in queries against the change_event resource.
New conversion metrics by conversion date.
New call_view resource for reporting on call extensions and call only ads.

Where can I learn more?
The following resources can help you get started:

If you have any questions or need additional help, contact us via the forum.
Josh Radcliff, on behalf of the Google Ads API Team

Sunsetting Portofolio Enhanced CPC Bid Strategies

2021-02-09T06:26:00.000-08:00

On March 22, 2021 we will begin to sunset portfolio (shared) Enhanced cost-per-click (ECPC) bid strategies. The following behaviors will be blocked in all versions of both the AdWords API and the Google Ads API:

Creating new portfolio ECPC strategies.
Attaching portfolio ECPC strategies to campaigns.

Note that standard (non-portfolio) ECPC strategies will not be affected.

	Affected Portfolio Enhanced CPC Strategies
Google Ads API	`Bidding_strategy.type` = `BiddingStrategyType.ENHANCED_CPC`
AdWords API	`SharedBiddingStrategy.type` = `MANUAL_CPC`, `SharedBiddingStrategy.biddingScheme.enhancedCpcEnabled` = `TRUE`

Change Description
Any operation creating new portfolio ECPC strategies, or attaching a portfolio ECPC strategy to a campaign, will generate one of the following errors:

	Error Upon Creation	Error Upon Attaching
Google Ads API	`BIDDING_STRATEGY_NOT_SUPPORTED`	`CANNOT_ATTACH_BIDDING_STRATEGY_TO_CAMPAIGN`
AdWords API	`BIDDING_STRATEGY_NOT_SUPPORTED`	`CANNOT_ATTACH_BIDDING_STRATEGY_TO_CAMPAIGN`

Migration Description
In the future, we will remove the portfolio ECPC strategy entirely, in favor of standard ECPC. In order to prepare for this change, you can proactively migrate all your portfolio ECPC strategies to standard ECPC strategies using the instructions below.

All remaining portfolio ECPC campaigns and strategies will be automatically migrated at a later date. We will post an update on this blog ahead of that migration.

Self-migration using Google Ads API
Update a campaign by using CampaignService.MutateCampaigns() to set its manual_cpc.enhanced_cpc_enabled field to true. Be sure to set the update_mask on your request to match:


operations: [
  {
    update: {
      resource_mame: customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID,
      manual_cpc: {
        enhanced_cpc_enabled: true
      }
    },
    update_mask: manual_cpc.enhanced_cpc_enabled
  }
]

Self-migration using AdWords API
Update a campaign by using CampaignService.mutate() to set its biddingStrategyType to MANUAL_CPC, and its biddingScheme.enhancedCpc field to true:


<operations>
  <operator>SET</operator>
  <operand>
    <id>CAMPAIGN_ID</id>
    <biddingStrategyConfiguration>
      <biddingStrategyType>MANUAL_CPC</biddingStrategyType>
      <biddingScheme>
        <enhancedCpcEnabled>true</enhancedCpcEnabled>
      </biddingScheme>
    </biddingStrategyConfiguration>
  </operand>
</operations>

If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
Adam Ohren, Google Ads API Team

Changes to phrase match and broad match modifier

2021-02-04T13:28:00.000-08:00

On February 4, 2021, we announced upcoming changes to phrase match and broad match modifier. To simplify the keyword portfolio and help advertisers reach more relevant user searches, we are bringing behaviors of broad match modifier (BMM) into phrase match, and phasing out support for BMM. This will be a gradual rollout that will change the back end processing for keyword match types (AdWords API, Google Ads API, Google Ads scripts) in order to simplify keywords and make it easier to reach relevant customers.

The updated phrase match will contain the best of both match types: the control of phrase match, and the expanded reach of broad match modifier. Both phrase and BMM keywords will continue to work and beginning February 18, 2021 for our first wave of languages (English, German, Spanish, French, Italian, Dutch, Portuguese, Russian), keywords using the phrase or BMM notations will begin to use the updated phrase match behavior. In Q2 we will begin the same process for all other Google Ads languages, and expect to complete in July 2021.

In July 2021, once all languages have the updated phrase match behavior, advertisers will be prevented from creating new BMM keywords (but any legacy BMM keywords will still work).

The changes to phrase match and BMM will not impact negative keyword match types.

How does this change affect the AdWords API, Google Ads API and Google Ads scripts?
Starting in July 2021, you will no longer be able to create new BMM keywords (i.e. matchType of BROAD and keyword text in which tokens begin with +). We will do a separate reminder announcement as we get closer to this milestone.

What impact should advertisers expect?
Impact will depend on each advertiser's usage of phrase and/or BMM and how comprehensive their query coverage is.

Advertisers predominantly using phrase match are expected to see an incremental increase in clicks and conversions
- This is due to the additional queries to which these keywords will now be eligible to match. For example, “holidays in zambia” as a phrase keyword will now begin to match to “holiday spots in zambia”, which was previously only eligible for BMM.
Advertisers predominantly using BMM are expected to see a slight decrease in clicks and conversions
- The majority of this loss is from BMMs where the modifier was only applied to part of the keyword, e.g. tennis +shoes.
- In addition we are now considering word order when it’s important to the meaning of the keyword, so some matches that previously matched to BMM will be filtered out.

What should I do?
Advertisers may experience traffic shifts. User queries that previously matched to keywords in one match type may become eligible to match to a phrase or legacy BMM keyword causing the volume to move across keywords. For this reason it is important for advertisers to monitor their accounts and adjust budgets if needed to accommodate additional volume. Additional best practices are outlined in the announcement.

If you have any questions or need additional help, contact us via the forum.
David Wihl, Google Ads API Team

The Invoice Service of Google Ads API is out of beta

2021-02-04T08:01:00.000-08:00

The InvoiceService is now available for all API users starting with version 6 of the Google Ads API. Earlier API versions will continue to only support this service for allowlisted accounts.

This service retrieves the monthly invoices of Google Ads accounts. Each returned Invoice comes loaded with data (for example: adjustments, regulatory costs, taxes, account budgets) and can be downloaded as a PDF file. Google Ads manager accounts can use the data to automatically reconcile customer invoices. To get started, read through our dedicated guide.

If you have any questions or need additional help, contact us through the forum or at googleadsapi-support@google.com.
Pierrick Voulet, Google Ads API Team

Disabling "lead" category mutates in AdWords API

2021-02-03T07:30:00.000-08:00

On March 8, 2021 we're disabling mutates to the Lead category in the AdWords API. The Google Ads API ConversionActionCategory is not affected. This is a follow-on to the conversion category changes and expanded conversion categories announced in September 2020, which provided a finer grained categorization of conversions.

We are making this change because we are seeing some advertisers change their new category conversion types back to Lead category through the AdWords API, resulting in ambiguity since multiple new categories map to this old category. The following table summarizes how the AdWords API will respond to mutates that set the conversion category to Lead.

Existing Category	AdWords API READs (Existing behavior)	AdWords API Mutate to LEAD Response
Lead	Lead	OK
“Old” category	“Old” category	ERROR
“New” lead category	Lead	OK
“New” non-lead category	“Old” category	ERROR

Since the AdWords API does not support all the new conversion categories, reading in a new fine grained Lead conversion category will be mapped to Lead upon read, but will continue to be persisted as the finer grained new category. If read through the Google Ads UI or Google Ads API, the new conversion category will be accurately retrieved.

As a recap from our September 2020 announcement, here is the mapping of new conversion category types to existing AdWords API ConversionTracker.Category enum values:

New Conversion Category	Mapping to ConversionTracker.Category
Add to cart	LEAD
Begin checkout	LEAD
Purchase	PURCHASE
Subscribe	PURCHASE
Sign-up	SIGNUP
Phone call lead	LEAD
Imported lead	LEAD
Submit lead form	LEAD
Book appointment	LEAD
Request quote	LEAD
Get directions	LEAD
Outbound click	LEAD
Contact	LEAD
Download	DOWNLOAD
Page view	PAGE_VIEW
Engagement	DEFAULT
Store visit	DEFAULT
Store sale	PURCHASE
Other	DEFAULT

If you have any questions or need additional help, contact us via the forum.
David Wihl, Google Ads API Team

Changes to Hotel Ads pricing buckets in the Google Ads API

2021-01-25T08:31:00.000-08:00

On February 23rd, Google Ads API will be changing the way Hotel price buckets returns data by utilizing two new values in the hotel_price_bucket segment. Those new values will be added as enums in v6_1, “Lowest Unique” and “Only partner shown”.

Because there is overlap between the two new values and the existing “Lowest tied” value, after February 23rd developers using API versions earlier than v6_1 will see reports with the “Unknown” value wherever the two new values would be shown. This can result in one or two rows with the “Unknown” value.

Example:
Currently, data for ONLY_PARTER_SHOWN and LOWEST_UNIQUE are not returned, instead data is only shown for LOWEST_TIED.

LOWEST_TIED 12

Once the changes are released on February 23rd, developers on API versions v6_1 and greater will see the two new ONLY_PARTER_SHOWN and LOWEST_UNIQUE values, with the two new price buckets being displayed.

`LOWEST_UNIQUE`	3
`ONLY_PARTER_SHOWN`	4
`LOWEST_TIED`	5

After the changes are released on February 23rd, any developers on API versions lower than v6_1 will see “UNKNOWN” where the new values would have otherwise been shown.

`UNKNOWN`	3
`UNKNOWN`	4
`LOWEST_TIED`	5

If you have any questions about this change or any other API feature, please reach out to your account team directly, or contact us via the forum.
- Cory Liseno, Google Ads API Team

Ad Policy Error Management is evolving in Google Ads API

2021-01-15T13:05:00.001-08:00

Update (February 11, 2021): Added APP_AD and APP_ENGAGEMENT_AD to the list of ad types that are impacted by this change.

On March 1st, 2021, all versions of the Google Ads API will replace policy violations with policy findings for all remaining ad types.

The impact is limited to the creation and update of ads that trigger ad policy errors for the following types:

APP_AD
APP_ENGAGEMENT_AD
CALL_ONLY_AD
EXPANDED_DYNAMIC_SEARCH_AD
GMAIL_AD
HTML5_UPLOAD_AD
IMAGE_AD
LEGACY_APP_INSTALL_AD
LOCAL_AD
RESPONSIVE_DISPLAY_AD
RESPONSIVE_SEARCH_AD
VIDEO_RESPONSIVE_AD

If your application is impacted by this change and not upgraded before March 1st, 2021, then the ad policy errors will no longer be recognized and the requested exemptions will not be applied.

What’s Changing
Both AdGroupAdService.MutateAdGroupAds and AdService.MutateAds methods will behave differently:

Request: For each operation, the Google Ads API will only take into account the requested exemptions that are listed in PolicyValidationParameter.ignorable_policy_topics from the field policy_validation_parameter, not in PolicyValidationParameter.exempt_policy_violation_keys.
Response: The Google Ads API will only return ad policy errors as PolicyFindingErrors in the field GoogleAdsError.error_code and provide details as PolicyFindingDetails in the field GoogleAdsError.details, not as PolicyViolationErrors and PolicyViolationDetails.

What’s Not Changing

All the ad policies will remain and all the ad policy checks will still occur.
AdWords API
The ad policy status information AdGroupAdPolicySummary will remain accessible by querying the field AdGroupAd.policy_summary.

What to Do
Before March 1st, 2021, make sure to add the support of policy findings in your management of ad policy errors. To get started, you can refer to our guide and code example that are both dedicated to ad policy error management. We recommend testing with the ad types that already use policy findings: EXPANDED_TEXT_AD and RESPONSIVE_SEARCH_AD.

If you have any questions or need additional help, contact us through the forum or at googleadsapi-support@google.com.
Pierrick Voulet, Google Ads API Team

Update to Customer Match Uploads in the Google Ads API and the AdWords API Starting March 1, 2021

2021-01-12T09:41:00.000-08:00

On March 1, 2021, the Google Ads API and the AdWords API will have a new upload limit for each Customer Match upload request. There is no change to the limit of the overall Customer Match audience list size.

What code do I need to change?
When uploading user identifiers for Customer Match, check that the number of user identifiers you are uploading per request is within the limit.

	Google Ads API	AdWords API
Limit	100,000 per request	500,000 per user list ID per request
Method	`OfflineUserDataJobService.AddOfflineUserDataJobOperations()`	`AdWordsUserListService.mutateMembers()`
Field	`userIdentifiers`	`membersList`
Error on exceeding upload limit	`TOO_MANY_USER_IDENTIFIERS`	`TOO_MANY`

Why is this changing?
In order to make the processing of Customer Match user identifiers more efficient, we needed to set the new upload limit.

If you have any questions while updating your code, please reach out to us on our Google Ads API and AdWords API forum.
Nadine Wang, Google Ads API Team

The google_global_site_tag will no longer be filterable in Google Ads API

2021-01-11T13:51:00.000-08:00

What's changing?
Starting the week of Jan 25, 2021, the customer.remarketing_setting.google_global_site_tag field will no longer be filterable in the Google Ads API. If you use this field in a WHERE clause of a GAQL query in a call to the GoogleAdsService.Search or GoogleAdsService.SearchStream method, you will receive a QueryError.PROHIBITED_FIELD_IN_WHERE_CLAUSE error. Similarly, the GoogleAdsFieldService.SearchGoogleAdsFields method will report this field as non-filterable. This change affects all versions of the Google Ads API.

What should you do?
Before Jan 25, 2021, review and modify your Google Ads API reporting queries to stop using the google_global_site_tag field for filtering purposes.

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

Google Ads API v3 sunset reminder

2021-01-07T06:53:00.000-08:00

Google Ads API v3 will sunset on February 10, 2021. After this date, all v3 API requests will begin to fail. Please migrate to a newer version prior to February 10, 2021 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 or at googleadsapi-support@google.com.

- Thanet Knack Praneenararat, Google Ads API Team

Live Webinar: Website Conversions & Audience Remarketing

2020-12-01T06:32:00.000-08:00

The Google Ads API Developer Relations team will be hosting a live webinar, Website Conversions & Audience Remarketing with the Google Ads API, on December 11 at 10 AM EST (3 PM GMT).

Mark your calendar

Prerequisites
In order to get the most out of this webinar, we suggest you develop a basic understanding of the Google Ads API. In order to learn more, please visit our API Overview documentation or check out this Google Ads API Overview workshop from 2019. In addition, you may find this post useful to learn how conversion tracking works in Google Ads.

Agenda
The webinar will cover the topics below and include code walkthroughs to demonstrate how to perform different actions with the Google Ads API client libraries. We will also be hosting a live Q&A at the end.

What conversion actions are
How to create and utilize conversion actions
How remarketing works in the Google Ads API
How to define different audience types
How to measure audience performance

Reminders
Feel free to add the event to your calendar. In addition, you can set a reminder for the event on YouTube by clicking the “Set reminder” button on the YouTube event page.

We look forward to sharing our knowledge of the Google Ads API with you and answering your questions. If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
- Devin Chasanoff, on behalf of the Google Ads API Team

Live Webinar: Intro to Reporting & the Google Ads Query Language

2020-11-18T09:54:00.000-08:00

The Google Ads API Developer Relations team will be hosting a live webinar, Intro to Reporting & the Google Ads Query Language, on December 4 at 10 AM EST (3 PM GMT).

Mark your calendar

Agenda
The webinar will cover the topics below and include code walkthroughs to demonstrate how to perform different actions with the Google Ads API client libraries. We will also host a live Q&A at the end.

Reporting in the Google Ads API vs. the AdWords API
Types of search requests you can perform with the Google Ads API
The syntax and structure of Google Ads Query Language queries
How to discover available fields to construct Google Ads Query Language queries

Prerequisites
In order to get the most out of this webinar, we suggest you develop a basic understanding of the Google Ads API. To learn more, please visit our API Overview documentation or check out this Google Ads API Overview workshop from 2019. In addition, you may find this guide useful to learn about reporting with the Google Ads API, though much of this information will be covered in the webinar.

Reminders
Feel free to add the event to your calendar. In addition, you can set a reminder for the event on YouTube by clicking the “Set reminder” button on the YouTube event page.

We look forward to sharing our knowledge of the Google Ads API with you and answering your questions. If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
- Devin Chasanoff, on behalf of the Google Ads API Team

Announcing v6 of the Google Ads API

2020-11-09T07:00:00.000-08:00

Today, we’re announcing the v6 release of the Google Ads API. To use the v6 features, you will need to upgrade your client libraries and client code. The updated client libraries and code examples will be published this week. For more information on breaking changes, see the migration guide.

Here are the highlights:

The API now has Change History similar to the Google Ads UI with ChangeEvent including what interface and who made the changes.
You can now manage user access in your Google Ads account.
Maximize conversion value and maximize conversions are now available as portfolio bidding strategies, which includes Search.
The new Customer.optimization_score_weight helps you calculate your overall optimization score for your manager account.
New audience types are available including CombinedAudience and CustomAudience.

Where can I learn more?
The following resources can help you get started:

If you have any questions or need additional help, contact us via the forum.
Nadine Wang, on behalf of the Google Ads API Team

Target Spend Migration for Maximize Clicks Bid Strategies

2020-10-29T11:06:00.000-07:00

Starting January 18, 2021, we will start migrating Maximize Clicks bid strategies that still utilize the deprecated target_spend setting to use campaign daily budget pacing instead. This follows last year’s sunset of the target_spend field for Maximize Clicks. After that sunset went into effect, Google Ads has prevented users from creating any new Maximize Clicks strategies that have a target_spend setting.

What’s changing

As part of this migration, any Maximize Clicks bid strategies that still use the target_spend setting may have their maximum CPC bid limit lowered to minimize the performance impact that may result from this change. This would affect the following API fields:

Fields whose values may be lowered as part of the January 18, 2021, migration:
AdWords API	Google Ads API
TargetSpendBiddingScheme.bidCeiling	TargetSpend.cpc_bid_ceiling_micros

What you can do

You can avoid the above changes by removing the target spend setting on your campaigns’ bidding strategies before January 18, 2021. To do so, unset the following field (set its value to 0) on any existing Maximize Clicks bid strategies:

Fields to unset (set to `0`) to avoid the migration:
AdWords API	Google Ads API
TargetSpendBiddingScheme.spendTarget	TargetSpend.spend_target_micros

If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.

Adam Ohren, Google Ads API Team

Google Ads and AdWords APIs upgrading authorization scope to "sensitive"

2020-10-15T06:02:00.000-07:00

As of October 1, 2020, any Google Cloud app used to obtain credentials for the Google Ads API or AdWords API scope (https://www.googleapis.com/auth/adwords) in its projects (i.e. any new AdWords API or Google Ads API developers) will need to undergo a Google OAuth verification to avoid an unverified app screen for its users. An app, in this context, is defined as a unique OAuth 2.0 Client ID in Google Cloud. This verification is independent and in addition to any reviews conducted as part of the developer token approval process.

There is no cost for the Google verification, which typically completes in 3 to 5 business days. Information on how this process fits in the larger task of authorizing requests can be found in our guide. The verification status of a given app can be viewed at the OAuth consent screen of a Google Cloud Project.

Apps already using the Google Ads API or AdWords API scope prior to October 1, 2020 are not currently affected by this policy. However, this policy will be applied to all apps at a later date in 2021, and it is recommended that all apps undergo the Google OAuth verification process at their earliest convenience to avoid any business interruptions.

If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
- Devin Chasanoff, on behalf of the Google Ads API Team

Announcing the Google Ads API is out of beta

2020-09-21T10:04:00.000-07:00

We are excited to announce that the Google Ads API is now generally available. This means you can use the Google Ads API for your production applications with confidence that prior performance issues have all been addressed. Batch processing is now available to everyone.

The AdWords API will continue to be supported. We will announce a deprecation schedule at a later date. We will continue to add more features in upcoming releases to reach full parity with the AdWords API.

Where can I learn more?
Get started with the following resources:

If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
Nadine Wang, on behalf of the Google Ads API Team

Conversion Category Changes in AdWords API, Google Ads API, and Google Ads scripts

2020-09-08T09:06:00.002-07:00

Update (Feb 1, 2021): Correction to some of the category mappings.

Since May 2020, when you sign in to your Google Ads account you may be prompted to upgrade each of your conversion actions to the new conversion categories. The updated conversion categories provide more granularity to describe the conversion actions that are the most meaningful for your business. More details can be found in this Google Ads Help Center article.

Starting October 15th 2020, these suggestions will be automatically applied if you haven’t already accepted them. Google Ads API, AdWords API and Google Ads Scripts users will see the following changes:

If you are using the Google Ads API, the new conversion categories are already available in ConversionActionCategoryEnum. No further action is needed.

If you are using the AdWords API, since we are not releasing a new version for the AdWords API, the new conversion category types will be translated to the existing ConversionTracker.Category enum values, based on the mapping below:

New Conversion Category	ConversionTracker.Category
Add to cart	`LEAD`
Begin checkout	`LEAD`
Purchase	`PURCHASE`
Subscribe	`PURCHASE`
Sign-up	`SIGNUP`
Phone call leads	`LEAD`
Imported lead	`LEAD`
Submit lead form	`LEAD`
Book appointment	`LEAD`
Request quote	`LEAD`
Get directions	`LEAD`
Outbound click	`LEAD`
Contact	`LEAD`
Download	`DOWNLOAD`
Page view	`PAGE_VIEW`
Engagement	`DEFAULT`
Store visit	`DEFAULT`
Store sale	`PURCHASE`
Other	`DEFAULT`

Therefore, if you are using the AdWords API to retrieve conversion category types (via reports or services), you will still see existing conversion category types being returned based on the mapping above, which will be different from the migrated new types in Google Ads UI.

AdWords API users can still create conversion actions using the existing category types. The AdWords API will automatically translate the created conversions to new category types, based on machine learning models. You can find code examples on how to set category type for conversion actions on the AdWords API developer site.

If you are using Google Ads scripts, when you select or filter on the report field ConversionCategoryName, you will see the same existing category types as the ones used in AdWords API, based on the mapping in the above table.

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