This document provides an overview of the Google Analytics Core Reporting API Version 2.4. For a detailed reference, see the Data Feed Reference.
Version 2.4 of the Core Reporting API is an XML-only API that is mostly backwards compatible with version 2.3. With it, you can continue to use the existing XML Feeds and Google Data client libraries. Changes from version 2.3 to version 2.4 include the following:
- Application registration is required.
- The base URL has changed:
- OAuth 2.0 is the recommend authorization mechanism.
- Error messages contain more specific details.
Quota Deniederror code has been changed from 503 to 403.
Note: We strongly recommend migrating to Version 3.0 because all upcoming features will be only added to that version. While Version 2.4 allows you to continue using the XML feeds, Version 3.0 provides responses in a new, compact JSON format.
Before You Begin
Before you begin using the Core Reporting API, there are a couple of things you need to do.
Sign up for Google Analytics
To use the Core Reporting 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
All requests sent to the Core Reporting API must belong to an application registered through the Google API Console. When you register your application though the console, you will receive a token which must be used in every API request. Depending on how your users authorize access to your applications, there are different ways to send the registration token:
- OAuth 2.0 – If you use the recommended
OAuth 2.0 authorization mechanism, your authorization
Client Secretare used in place of registration credentials to identify your application.
- Legacy Mechanisms – If you use legacy
authorization mechanisms, like OAuth 1.0, AuthSub, or ClientLogin,
you use the value of the application key as the value
keyquery parameter. This key value is found in the console, and you'll need to use it in each API request.
Note: We recommended that you use the same registration credentials between both Data Export and Management API requests.
We strongly recommend that your application use OAuth 2.0 because it's safer for users and easier for developers to implement. See the authorization guide for all the supported authorization mechanisms supported in version 2.4.
- OAuth 2.0 – If you use the recommended OAuth 2.0 authorization mechanism, your authorization
This section lists the steps required for your application to use the Core Reporting API. Any application must do these steps, regardless of the language it is written in.
Before users can view their data through the Google Analytics web site, they must first log in with a Google Account. Similarly, when users access their Analytics data through your application, they must grant your application access to that data. This step is called application authorization. The Authorization guide document describes how to do this.
Get a view (profile) ID for the authorized user
All reporting in Google Analytics is done at the view (profile) level. A view (profile) configured through the web interface. When you request report data through the Core Reporting API, each query must specify a view (profile) ID to identify which of the user's views (profiles) to use.
If a user already knows their view (profile) ID, they can directly supply the ID to your application. Alternatively, you can query the Management API to access all the view (profile) IDs that exist for the authenticated user. Once you have a view (profile) ID, your application or the user can re-use the ID in subsequent requests.
Query the Core Reporting API
The heart of your application consists of Data Export API queries and reports. You can use this data to build custom reports and visualizations, or to import this data into a corporate data warehouse. Each Core Reporting API query specifies a list of values called dimensions and metrics. The query also supports a rich set of operations to refine the returned data. See the Dimensions and Metrics list to learn more about all the data exposed in the Core Reporting API. See the reference for version 2.4 to learn the syntax you can use when querying for data and handling responses.
Quota and Deprecation Policies
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.
For details on how changes to Core Reporting API columns (i.e. dimensions and metrics) are handled, read the Data Deprecation Policy. To learn how the Metadata API can be used to check for deprecated columns, see the Metadata API Dev Guide.
If you have developed your application on Version 2.3 of the Google Analytics Data Export API, it should continue to work on Version 2.4 of the Core Reporting API. If you are using the protocol to develop your application, it is important that you adhere to the "XML Parsing Guidelines" indicated in the Protocol guide to minimize conflicts between versions of our API. If you are using a client library to develop your application, versioning between minor versions is automatically handled for you by the client library.