Developer Guide

This document describes how to use the Real Time Reporting API to get Google Analytics data.

Introduction

The Real Time Reporting API allows you to report activity that is occurring on your property right now. To access the real time data, you create a query that specifies a view (profile) and at least one metric. You may also supply additional query parameters such as dimensions and filters to refine your query. This query is sent to the Real Time Reporting API which returns the data in the form of a table.

If you are new to the API, read the Real Time Reporting API Overview for an introduction to the Real Time Reporting API and the data it provides.

Prerequisite

Before using the Real Time Reporting API to get Google Analytics data:

  • Read the client libraries page for a complete list of programming language specific client libraries that work with the API.
  • Read the Reference Guide to learn how to use the API alone (without using a client library) to get Google Analytics data.

Each client library provides a single analytics service object to access all Real Time Reporting API data. To create a service object:

  1. Register your application in the Google API Console.
  2. Authorize access to Google Analytics data.
  3. Create an Analytics service object.

If you haven't completed these steps, please stop and read the Hello Google Analytics API Tutorial, which walks you through the initial steps of building a Google Analytics API application. After that you know how to use the API to get Google Analytics data.

Using the Real Time Reporting API

To use the Real Time Reporting API, an application:

  1. Queries the Real Time Reporting API.
  2. Handles the API Response.

Querying the Real Time Reporting API

The analytics service object provides a method to build a Real Time Reporting API query. For details on the query parameters and data available to the API, read:

After you have defined a query, call its execute method to send the query to Google Analytics servers.

Handling the API Response

If a query to the Real Time Reporting API is successful, the API returns the requested data as part of a real time data resource. See the Real Time Reporting API reference for details on the API response structure and format.

If any errors occur, the API returns a specific status code and a message describing the error. All applications should catch and handle errors. See Error Responses for a detailed list of errors and retry recommendations.

Code Examples

The Examples section on the Real Time Data: get page provides sample code in various programming languages to query the Real Time Reporting API and handle the API response.

Query Constraints

These are the restrictions on Real Time API queries:

  • If the rt:activeUsers metric is included in a query with the following dimension filters, then only the AND operator and equality match type (==) are supported.
    • rt:goalId
    • rt:eventAction
    • rt:eventCategory
    • rt:eventLabel

    Because the rt:activeUsers metric retrieves only the number of users active on the site right now, don't use rt:minutesAgo with rt:activeUsers. That is, rt:activeUsers implies that rt:minutesAgo is 0.

  • There is no support for metric filters.
  • There is no support for the fields parameter.

Quota Management

As described in Limits and Quota, there are daily quotas for the Real Time Reporting API that are shared with other Google Analytics APIs. If you're polling the Real Time Reporting API at short intervals, you reach the daily quota limits very quickly. When that happens, requests from other Google Analytics APIs also stop working until the quota is refreshed.

Some example implementations that may use up quota very quickly are:

  • You have multiple realtime dashboards querying data for a single Google Analytics view (profile) at very short intervals on a daily basis.
  • You have a property with a lot of users and have implemented a real time widget. Each time the widget is displayed to a user, you are querying Google Analytics directly, instead of using a cache.

To minimize quota usage and manage it efficiently:

  • Implement server-side caching. When multiple users make a request for the same real time data, you should return a cached response instead of directly querying the Real Time Reporting API for each user's request. Then periodically refresh the cache with the latest real time data at a reasonable refresh interval to avoid exceeding the daily quota limits.
  • Combine multiple queries by specifying additional dimensions and parse the response on the server or client side.
  • Increase the time interval at which you're requesting real time data.

Example: Calculating a Refresh Interval

If you expect to make regular requests for real time data, you should select a reasonable refresh interval based on your expected usage.

For example, a single Google Analytics view (profile) has a daily quota limit of 10,000 requests per day. In a single day, if you expect to make 6,000 queries to the Core Reporting API for a single view (profile), then you will have a quota of 4,000 requests remaining for that view (profile).

Suppose you decide to use the Real Time Reporting API to implement 3 real time dashboards that run all day querying for real time data from the same view (profile). Each dashboard can make approximately 1,333 queries per day (4,000 queries / 3 dashboards). There are 86,400 seconds in a day. Thus the refresh interval for each dashboard must be greater than 65 seconds (86,400 / 1,333) so that the total number of daily requests for the view (profile) is below the 4,000 daily limit.