Create a report

  • The Google Analytics Data API v1 allows you to create basic reports similar to the Google Analytics UI using the runReport method.

  • Reports are tables containing dimensions and metrics, which can be filtered and paginated.

  • To generate a report, you need to specify a property ID and include date ranges, at least one dimension, and at least one metric in your request.

  • You can use up to nine dimensions to group and filter your data, applying inclusion and exclusion criteria.

  • Pagination using limit and offset parameters allows retrieving more than the default 10,000 rows, and multiple date ranges can be included for comparison.

This guide explains how to create a basic report for your Analytics data using the Google Analytics Data API v1. Reports from the Data API v1 are similar to the reports you can generate in the Reports section of the Google Analytics UI.

This guide covers core reporting, the general reporting feature of the Data API. The Data API v1 also has specialized Realtime reporting and Funnel reporting.

runReport is the recommended method for queries, and is used in all examples throughout this guide. See advanced features for an overview of other core reporting methods. Try the Query Explorer to test your queries.

Reports overview

Reports are tables of event data for a Google Analytics property. Each report table has the dimensions and metrics requested in your query, with data in individual rows.

Use filters to return only rows matching a certain condition, and pagination to navigate through results.

Here's a sample report table that shows one dimension (Country) and one metric (activeUsers):

Country Active Users
Japan 2541
France 12

Specify a data source

Every runReport request requires you to specify a Google Analytics property ID. The Analytics property you specify is used as the dataset for that query. Here's an example:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport

The response from this request includes only data from the Analytics property you specify as the GA_PROPERTY_ID.

If you use the Data API client libraries, specify the data source in the property parameter, in the form of properties/GA_PROPERTY_ID. See the quick start guide for examples of using the client libraries.

See Send Measurement Protocol events to Google Analytics if you want to include Measurement Protocol events in your reports.

Generate a report

To generate a report, construct a RunReportRequest object. We recommend starting with the following parameters:

  • 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's a sample request with the recommended fields:

HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
  {
    "dateRanges": [{ "startDate": "2023-09-01"", "endDate": "2023-09-15" }],
    "dimensions": [{ "name": "country" }],
    "metrics": [{ "name": "activeUsers" }]
  }

Java

google-analytics-data/src/main/java/com/google/analytics/data/samples/RunReportSample.java
Open in Cloud Shell View on GitHub 
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient;
import com.google.analytics.data.v1beta.DateRange;
import com.google.analytics.data.v1beta.Dimension;
import com.google.analytics.data.v1beta.DimensionHeader;
import com.google.analytics.data.v1beta.Metric;
import com.google.analytics.data.v1beta.MetricHeader;
import com.google.analytics.data.v1beta.Row;
import com.google.analytics.data.v1beta.RunReportRequest;
import com.google.analytics.data.v1beta.RunReportResponse;

/**
 * Google Analytics Data API sample application demonstrating the creation of a basic report.
 *
 * <p>See
 * https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport
 * for more information.
 *
 * <p>Before you start the application, please review the comments starting with "TODO(developer)"
 * and update the code to use correct values.
 *
 * <p>To run this sample using Maven:
 *
 * <pre>{@code
 * cd google-analytics-data
 * mvn compile exec:java -Dexec.mainClass="com.google.analytics.data.samples.RunReportSample"
 * }</pre>
 */
public class RunReportSample {

  public static void main(String... args) throws Exception {
    /**
     * TODO(developer): Replace this variable with your Google Analytics 4 property ID before
     * running the sample.
     */
    String propertyId = "YOUR-GA4-PROPERTY-ID";
    sampleRunReport(propertyId);
  }

  // Runs a report of active users grouped by country.
  static void sampleRunReport(String propertyId) throws Exception {

    // Using a default constructor instructs the client to use the credentials
    // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
    try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
      RunReportRequest request =
          RunReportRequest.newBuilder()
              .setProperty("properties/" + propertyId)
              .addDimensions(Dimension.newBuilder().setName("country"))
              .addMetrics(Metric.newBuilder().setName("activeUsers"))
              .addDateRanges(
                  DateRange.newBuilder().setStartDate("2020-09-01").setEndDate("2020-09-15"))
              .build();

      // Make the request.
      RunReportResponse response = analyticsData.runReport(request);
      printRunResponseResponse(response);
    }
  }

  // Prints results of a runReport call.
  static void