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
orDESCENDING
) through thesortOrder
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
orDESCENDING
) through thesortOrder
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.