Creating a Report

This is a developer guide to the Analytics Reporting API v4. For a detailed reference of the API, see the API Reference.

Reports

The Analytics Reporting API v4 provides the batchGet method to access the Reports resource. The following sections describe the structure of the request body for batchGet and the structure of the response body from batchGet.

Request Body

To use the Analytics Reporting API v4 to request data, you must construct a ReportRequest object, which has these minimum requirements:

  • A valid view ID for the viewId field.
  • At least one valid entry in the dateRanges field.
  • At least one valid entry in the metrics field.

To find a view ID, query the account summaries method or use the Account Explorer. If a date range is not provided, the default date range is: {"startDate": "7daysAgo", "endDate": "yesterday"}.

Here is a sample request with the minimum required fields:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:users"}]
    }
  ]
}

The batchGet method accepts a maximum of five ReportRequest objects. All requests should have the same dateRange, viewId, segments, samplingLevel, and cohortGroup.

Response Body

The response body of the API request is an array of Report objects. The report structure is defined in the ColumnHeader object which describes the dimensions and metrics and their data types in the report. The values of the dimensions and metrics are specified in the data field.

Here is a sample response for the sample request above:

{
    "reports": [
        {
            "columnHeader": {
                "metricHeader": {
                    "metricHeaderEntries": [
                        {
                            "name": "ga:users",
                            "type": "INTEGER"
                        }
                    ]
                }
            },
            "data": {
                "isDataGolden": true,
                "maximums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "minimums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "rowCount": 1,
                "rows": [
                    {
                        "metrics": [
                            {
                                "values": [
                                    "98"
                                ]
                            }
                        ]
                    }
                ],
                "totals": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ]
            }
        }
    ]
}

Metrics

Metrics are quantitative measurements; every request requires at least one Metric object.

In the following example, the Sessions metric is supplied to the batchGet method to get the total number of sessions in the specified date range:

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

You can use the dimensions and metrics explorer or the Metadata API to get the list of available dimensions and metrics.

Filtering

When submitting a batchGet request, you can ask it to return only metrics that meet specific criteria. To filter metrics, in the request body, specify one or more MetricFilterClauses and in each MetricFilterClause, define one or more MetricFilters. In each MetricFilter, specify the values for the following:

  • metricName
  • not
  • operator
  • comparisonValue

Let {metricName} represents the metric, {operator} the operator, and {comparisonValue} the comparisonValue. Then the filter works as follows:

if {metricName} {operator} {comparisonValue}
   return the metric

If you specify true for not, then the filter works as follows:

if {metricName} {operator} {comparisonValue}
   do not return the metric

In the following example, batchGet returns only pageviews whose value is greater than 2:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "metricFilterClauses": [{
          "filters": [{
              "metricName": "ga:pageviews",
              "operator": "GREATER_THAN",
              "comparisonValue": "2"
          }]
      }]
  }]
}

Expressions

A metric expression is a mathematical expression you define on existing metrics; it operates like dynamic calculated metrics. You can define an alias to represent the metric expression, for example:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {
          "expression": "ga:goal1completions/ga:users",
          "alias": "completions per user"
        }
      ]
    }
  ]
}

Ordering

To sort the results by a metric value:

  • Supply its name or alias through the fieldName field.
  • Specify the sort order (ASCENDING or DESCENDING) through the sortOrder field.

In the following example, batchGet returns the metrics sorted first by sessions and then by pageviews in descending order:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "orderBys":
      [
        {"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
        {"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
      ]
    }
  ]
}

Dimensions

Dimensions describe characteristics of your users, their sessions and actions. The City dimension, for example, describes a characteristic of sessions and indicates the city ("Paris" or "New York") from which each session originated. In a batchGet request, you can specify zero or more dimension objects, for example:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges":
      [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics":
      [
        {"expression": "ga:users"}
      ],
      "dimensions":
      [
        {"name": "ga:city"}
      ]
    }
  ]
}

Filtering

When submitting a batchGet request, you can ask it to return only dimensions that meet specific criteria. To filter dimensions, in the request body, specify one or more DimensionsFilterClauses and in each DimensionsFilterClause, define one or more DimensionsFilters. In each DimensionsFilters, specify the values for the following:

  • dimensionName
  • not
  • operator
  • expressions
  • caseSensitive

Let {dimensionName} represents the dimension, {operator} the operator, and {expressions} the expressions. Then the filter works as follows:

if {dimensionName} {operator} {expressions}
    return the dimension

If you specify true for not, then the filter works as follows:

if {dimensionName} {operator} {expressions}
    do not return the dimension

In the following example, batchGet returns pagesviews and sessions in a Chrome browser:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
      "dimensionFilterClauses": [
        {
          "filters": [
            {
              "dimensionName": "ga:browser",
              "operator": "EXACT",
              "expressions": ["Chrome"]
            }
          ]
        }
      ]
    }
  ]
}

Ordering

To sort the results by a dimension value:

  • Supply its name through the fieldName field.
  • Specify the sort order (ASCENDING or DESCENDING) through the sortOrder field.

For example, the following batchGet returns the dimensions sorted by country and then by browser:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
      "orderBys": [
        {"fieldName": "ga:country"},
        {"fieldName": "ga:browser"}
      ]
    }
  ]
}

Histogram buckets

For dimensions with integer values, it is easier to understand their characteristics by bucketing their values into ranges. Use the histogramBuckets field to define the ranges for the resultant buckets and specify HISTOGRAM_BUCKET as the order type, for example:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [
        {
          "name": "ga:sessionCount",
          "histogramBuckets": ["1","10","100","200","400"]
        }
      ],
      "orderBys": [
        {
          "fieldName": "ga:sessionCount",
          "orderType": "HISTOGRAM_BUCKET"
        }
      ]
    }
  ]
}

Multiple Date Ranges

The Google Analytics Reporting API v4 allows you to get data in multiple date ranges in a single request. Whether your request specifies one or two date ranges, the data is returned in the dateRangeValue object, for example:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}]
    }
  ]
}

Delta ordering

When requesting metric values in two date ranges, you can order the results by the difference between the values of the metric in the date ranges, for example:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}],
      "orderBys": [
        {
          "fieldName": "ga:sessions",
          "orderType": "DELTA"
        }
      ]
    }
  ]
}

Date dimension behavior

If you request a date or time related dimension, the DateRangeValue object will hold only values for the dates that fall within the respective ranges; all other values not in the specified date ranges will be 0.

For example, consider a request for the ga:date dimension and the ga:sessions metric in two date ranges: January and February. In the response for the requested data in January, values in February will be 0; and in the response for the requested data in February, values in January will be 0.

January report

{
    "dimensions": [
        "20140101" # `ga:date` dimension value for January 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "8"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "0"
            ]
        }
    ]
},
...

February report

{
    "dimensions": [
        "20140201"  # `ga:date` dimension value for February 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "0"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "7"
            ]
        }
    ]
},
...

Segments

To request a subset of your Analytics data, use segments. For example, you can define users from a particular country or city in one segment, and users who visit a specific part of your site in another. Filters return only rows that satisfy a condition, whereas segments return subset of users, sessions, or events that meet the conditions containing the segments.

When making a request with segments, ensure that:

  • Every ReportRequest within a batchGet method must contain identical segment definitions.
  • You add ga:segment to the list of dimensions.

For example:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
      "metrics": [{"expression": "ga:sessions"}],
      "segments": [
        {
          "dynamicSegment":
          {
            "name": "Sessions with Safari browser",
            "userSegment":
            {
              "segmentFilters": [
                {
                  "simpleSegment":
                  {
                    "orFiltersForSegment": [
                      {
                        "segmentFilterClauses": [
                          {
                            "dimensionFilter":
                            {
                              "dimensionName": "ga:browser",
                              "operator": "EXACT",
                              "expressions": ["Safari"]
                            }
                        }]
                    }]
                  }
              }]
            }
          }
      }]
  }]
}

See Samples for more example requests with segments.

Segment ID

Use the segmentId field to request segments. You cannot use both a segmentId and a dynamicSegment to request segments.

For example:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
      "metrics": [{"expression": "ga:users"}],
      "segments":  [{"segmentId": "gaid::-3"}]
    }
  ]
}

Sampling

Sampling can affect the results of your data and is a common reason why the values returned from the API do not match the web interface. Use the samplingLevel field to set the desired sample size.

  • Set the value to SMALL for a fast response with a smaller sampling size.
  • set the value to LARGE for a more accurate but slower response.
  • set the value to DEFAULT for a response that balances speed and accuracy.

For example:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}],
      "metrics": [{"expression": "ga:sessions"}],
      "samplingLevel":  "LARGE"
    }
  ]
}

if a report contains sampled data the Analytics Reporting API v4 returns the samplesReadCounts and the samplingSpaceSizes fields. If the results are not sampled these fields will not be defined.

Below is an example response which contains sampled data from a request with two date ranges. The results were calculated from almost 500k samples of a sampling space size of approximately 15 million sessions:

{
  "reports":
  [
    {
      "columnHeader": {
        ...
      },
      "data": {
        ...
        "samplesReadCounts": [ "499630","499630"],
        "samplingSpaceSizes": ["15328013","15328013"],
      }
    }
  ]
}

Pagination

The Analytics Reporting API v4 uses the pageToken and pageSize fields to paginate through response results that span multiple pages. You get pageToken from the nextPageToken parameter in the response to the reports.batchGet request:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    # Taken from `nextPageToken` of a previous response.
    "pageToken": "10000",
    "pageSize": "10000",
  }]
}

Next step

Now that you have covered the basics of creating a report, take a look at API v4's advanced features.