Upcoming breaking changes to the Google Ad Manager API

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:

1. Remove any Columns not in the list above.
2. Remove any Dimensions that are not prefixed with AD_EXCHANGE, with the exception of the following Dimensions:
1. DATE
2. WEEK
3. DAY
4. MONTH_AND_YEAR
3. Remove any DimensionAttributes for dimensions you removed.
4. Remove any PQL filters that applied to fields you removed.

To convert the report to a Historical report:

1. Remove any of the Columns in the list above.
2. Remove any Dimensions that are prefixed with AD_EXCHANGE.
3. 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.

 - Chris Seeley, Ad Manager API Team