Google Ads Developer Blog: Upcoming breaking changes to the Google Ad Manager API

Ads Developer Blog

The official blog for information about the Google Ads, Google Ad Manager, Google Mobile Ads SDKs for AdMob and IMA SDKs, and other Google Advertising Platform developer tools.

Upcoming breaking changes to the Google Ad Manager API

Friday, May 3, 2019

Update 2019-10-03: A prior version of this post incorrectly listed the HOUR dimension as supported for Ad Exchange historical reports. The HOUR dimension is no longer supported in newly created Ad Exchange historical reports. However, HOUR will continue to be supported in existing Ad Exchange historical reports for a limited time. Please update your existing reports as soon as possible.
On Monday July 8, 2019 the Ad Manager API's ReportService will stop supporting reports that mix Ad Exchange historical reporting fields with Historical reporting fields. This change will impact all API versions.

After July 8, any API reports that use both an Ad Exchange historical Dimension or Column and a Historical Dimension or Column will fail with the following error: ReportError.REPORT_CONSTRAINT_VIOLATION

Why are we making this change?

This change is being made to ensure all API reports return accurate data. The Query Tool has never supported creating reports that mix Ad Exchange historical and Historical data, and in some cases this may lead to unexpected results. This change brings the API in line with the Query Tool.

How can I tell if I am impacted?

This change impacts approximately 2% of all reports run with the Ad Manager API. If you only run saved queries that were created with the Query Tool, this change does not impact you.

If you use any of the following columns, your report will be considered an Ad Exchange historical report, and you may only use either Dimensions prefixed with AD_EXCHANGE or date Dimensions including DATE, WEEK, DAY or MONTH_AND_YEAR:

Column.AD_EXCHANGE_ACTIVE_VIEW_ENABLED_IMPRESSIONS
Column.AD_EXCHANGE_ACTIVE_VIEW_MEASURED_IMPRESSIONS
Column.AD_EXCHANGE_ACTIVE_VIEW_VIEWED_IMPRESSIONS
Column.AD_EXCHANGE_AD_CTR
Column.AD_EXCHANGE_AD_ECPM
Column.AD_EXCHANGE_AD_REQUEST_CTR
Column.AD_EXCHANGE_AD_REQUEST_ECPM
Column.AD_EXCHANGE_AD_REQUESTS
Column.AD_EXCHANGE_AVERAGE_VIEWABLE_TIME
Column.AD_EXCHANGE_CLICKS
Column.AD_EXCHANGE_COVERAGE
Column.AD_EXCHANGE_CPC
Column.AD_EXCHANGE_CTR
Column.AD_EXCHANGE_DEALS_AD_REQUESTS
Column.AD_EXCHANGE_DEALS_BID_RESPONSES
Column.AD_EXCHANGE_DEALS_MATCH_RATE
Column.AD_EXCHANGE_DEALS_MATCHED_REQUESTS
Column.AD_EXCHANGE_ESTIMATED_REVENUE
Column.AD_EXCHANGE_IMPRESSIONS
Column.AD_EXCHANGE_LIFT
Column.AD_EXCHANGE_MATCHED_ECPM
Column.AD_EXCHANGE_MATCHED_REQUESTS
Column.AD_EXCHANGE_VIDEO_ABANDONMENT_RATE
Column.AD_EXCHANGE_VIDEO_DROPOFF_RATE
Column.AD_EXCHANGE_VIDEO_QUARTILE_1
Column.AD_EXCHANGE_VIDEO_QUARTILE_3
Column.AD_EXCHANGE_VIDEO_TRUEVIEW_SKIP_RATE
Column.AD_EXCHANGE_VIDEO_TRUEVIEW_VIEWS
Column.AD_EXCHANGE_VIDEO_TRUEVIEW_VTR

What changes do I need to make?

To prevent your reports from failing, you must convert your report to be either an Ad Exchange historical report or a Historical report.

To convert the report to an Ad Exchange historical report:

Remove any Columns not in the list above.
Remove any Dimensions that are not prefixed with AD_EXCHANGE, with the exception of the following Dimensions:

DATE
WEEK
DAY
MONTH_AND_YEAR

Remove any DimensionAttributes for dimensions you removed.
Remove any PQL filters that applied to fields you removed.

To convert the report to a Historical report:

Remove any of the Columns in the list above.
Remove any Dimensions that are prefixed with AD_EXCHANGE.
Remove any PQL filters that applied to fields you removed.

If you have questions about this change or are unsure if it impacts you, reach out to us on the Ad Manager API forums. We'll be happy to check if you're impacted and work with you to update your applications.