Advanced Use Cases

This document describes the advanced features of the Google Analytics Reporting API v4. For a detailed reference of the API, see the Reference Guide.

Note: This API does not support Google Analytics 4 (GA4) properties. Please use the Google Analytics Data API to access the new reporting features for GA4 properties.

Introduction

After creating a simple report, use these features to create advanced reports:

• Pivots
• Cohorts
• Lifetime value

Note: See the Request Composer for a demo application which makes use of some of these features.

Pivots

Google Analytics Reporting API v4 allows you to generate Pivot Tables. To construct a request with a pivot table, define the Pivot field in the ReportRequest. The Pivot object has its own set of dimensions and metrics, and optional startGroup and maxGroupCount to specify the number of dimensions to be included in the pivot table.

Request

The following API call requests sessions by country and pivots the results on browser:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges":
      [
        {
          "startDate": "2014-11-01",
          "endDate": "2014-11-30"
        }
      ],
      "metrics":
      [
        {
          "expression": "ga:sessions"
        }
      ],
      "dimensions":
      [
        {
          "name": "ga:country"
        }
      ],
      "pivots":
      [
        {
          "dimensions":
          [
            {
              "name": "ga:browser"
            }
          ],
          "maxGroupCount": 3,
          "startGroup": 3,
          "metrics":
          [
            {
              "expression": "ga:sessions"
            }
          ]
        }
      ]
    }
  ]
}

Note: The orderBys field does not affect the pivot dimensions or metrics.

Response column header

In the returned report object for a pivot request, the metricHeader has a list of pivotHeaders objects whose pivotHeaderEntries fields define the ordering of pivot dimension values and the corresponding metric values, for example:

"columnHeader": {
    "dimensions": [
        "ga:country"
    ],
    "metricHeader": {
        "metricHeaderEntries": [
            {
                "name": "ga:sessions",
                "type": "INTEGER"
            }
        ],
        "pivotHeaders": [
            {
                "pivotHeaderEntries": [
                    {
                        "dimensionNames": [
                            "ga:browser"
                        ],
                        "dimensionValues": [
                            "Internet Explorer"
                        ],
                        "metric": {
                            "name": "ga:sessions",
                            "type": "INTEGER"
                        }
                    },
                    {
                        "dimensionNames": [
                            "ga:browser"
                        ],
                        "dimensionValues": [
                            "Firefox"
                        ],
                        "metric": {
                            "name": "ga:sessions",
                            "type": "INTEGER"
                        }
                    },
                    {
                        "dimensionNames": [
                            "ga:browser"
                        ],
                        "dimensionValues": [
                            "Android Browser"
                        ],
                        "metric": {
                            "name": "ga:sessions",
                            "type": "INTEGER"
                        }
                    }
                ],
                "totalPivotGroupsCount": 7
            }
        ]
    }
},

Response rows

Each row of the reportData object defines an array of dateRangeValue objects, each of which contains a set of pivotValue objects; the order of the values corresponds to the order of the metrics listed in the pivot headers in the response column header.

"rows": [
    ...
    {
        "dimensions": [
            "United States"
        ],
        "metrics": [
            {
                "pivotValues": [
                    {
                        "values": [
                            "21",
                            "18",
                            "1"
                        ]
                    }
                ],
                "values": [
                    "192"
                ]
            }
        ]
    }
],

Note that there are only three pivot values in the report because in the original request, maxGroupCount is 3. There could be up to seven values because of "totalPivotGroupsCount": 7.

Pivot table row example

In the sample response above, the row associated with the country United States is represented in the following pivot table:

Country	Total Sessions	Internet Explorer Sessions	FireFox Sessions	Android Browser Sessions
India	12	3	2	4
United States	192	21	18	1
United Kingdom	35	12	2	0

Cohorts

A cohort is a group of users who share a common characteristic. For example, all users with the same Acquisition Date belong to the same cohort. The Cohort Analysis report lets you isolate and analyze cohort behavior. For a list of Cohort specific dimensions and metrics, see Cohort and lifetime value (LTV) dimensions and metrics.

To define a cohort request, you must define a cohort object with name, type, and dateRange:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions":
      [
        {
          "name": "ga:cohort"
        },
        {
          "name": "ga:cohortNthDay"
        }
      ],
      "metrics":
      [
        {
          "expression": "ga:cohortActiveUsers"
        },
        {
          "expression": "ga:cohortTotalUsers"
        }
      ],
      "cohortGroup":
      {
        "cohorts":
        [
          {
            "name": "cohort 1",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-08-01",
              "endDate": "2015-08-01"
            }
          },
          {
            "name": "cohort 2",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-07-01",
              "endDate": "2015-07-01"
            }
          }
        ]
      }
    }
  ]
}

See the example above in the API Explorer.

Note: When defining a cohort request, you do not need to provide the ReportRequest.dateRanges field.

Cohort restrictions

A valid cohort request must meet the following restrictions:

• The ga:cohort dimension is included if and only if the request has one or more cohort definitions.
• The cohort name must be unique.
• The maximum number of cohorts in a request is 12.
• If ga:cohortNthWeek is defined, the start date must be Sunday and the end date must be Saturday. If ga:cohortNthMonth is defined, the start date must be the first day of the month and the end date must be the last day of the month. If ga:cohortNthDay is defined, the date range must be exactly one day.
• Cohort requests with today's date are not allowed.
• Cohort and non-cohort requests should not be in the same batchGet request.
• The date range in cohorts must be after February 1, 2015.

Lifetime value (LTV)

The Lifetime Value report shows how user value (Revenue) and engagement (Appviews, Goal Completions, Sessions, and Session Duration) grow during the 90 days after a user is acquired. See LTV specific dimensions and metrics.

A LTV request is defined as a cohort with the lifetimeValue field set to true, for example:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions":
      [
        {
          "name": "ga:cohort"
        },
        {
          "name": "ga:cohortNthWeek"
        }
      ],
      "metrics":
      [
        {
          "expression": "ga:cohortTotalUsersWithLifetimeCriteria"
        },
        {
          "expression": "ga:cohortRevenuePerUser"
        }
      ],
      "cohortGroup":
      {
        "cohorts":
        [
          {
            "name": "cohort 1",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-08-01",
              "endDate": "2015-09-01"
            }
          },
          {
            "name": "cohort 2",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-07-01",
              "endDate": "2015-08-01"
            }
          }
        ],
        "lifetimeValue": true
      }
    }
  ]
}

See the above example in the API Explorer.

Note: When defining a lifetime value request, you do not need to provide the ReportRequest.dateRanges field.

Cohort and lifetime value (LTV) dimensions and metrics

Dimensions

Dimension Name	Definition
ga:cohort	Name of the cohort to which a user belongs. Depending on how cohorts are defined, a user can belong to multiple cohorts, similar to how a user can belong to multiple segments.
ga:cohortNthDay	0-based day offset relative to the cohort definition date. For example, if a cohort is defined with the first visit date as 2015-09-01, then for the date 2015-09-04, ga:cohortNthDay will be 3.
ga:cohortNthMonth	0-based month offset relative to the cohort definition date.
ga:cohortNthWeek	0-based week offset relative to the cohort definition date.
ga:acquisitionTrafficChannel	Traffic channel through which the user was acquired. It is extracted from the first session of the user. Traffic channel is computed based on the default channel grouping rules (at view level if available) at the time of user acquisition.
ga:acquisitionSource	The source through which the user was acquired. Derived from the first session of the user.
ga:acquisitionMedium	The medium through which the user was acquired. Derived from the first session of the user.
ga:acquisitionSourceMedium	The combined value of ga:userAcquisitionSource and ga:acquisitionMedium.
ga:acquisitionCampaign	The campaign through which the user was acquired. Derived from the first session of the user.

Metrics

Metric Name	Definition
ga:cohortActiveUsers	This metric is relevant in the context of the 0-based offset dimensions (ga:cohortNthDay, ga:cohortNthWeek, or ga:cohortNthMonth). It indicates number of users in the cohort who are active in the time window corresponding to the cohort nth day/week/month. For example, for ga:cohortNthWeek = 1, number of users (in the cohort) who are active in the second week. If a request does not have any of ga:cohortNthDay, ga:cohortNthWeek, or ga:cohortNthMonth, this metric will have the same value as ga:cohortTotalUsers.
ga:cohortTotalUsers	Number of users belonging to the cohort, also known as cohort size.
ga:cohortAppviewsPerUser	App views per user for a cohort.
ga:cohortGoalCompletionsPerUser	Goal completions per user for a cohort.
ga:cohortPageviewsPerUser	Pageviews per user for a cohort.
ga:cohortRetentionRate	Cohort retention rate.
ga:cohortRevenuePerUser	Revenue per user for a cohort.
ga:cohortVisitDurationPerUser	Session duration per user for a cohort.
ga:cohortSessionsPerUser	Sessions per user for a cohort.

Lifetime value (LTV) metrics

Note: Lifetime value (LTV) requests are currently available only for app views.

Metric Name	Definition
ga:cohortTotalUsersWithLifetimeCriteria	This is relevant in the context of a request which has the dimensions ga:acquisitionTrafficChannel, ga:acquisitionSource, ga:acquisitionMedium, or ga:acquisitionCampaign. It represents the number of users in the cohorts who are acquired through the current channel, source, medium, or campaign. For example, for ga:acquisitionTrafficChannel=Direct, it represents the number users in the cohort, who were acquired directly. If none of the mentioned dimensions are present, then its value is equal to ga:cohortTotalUsers (app views only).
ga:cohortAppviewsPerUserWithLifetimeCriteria	App views per user for the acquisition dimension for a cohort (app views only).
ga:cohortGoalCompletionsPerUserWithLifetimeCriteria	Goal completions per user for the acquisition dimension for a cohort (app views only).
ga:cohortPageviewsPerUserWithLifetimeCriteria	Pageviews per user for the acquisition dimension for a cohort (app views only).
ga:cohortRevenuePerUserWithLifetimeCriteria	Revenue per user for the acquisition dimension for a cohort (app views only).
ga:cohortSessionsPerUserWithLifetimeCriteria	Session duration per user for the acquisition dimension for a cohort (app views only).