Today we’re releasing an update to the Display & Video 360 API which includes the following features:

• Support for retrieval and management of TV insertion orders and over-the-top line items through the introduction of an insertionOrderType field and new LineItemType enum value.
• Full support of mobile app line items with the addition of a mobileApp field in the LineItem resource.
• Additional values for Exchange, GoogleAudienceType, and SdfVersion enums.
• The ability to filter and order advertiser.list responses by updateTime.

More detailed information about this update can be found in the Display & Video 360 API release notes.

Before using these new features, make sure to update your client library to the latest version.

If you run into issues or need help with these new features, please contact us using our support contact form.

- Trevor Mulchay, Display & Video 360 API Team

On Monday, March 1, 2021, in accordance with the deprecation schedule, v202002 of the Ad Manager API will sunset. At that time, any requests made to this version will return errors.

If you’re still using v202002, now is the time to upgrade to a newer release and take advantage of additional functionality. For example, in v202011 we added the getTrafficData method to the ForecastService, which is capable of exploring historical and forecasted network-level data for a particular date range and targeting configuration.

When you’re ready to upgrade, check the full release notes to identify any breaking changes. Keep in mind that v202002 is the final version to use int types for Activity and ActivityGroup, and all later versions use type long. After you’ve considered all of the changes, grab the latest version of your client library and update your code.

As always, don't hesitate to reach out to us on the developer forum with any questions.
 - Donovan McMurray, Ad Manager API Team

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

Google is launching experiments that are intended to provide bidders with an opportunity to test and provide collaborative feedback on ads-privacy proposals–these are features intended to improve user privacy protections and provide mechanisms for testing Chrome Privacy Sandbox proposals. We strongly encourage interested bidders to sign up and participate! Three new experiments made available today are described below.

Experiment #1: TURTLEDOVE simulationThe RTB protocols and infrastructure have been updated to enable a server-side simulation of Chrome’s TURTLEDOVE proposal, as described in the TURTLEDOVE simulation proposal. Bidders interested in participating can reference the TURTLEDOVE RTB Simulation API guide to learn more about the specific API and protocol changes associated with this experiment. Along with these changes, a new biddingFunctions resource for managing bidding functions that are used in the server-side simulation was added to the Real-time Bidding API.

The goal of this simulation is to provide bidders with an opportunity to experiment with Chrome’s proposal before it is implemented in Chrome, so that participating bidders can provide feedback on its viability and effectiveness. The APIs and modified RTB workflow used in the server-side simulation are conceptually similar to the ones that Chrome may later implement for TURTLEDOVE, based on existing proposals and public design discussions. Feedback relevant to Google’s simulation should be directed to the ads-privacy issue tracker, whereas feedback relevant to the TURTLEDOVE proposal itself should be directed to Chrome’s TURTLEDOVE issue tracker. To report bugs or technical questions about this experiment, you may contact the brse-eng-support@google.com support alias.

Experiment #2: Federated Learning of Cohorts (FLoC)Google will allow participating bidders to experiment with Chrome’s FLoC proposal by simulating FLoC cohorts on its servers, based on algorithms described in this Google Research & Ads whitepaper. To facilitate this experiment, a Floc message has been added to the BidRequest in the Google RTB protocol, and as an extension of the User object for Google’s OpenRTB implementation. The message is structured as follows:

message Floc {
    // The value of a cohort ID – a string identifier that is common to a large
    // cohort of users with similar browsing habits.
    optional string id = 1;
    // The type of the FLoC. See
    // https://github.com/google/ads-privacy/blob/master/proposals/FLoC/FLOC-Whitepaper-Google.pdf.
    enum FlocType {
      // Default value that should not be used.
      FLOC_TYPE_UNKNOWN = 0;
      // FLoC simulated using affinity hierarchical clustering with centroids
      // and feature extraction based on Topic categories as described in the
      // whitepaper.

      SIMULATED_AFFINITY_CLUSTERING_CENTROID_VERTICAL = 2;
      // FLoC simulated using SortingLSH clustering algorithm and Domain One-hot
      // encoding feature extraction as described in the whitepaper.
      SIMULATED_SIMHASH_SORTING_LSH_DOMAIN_ONE_HOT = 3;
      // FLoC simulated using a k Random Centers locality-sensitive hash
      // function as described in
      // https://github.com/google/ads-privacy/blob/master/proposals/FLoC/k-random-centers.md
      // with Domain TF-IDF feature extraction as described in the whitepaper.
      KCENTER_DOM_FILTERED_TFDIF = 4;
    }
    optional FlocType type = 2;
  }
  

Only web requests are in scope for the FLoC simulation experiment. In practice, only a small percentage of bid requests for bidders opted-in to the experiment would include this message, and those that do would not include pseudonymous user identifiers such as google_user_id and hosted_match_data.

Floc would also not be populated as a result of privacy controls, such as when users opt out of personalized advertising. Upon winning impressions, bidders can render creatives as usual and use their cookie-based identifiers to attribute conversions–for instance–to measure how well different FLoCs correlate with conversions.

We encourage participants to use the issue tracker to leave feedback on the simulated cohort algorithms. One useful metric to include would be the conversion rates for each FlocType in the experiment, possibly in comparison to regular traffic, where bidders may rely on cookie-based identifiers for targeting and optimization.

Experiment #3: Exchange-enforced frequency cappingThe RTB protocols have been updated to enable an experiment for the exchange-enforced frequency capping proposal, which intends to support the critical frequency capping use case for the inventory provided by a single exchange without reliance on user identifiers provided in bid requests. A FrequencyCap message has been added to the BidResponse in the Google RTB protocol, and as an extension of the Bid object for Google’s OpenRTB implementation. The message is structured as follows:

  message FrequencyCap {
    // An ID that can represent a bidder's use-case for frequency capping; for
    // example, it could represent their campaign, ad, line item, etc. It should
    // not contain any user-specific information or identifiers.
    optional string fcap_id = 1;

    // The time units for which frequency caps can be enforced.
    enum TimeUnit {
      UNKNOWN_TIME_UNIT = 0;
      MINUTE = 1;
      DAY = 2;
      WEEK = 3;
      MONTH = 4;
      // When INDEFINITE is used, time_range will be ignored. INDEFINITE means
      // the frequency cap will be applied for a long period of time, (longer
      // than a month) but not necessarily forever.
      INDEFINITE = 5;
    }

    // The unit of time used to specify the time window for which a frequency
    // cap applies.
    optional TimeUnit time_unit = 2;

    // The length of the time window, in units specified by time_unit, for which
    // the frequency cap applies. For instance, if time_unit=WEEK and
    // time_range=3, then capping is applied for a three week period. If the
    // time_unit=INDEFINITE, this will be ignored.
    optional int32 time_range = 3 [default = 1];

    // The maximum number of impressions allowed to be shown to a user for
    // the provided frequency_cap_id within the time window described by
    // time_unit and time_range.
    optional int32 max_imp = 4;
  }

Additional information about this experiment can be found in the proposal, and we encourage participants to leave feedback in the issue tracker.

Mark Saniscalchi, Authorized Buyers Developer Relations

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

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

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

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 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:

• Upgrading to the newest version
• Release notes

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