This is an overview of the capabilities of the Analytics Data API v1. For a detailed reference of the API, see the API Reference.
Reports
Reports are tables of event data for a GA4 Property. Tables have rows and columns. The columns in each report are the Dimensions and Metrics from the Report's API request. Rows are selected by Filters and Pagination.
The following is an example report table.
| Country | Active Users |
|---|---|
| Japan | 2541 |
| France | 12 |
Report Request
To use the Analytics Data API v1 to request data, you can construct a RunReportRequest object. We recommend starting with these request parameters:
- A valid property ID for the propertyId field.
- A valid entry in the dateRanges field.
- At least one valid entry in the dimensions field.
- At least one valid entry in the metrics field.
Here is a sample request with the recommended fields:
POST https://analyticsdata.googleapis.com/v1alpha:runReport
{
"entity": { "propertyId": "XXXX" },
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
Report Response
The Report Response of the API request is primarily a header and rows. The header consists of DimensionHeaders and MetricHeaders which list the columns in the Report. Each row consists of DimensionValues and MetricValues for the columns in the report. The ordering of columns is consistent in the request, the header, and every row.
Here is a sample response for the sample request above:
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "2541"
}
]
},
{
"dimensionValues": [
{
"value": "France"
}
],
"metricValues": [
{
"value": "12"
}
]
}
],
"metadata": {},
"rowCount": 2
}
Dimensions
Dimensions describe and group event data for your
website or app. The city dimension, for example, indicates the city ("Paris"
or "New York") from which each event originated. In a report request, you can
specify zero or more dimensions. See the API Dimensions
for a full list of API Dimension names available to be specified in requests.
For example, this request groups Active Users in three dimension columns:
POST https://analyticsdata.googleapis.com/v1alpha:runReport
{
"entity": { "propertyId": "XXXX" },
"dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
"dimensions": [
{
"name": "country"
},
{
"name": "region"
},
{
"name": "city"
}
],
"metrics": [{ "name": "activeUsers" }]
}
As a sample, a row in the report response could contain the following. This row means there are 47 Active Users for your website or app for the date range with events from Cape Town, South Africa.
"rows": [
...
{
"dimensionValues": [
{
"value": "South Africa"
},
{
"value": "Western Cape"
},
{
"value": "Cape Town"
}
],
"metricValues": [
{
"value": "47"
}
]
},
...
],
Metrics
Metrics are quantitative measurements of event data for your website or app. In a report request, you can specify one or more metrics. See the API Metrics for a full list of API Metric names available to be specified in requests.
For example, this request will show the three metrics grouped by the dimension
date:
POST https://analyticsdata.googleapis.com/v1alpha:runReport
{
"entity": { "propertyId": "XXXX" },
"dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "date" }],
"metrics": [
{
"name": "activeUsers"
},
{
"name": "newUsers"
},
{
"name": "totalRevenue"
}
],
}
As a sample, a row in report response could contain the following. This row
means that for the date 20201025 (October 25, 2020), there are 1135 Active
Users, 512 New Users, and 73.0841 Total Revenue in your Analytics property's
currency.
"rows": [
...
{
"dimensionValues": [
{
"value": "20201025"
}
],
"metricValues": [
{
"value": "1135"
},
{
"value": "512"
},
{
"value": "73.0841"
}
]
},
...
],
Pagination
By default, the report response contains at most the first 10,000 rows of event
data. For reports with 10,000 to 100,000 rows, you can include "limit": 100000
in the RunReportRequest
to retrieve up to 100,000 rows.
For reports with more than 100,000 rows, it is necessary to send a sequence of requests paging through the rows. For example, this request is for the first 100,000 rows:
POST https://analyticsdata.googleapis.com/v1alpha:runReport
{
...
"limit": 100000,
"offset": 0
}
The rowCount parameter in the report response is independent of the
pagination parameters limit and offset in the request. If the report
response for example contains "rowCount": 272345, three requests of 100,000
rows each will retrieve all the data.
This request is for the second 100,000 rows. All other parameters such as
dateRange, dimensions, and metrics should be the same as the first
request.
POST https://analyticsdata.googleapis.com/v1alpha:runReport
{
...
"limit": 100000,
"offset": 100000
}
This request is for the third 100,000 rows. Again, all other parameters such as
dateRange, dimensions, and metrics should be the same as the first
request.
POST https://analyticsdata.googleapis.com/v1alpha:runReport
{
...
"limit": 100000,
"offset": 200000
}
Dimension Filters
When submitting a report request, you can ask it to only return data for
specific dimension values. To filter dimensions, in the request body, specify a
FilterExpression in the dimensionFilter
field. For example, this request returns a time series report of eventCount
when eventName is first_open for each date :
POST https://analyticsdata.googleapis.com/v1alpha:runReport
{
"entity": { "propertyId": "XXXX" },
"dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "date" }],
"metrics": [{ "name": "eventCount" }],
"dimensionFilter": {
"filter": {
"fieldName": "eventName",
"stringFilter": {
"value": "first_open"
}
}
},
}
The FilterExpression can specify filtering
criteria for many use cases. For example, an andGroup includes only data that
meets all criteria in the expressions list. This dimensionFilter selects for
when both browser is Chrome and countryId is US:
"dimensionFilter": {
"andGroup": {
"expressions": [
{
"filter": {
"fieldName": "browser",
"stringFilter": {
"value": "Chrome"
}
}
},
{
"filter": {
"fieldName": "countryId",
"stringFilter": {
"value": "US"
}
}
}
]
}
},
An orGroup includes data that meets any of the criteria in the expressions
list.
A notExpression excludes data that matches its inner expression. This
dimensionFilter selects for when pageTitle is not My Homepage. The report
will show event data for every pageTitle other than My Homepage:
"dimensionFilter": {
"notExpression": {
"filter": {
"fieldName": "pageTitle",
"stringFilter": {
"value": "My Homepage"
}
}
}
},
Multiple Date Ranges
One report request can retrieve data for multiple dateRanges. For example, this report compares the first two weeks for August in 2019 and 2020:
POST https://analyticsdata.googleapis.com/v1alpha:runReport
{
"entity": { "propertyId": "XXXX" },
"dateRanges": [
{
"startDate": "2019-08-01",
"endDate": "2019-08-14"
},
{
"startDate": "2020-08-01",
"endDate": "2020-08-14"
}
],
"dimensions": [{ "name": "platform" }],
"metrics": [{ "name": "activeUsers" }]
}
When multiple dateRanges are included in a request, a dateRange column is
automatically added to the report response. The following is an example
response. When the dateRange column is date_range_0, that row's data is for
the first date range. When the dateRange column is date_range_1, that row's
data is for the second date range.
{
"dimensionHeaders": [
{
"name": "platform"
},
{
"name": "dateRange"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "iOS"
},
{
"value": "date_range_0"
}
],
"metricValues": [
{
"value": "774"
}
]
},
{
"dimensionValues": [
{
"value": "Android"
},
{
"value": "date_range_1"
}
],
"metricValues": [
{
"value": "335"
}
]
},
...
],
}
Next step
Now that you have covered the basics of creating a report, take a look at the advanced features.