This document explains important concepts about using the Real Time Reporting API to access Google Analytics data.
The Real Time Reporting API allows you to report on activity that is occurring on your property right now. To access data, you create a query that specifies: the 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 will return 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.
Before You Begin
All Google Analytics APIs are accessed in a similar manner. Before you begin with the Real Time Reporting API you should:
- 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 about the API interface and accessing data without a client library.
Each client library provides a single analytics service object to access all Real Time Reporting API data. To create the service object you generally have to go through the following steps:
- Register your application in the Google Developers Console.
- Authorize access to Google Analytics data.
- Create an Analytics service object.
If you haven't completed these steps, please stop and read the Hello Google Analytics API Tutorial. This tutorial will walk you through the initial steps of building a Google Analytics API application. Once complete, you will understand how to access Google Analytics APIs to perform real-world tasks.
An application that uses the Real Time Reporting API will generally follow 2 steps:
- Query the Real Time Reporting API
- Handle the API Response
Query the Real Time Reporting API
The analytics service object contains a method to build a Real Time Reporting API query. For details on the query parameters and data available through the API see the:
Real Time Reporting API reference for a complete listing of all the
query parameters for the
getmethod of the Real Time Reporting API.
- Standard Query Parameters reference for a list of query parameters that can be used with all methods and resources.
- Dimensions and metrics reference page for a list of what data can be retrieved from Google Analytics.
Once you have a query defined, you call it's
to send the query to Google Analytics servers.
Handle the API Response
If a query to the Real Time Reporting API is successful, the API will return 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 will return a specific status code and a message describing the error. All applications should properly catch and handle errors. See Error Responses for detailed list of errors and retry recommendations.
For examples on how to query the Real Time Reporting API and handle the API response, see the Examples section of the Real-Time Reporting API reference for sample code in various programming languages
There are a few specific restrictions when constructing Real Time API Queries:
rt:activeUsersmetric is included in a query with the following dimension filters, then only the
ANDoperator and equality match type (
==) are supported.
rt:activeUsersmetric retrieves only the number of users active on the site right now, don't use
rt:activeUsers. That is,
- There is no support for metric filters.
- There is no support for the
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 this can cause you to reach daily quota limits very quickly. When that happens requests from other Google Analytics APIs will 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 and efficiently manage quota usage:
- 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 request. Then periodically refresh the cache with the latest real time data at a reasonable refresh interval that will stay within the daily limits for your expected usage.
- Combine multiple queries by specifying additional dimensions and then parsing the response either 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/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).
Now you decide to use the Real Time Reporting API to implement 3 real time dashboards that will run all day and query for real time data for the same view (profile). Each dashboard can make approximately 1333 queries/day (4000 queries / 3 dashboards). There are 86,400 seconds per day so that means the refresh interval for each dashboard should be greater than 65 seconds (86400 / 1333) to stay below 4,000 requests and stay within the daily limit for the view (profile).