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: