Data Deprecation Policy for Google Analytics APIs

This document describes the data deprecation policy for the Core Reporting and Metadata APIs.

Overview

Dimensions and metrics (columns) are used to query the Google Analytics Reporting APIs. At times it is necessary to add, remove, or rename these columns. The data deprecation policy is provided to increase transparency on how these changes take place.

All column changes will be communicated through changelogs and the Metadata API will automatically update to reflect these changes.

What’s Covered By This Policy

This policy covers the dimensions and metrics exposed by public APIs. It does not cover the API request (query parameters), the API response, the values returned by the API, or valid combinations of dimensions and metrics.

New Data

When new columns are added to an API:

  • The changelog of the corresponding API will be updated with details about the new column(s).
  • The column(s) will be available in the Metadata API.

Data Removal

When columns are removed from an API:

  • The changelog of the corresponding API will be updated with details about the column(s) being removed.
  • In the Metadata API, the column status attribute will be set to DEPRECATED.
  • The column(s) will continue to work in reporting queries for a minimum of 6 months.
  • After 6 months, the column(s) will be removed from the Metadata API and querying for the column(s) in the reporting API will result in a 400 Bad Request error.

Data Rename

When columns are renamed:

  • The changelog of the corresponding API will be updated with details about the original and replacement column(s).
  • In the Metadata API , the status attribute of the original column will be set to DEPRECATED and the replacedBy attribute will be set to the Id of the replacement column.
  • The original column(s) will continue to work in reporting queries for a minimum of 6 months.
  • After 6 months, the original column(s) will be removed from the Metadata API and querying for the column(s) in the reporting API will result in a 400 Bad Request error.

Attribute Removal

When attributes are removed from the Metadata API:

  • The Metadata API changelog will be updated with details about the attribute(s) being removed.
  • The attribute(s) will continue to be available in the Metadata API for a minimum of 6 months.
  • After 6 months, the attribute(s) will be removed from the Metadata API.

Groups

At times it is necessary to change the name of a group or the ordering of the columns. When this occurs: