Take our developer survey. We want your feedback so we can learn how to improve Google Analytics, and make it an even better tool for you.

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.

Introduction

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

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"
            }
          ]
        }
      ]
    }
  ]
}

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.

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.

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

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).