Tag Archives: adwords_api_v201809

Broad match modifier upcoming changes in Google Ads

On February 4, 2021, we announced changes to phrase match and broad match modifier (BMM). As advised in that post, as of today all Google Ads languages have now been updated to use the new phrase match definition. Also as of today, all legacy BMM keywords will continue to serve but will now behave as phrase match keywords. Creation of new BMMs using the legacy BMM notation (+keyword) and modifications to existing BMM keyword text will no longer be permitted as of August 2, 2021 (AdWords API, Google Ads API, Google Ads scripts).

Updates of other targeting criteria fields (such as status, bid, url, labels) will still be permitted.

Partners are encouraged to follow the guidance in this article. As detailed in the article, if you choose to convert BMM keywords to phrase match, performance statistics will not carry over to the new instances. Smart bidding users are encouraged to use the broad match type.

Note: The changes to phrase match and BMM will not impact exact match, broad match, or negative keyword match types. Learn more about keyword matching options.

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

Deprecating Url Performance Report and Automatic Placements Performance Report in the AdWords API

Starting July 12, 2021, we will be deprecating Url Performance Report and Automatic Placements Performance Report in the AdWords API. The two reports will return empty results in the AdWords API after the deprecation.

To continue accessing these two reports, please migrate to Google Ads API and use the following views: For migrating reports to Google Ads API, refer to the report migration guide.

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

Changes to phrase match and broad match modifier

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.
, Google Ads API Team

Disabling "lead" category mutates in AdWords API

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.
, Google Ads API Team

Changes to conversion columns in AdWords API and Scripts

What's changing?
We are introducing restrictions on certain combinations of conversion columns in AdWords API and Google Ads scripts reports. If your reporting queries include these column combinations, you need to fix your queries before Feb 15, 2021.

Technical details
Starting the week of Feb 15, 2021, you will receive a ReportDefinitionError.INVALID_FIELD_NAME_FOR_REPORT error if your AdWords API report request contains columns from both of the restricted column sets listed below. Similarly, calls to the AdsApp.report method in Google Ads scripts will fail for queries with these restricted column combinations.

Restricted conversion columns:
  • ConversionAdjustment
  • ConversionAdjustmentLagBucket
  • ConversionAttributionEventType
  • ConversionCategoryName
  • ConversionLagBucket
  • ConversionTrackerId
  • ConversionTypeName
Metrics columns:
  • AllConversionRate
  • ConversionRate
  • CostPerAllConversion
  • CostPerConversion
  • CostPerCurrentModelAttributedConversion
The ReportDefinitionService.getReportFields method will reflect these restrictions in the exclusiveFields list of each impacted column.

What should you do?
Before Feb 15, 2021, review and modify the reporting queries in your AdWords API and Google Ads scripts applications to stop using the prohibited column combinations.

Why is this changing?
These column combinations are currently disallowed by the Google Ads UI, Google Ads Editor and the Google Ads API. This change makes the AdWords API and Google Ads scripts behaviour consistent with the rest of the Google Ads platform.

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

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

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 (paid) PURCHASE
Subscribe (free) SIGNUP
Phone call leads LEAD
Offline lead LEAD
Submit lead form LEAD
Book appointment LEAD
Request quote LEAD
Get directions LEAD
Outbound click LEAD
Contact LEAD
Download DOWNLOAD
View key page 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

Announcing v201809 of the AdWords API

Today we’re announcing the release of AdWords API v201809. Here are the highlights:

  • More available text in ads. Several ad types now have additional fields, and an increased character count of 90 characters for descriptions. Check out the release notes for more details.
  • Traffic split in trials. The new trafficSplitType gives you greater control over how traffic is split in your trials.
  • Conversion reporting. The new ConversionAttributionEventType field in the CAMPAIGN_PERFORMANCE_REPORT allows you to segment AllConversions and related metrics by event type (impression or interaction). In addition, the new ConversionAdjustment and ConversionAdjustmentLagBucket fields allow you to determine if conversion adjustments were applied and segment metrics by the number of days between the impression and either conversions or adjustments.

If you’re using v201802 of the AdWords API, please note that it will be sunset on January 30, 2019. We encourage you to skip v201806 and migrate straight to v201809. If you're using v201806, be aware it's now marked deprecated and will be sunset on March 26, 2019.

As with every new version of the AdWords API, please carefully review all changes in the release notes and the v201809 migration guide. The updated client libraries and code examples will be published within the next 48 hours.

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

- Josh Radcliff on behalf of the AdWords API Team.