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.

Creating a Report

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:

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.