This document provides a high level overview of the Google Analytics Management API Version 2.4. It is intended for developers of applications that use the Management API for read-only retrieval of Analytics configuration data.
Version 2.4 of the Management API is a XML-only API with a few changes over the deprecated Management API Version 2.3. Version 2.4 is mostly backwards compatible with 2.3 and lets you continue to use the existing XML Feeds and Google Data client libraries. Changes from Version 2.3 to Version 2.4 include the following:
- You must register your application.
- The base URL has been changed from:
- Although Version 2.4 supports all the same authorization methods as Version 2.3, we recommend that you use OAuth 2.0 as described in Using OAuth 2.0 to Access Google APIs.
- Version 2.4 is much faster than Version 2.3.
- Error messages have been improved.
- The HTTP error code for Quota Denied errors has been changed from 503 to 403.
Before You Begin
Sign up for Google Analytics — To use the Analytics Management API, you need access to an existing Google Analytics account. If you don't yet have a Google Analytics account, sign up for one now. Analytics uses Google Accounts, so if you already have a Google Account, you can use that ID to set up an Analytics account.
Migrating from v2.3 — If you are migrating from v2.3 APIs, see the Migration Guide
Register your Application — All requests to the Google Analytics Management API must be authorized by an authenticated user. Version 2.4 supports OAuth 2.0 as the authorization mechanism. As a developer you must register your application in the Google Developers Console and register for an OAuth 2.0 token before you can make authorized requests to the API.
Authorization. Version 2.4 of the Management API supports both OAuth 1.0 and 2.0 authorization mechanisms in addition to the mechanisms supported by Version 2.3. We strongly recommend that your application use OAuth 2.0. It is simpler to use than OAuth 1.0. It supports more fine-grained scope codes that let users limit applications' access to exactly the data they need. Fine-grained scoping helps applications gain users' trust in the privacy of their data. You can read more in the OAuth 2.0 for Google APIs documentation. Consult Authorization for a full description of the authorization methods supported by Version 2.4.
Feed Retrieval Basics
The following steps summarize the process your application should follow in order to retrieve data using the Management API feeds.
It is important to understand the relationship between a user's Analytics accounts, web properties, views (profiles), goals, and segments. After reading the documentation on Accounts & Views (Profiles), Goals, and Segments, you can better understand how to request specific data using feeds in Management API.
Users who access your application must be logged in to Analytics. Typically, your application will ask them to supply their login credentials by logging in with their Google Accounts email and password. For example:
email@example.com. To learn more about authorization, read the authorizaton section for each client language guide, or for complete details, see the Authorization guide.
- Querying the Management API
Once your application has verified that the user has Analytics access, it can request data for accounts, web properties, views (profiles), goals, or segments that the user has access to. There is a separate feed for each data type, and the resulting feed returns the data from the entities available to that user. For example, the view (profile) feed returns the list of views (profiles) available to the user for the indicated account(s). For more information on the feeds available in the Management API and how to construct a feed query, see the Feed Reference.
- Requesting data by ID or requesting
~alldata for the user
The Management API provides a way to request data for a specific entity (e.g. a user's specific account or view (profile)), or to request all the entities of a particular data type (e.g. all the user's accounts or views (profiles)).
By ID: The web property, view (profile), and goal feeds can be retrieved using a specific ID for its parent entity. For example, a web property ID might look like
UA-12345-1. Using these IDs reduces the time it takes for the API to find all the Analytics data, which in turn speeds up the response time. Using an ID also makes it easier for your application to retrieve only important information, like goal names for a particular view (profile). Because data queries are formed in a hierarchy, if you want to specify an ID for a child entity, you must also specify the ID of the parent entity for that child.
~all. You can also use the special identifier
~allin place of an ID to request all the data available for the user for that query. If you do use the
~allidentifier, any subsequent children for that element must use the
~allidentifier as well.
~allto retrieve all data is slow. For users with many accounts and many views (profiles), a response can take a longer time to return. Generally you should provide a way for end users to supply a specific ID for an entity to help filter the results and speed up the response.
- Using the Management API with the Export API
The view (profile) feed gives your application access to all the views (profiles) that the user has access to, and each view (profile) entry contains a tableId that your application can use in order to access the data for that view (profile) using the Core Reporting API.
The Google Analytics API handles millions of operations. To protect the system from receiving more operations than it can handle, and to ensure an equitable distribution of system resources, it is necessary to employ a quota system. Read the Limits and Quotas guide for specific limits.