Analytics Data API Overview

Developer Trusted Testing Preview

Summary: This document provides a high level overview of the Google Analytics Data API V1.

Introduction

The Google Analytics Data API V1 provides programmatic methods to access report data in Google Analytics 4 (GA4) properties. Learn more about GA4 properties.

With the Google Analytics Data API V1, you can:

  • Build custom dashboards to display Google Analytics data.
  • Automate complex reporting tasks to save time.
  • Integrate your Google Analytics data with other business applications.

Available methods

  • runReport This method returns a customized report of your Google Analytics event data. It does not support pivot functionality and is a preferred method for simple report queries.
  • runPivotReport This method returns a customized pivot report of you Google Analytics event data. Pivot reports are more advanced and expressive formats than regular reports. Each pivot describes the visible dimension columns and rows in the report response.
  • batchRunReports This is a batch version of the runReport method which allows generating multiple reports using a single API call.
  • batchRunPivotReports This is a batch version of the runPivotReport method which allows generating multiple reports using a single API call.
  • getMetadata This method returns metadata for dimensions and metrics available in reporting methods. Used to explore the dimensions and metrics. The response of this method also includes the Custom dimensions and metrics available for the specified GA4 property.
  • runRealtimeReport This method returns a customized report of your Google Analytics Realtime event data. Realtime reports show traffic for the last 30 minutes on your website or app.

Enable the API

Click this button to automatically enable the Google Analytics Data API V1:

Enable the Google Analytics Data API V1

Quick start guide

Quick start using client libraries

API discovery document

Use the following endpoint to query the Analytics Data API discovery document:

https://analyticsdata.googleapis.com/$discovery/rest?version=v1alpha

Client libraries

See the Quick start guide for examples of using the client libraries.

Java

If you are using Maven, add this to your pom.xml file:

<dependency>
  <groupId>com.google.analytics</groupId>
  <artifactId>google-analytics-data</artifactId>
  <version>0.1.0</version>
</dependency>

If you are using Gradle, add this to your dependencies
compile 'com.google.analytics:google-analytics-data:0.1.0'

Python

Install this library in a virtualenv using pip. virtualenv is a tool to create isolated Python environments. The basic problem it addresses is one of dependencies and versions, and indirectly permissions.

With virtualenv, it’s possible to install this library without needing system install permissions, and without clashing with the installed system dependencies.

pip install virtualenv
virtualenv 
source <your-env>/bin/activate
<your-env>/bin/pip install google-analytics-data

Node.js

npm install @google-analytics/data

Ruby

gem install google-analytics-data-v1alpha

Go

go get -u cloud.google.com/go/analytics/data/apiv1alpha

.NET

If you are using Package Manager, execute this command:

Install-Package Google.Analytics.Data.V1Alpha -Version 1.0.0-alpha01
If you are using .NET CLI, execute this command in your project's folder:
dotnet add package Google.Analytics.Data.V1Alpha --version 1.0.0-alpha01
You can directly include the library dependency to your project by adding this to your .NET project file:

<PackageReference Include="Google.Analytics.Data.V1Alpha" Version="1.0.0-alpha01" />

Supported dimensions and metrics

The API schema documentation lists the dimensions and metrics currently supported by the Analytics Data API.

Changelog

  • 2020-10-08 Custom dimensions and metrics are available in reports. See the API schema documentation for documentation on custom dimensions and metrics. This update includes Event-scoped Custom Dimensions and metrics as well as User-scoped Custom Dimensions.

  • 2020-10-08 getMetadata method added to the API. This method returns Custom dimensions and metrics available for the specified GA4 property ID, as well as Universal metadata.

  • 2020-10-13 App + Web properties have been renamed to Google Analytics 4 (GA4).

  • 2020-10-19 Client library artifacts updated along with usage instructions and code samples.

  • 2020-11-02 Added a Realtime Reporting Method. See the Creating a Realtime Report for examples and runRealtimeReport for the REST reference documentation.

  • 2020-11-09 The method getUniversalMetadata has been deleted. Please use getMetadata. The one year maximum date range per API request has been removed.