Google Analytics

Migration Guide: Moving from v2.3 APIs to v2.4 & v3.0

This article provides a set of guidelines to migrate from v2.3 to v2.4 of the Management and/or Core Reporting API. It also includes considerations for moving to v3.0.

  1. Introduction
  2. Overview
    1. 1. Register Application
    2. 2. Identify API requests
  1. Resources
  2. Differences between v2.4 and v3.0
  1. FAQs
  2. Summary
    1. API Version Reference
    2. Auth Tokens & Expected Responses
    3. Migration Guidelines Summary

Introduction

If your application currently uses v2.3 APIs, it is important that you migrate to either v2.4 or v3.0 so that your application continues to work.

Take a few minutes to review the following information:
  • Management API v2.3 has been shutdown. Queries made to this API endpoint automatically return a Management API v2.4 response.
  • Data Export API v2.3 is deprecated and will be shut down around by the end of July 2012, at which point any queries made to that API endpoint will return a Core Reporting API v2.4 response.

If you are new to Google Analytics APIs, it is recommended to use v3.0 APIs and OAuth 2.0 for authentication.

Overview

Making the move from v2.3 to v2.4 is a simple process that involves the following steps:

  1. Register your application using the Google Developers Console. This will be used to identify your application when making requests to the Analytics API.
  2. Identify API requests by associating them with a project

1. Register Application in the Google Developers Console

If you haven't already registered your application with the Google Developers Console, then set up a project and application in the Developers Console. The system guides you through the process of choosing or creating a project and registering a new application, and it automatically activates the API for you.

If you've already registered your application with the Developers Console, then follow this procedure instead:

  1. Go to the Google Developers Console.
  2. Select a project.
  3. In the sidebar on the left, select APIs & auth. In the list of APIs, make sure the status is ON for the Analytics API.
  4. In the sidebar on the left, select Credentials.

In either case, you end up on the application's credentials page.

If using OAuth v2.0 for authentication purposes:

To find your application's client ID and client secret, and set a redirect URI, expand the OAuth 2.0 Client ID section.

While we recommend that you use OAuth v2.0, if you are still using OAuth 1.0, AuthSub, or ClientLogin for authentication, an API Key is required:

To find your application's API key, expand the Browser Key or Server Key sections.

2. Identify API Requests

When you make a request to Management or Core Reporting API, you need to associate each request with a project registered in the Developers Console. The two ways to associate requests with a project depend on the authentication method.

OAuth 2.0 Authentication:

To authenticate and gain access to a Google Analytics account requires the use of a OAuth 2.0 Client ID and Client Secret. Because these are already associated with an Developers Console project, all API requests will be identified. No further action is required on your part.

OAuth 1.0, AuthSub, or ClientLogin Authentication:

To identify an application, include the API Key as a parameter with each API request. key=API_key where API_key is the API Key obtained from the Developers Console.

Examples

The following examples illustrate how to identify API requests with an API Key.

REST Examples

Data Export v2.3

Before: Unidentified request
https://www.google.com/analytics/feeds/data?ids=ga:XXXX&dimensions=ga:date&metrics=ga:sessions&start-date=2012-04-01&end-date=2012-04-02

After: API Key associated with Request
https://www.google.com/analytics/feeds/data?ids=ga:XXXX&dimensions=ga:date&metrics=ga:sessions&start-date=2012-04-01&end-date=2012-04-02&key=API_key

Core Reporting v2.4
Before: Unidentified request
https://www.googleapis.com/analytics/v2.4/data?ids=ga:XXXX&dimensions=ga:date&metrics=ga:sessions&start-date=2012-04-01&end-date=2012-04-02

After: API Key associated with Request
https://www.googleapis.com/analytics/v2.4/data?ids=ga:XXXX&dimensions=ga:date&metrics=ga:sessions&start-date=2012-04-01&end-date=2012-04-02&key=API_key
Management API v2.4
Before: Unidentified request
https://www.googleapis.com/analytics/v2.4/management/accounts

After: API Key associated with Request
https://www.googleapis.com/analytics/v2.4/management/accounts?key=API_key

Java Examples

Data Export v2.3
//Setup the query as usual
DataQuery query = new DataQuery(new URL("https://www.google.com/analytics/feeds/data"));
query.setIds("ga:XXXXX");
query.setStartDate("2012-01-01");
query.setEndDate("2012-01-02");
query.setDimensions("ga:browser");
query.setMetrics("ga:sessions,ga:bounces");

//Add a custom parameter for the API Key
query.setStringCustomParameter("key", API_key);

DataFeed dataFeed = myAnalyticsService.getFeed(query, DataFeed.class);
            
Core Reporting API v2.4
//Setup the query as usual
DataQuery query = new DataQuery(new URL("https://www.googleapis.com/analytics/v2.4/data"));
query.setIds("ga:XXXXX");
query.setStartDate("2012-01-01");
query.setEndDate("2012-01-02");
query.setDimensions("ga:browser");
query.setMetrics("ga:sessions,ga:bounces");

//Add a custom parameter for the API Key
query.setStringCustomParameter("key", API_key);

DataFeed dataFeed = myAnalyticsService.getFeed(query, DataFeed.class);
            
Management API v2.3
//Append the API key to the request
queryURL = new URL("https://www.google.com/analytics/feeds/datasources/ga/accounts?key=" + API_key);
ManagementFeed accountsFeed = myAnalyticsService.getFeed(queryURL, ManagementFeed.class);
            

Management API v2.4
//Append the API key to the request
queryURL = new URL("https://www.googleapis.com/analytics/v2.4/management/accounts?key=" + API_key);
ManagementFeed accountsFeed = myAnalyticsService.getFeed(queryURL, ManagementFeed.class);
            
Data Export v2.3 - Account Feed
The Account Feed is not available through the Core Reporting API. Update your application to use the Management API instead.

Resources

More information about the Google Developers Console and how it is used to identify an application:

Differences between v2.4 and v3.0

Core Reporting API

Version 3.0

  • The Core Reporting API version 3.0 is the latest major version of our API and is not backwards compatible. All future development of the API will be done on this version.

  • New Features
    • New JSON based output reduces the size of the response ~10x from the previous XML output.
    • New Google API client libraries that support Java, JavaScript, Python, PHP, Ruby, and .Net.
    • Support for the Google Discovery API.
    • Support for OAuth 2.0 as the new, recommended way to authorize users.
  • Updates
    • New URL to make requests: https://www.googleapis.com/analytics/v3/data/ga....
    • Registration and developers tokens required.
    • All requests for configuration data should be done through the Management API.

Version 2.4

  • The Core Reporting API version 2.4 is a minor version upgrade that is mostly backwards compatible with the existing Data Export API version 2.3.

  • Updates
    • New URL to make requests: https://www.googleapis.com/analytics/v2.4/data...
    • Registration and developers tokens required.
    • XML output consistent with version 2.3, so the other existing Google Data client libraries will continue to work.
    • Error code for quota errors have changed from 503 to 403
    • JSON responses are not supported.
    • Google Data JavaScript client library not supported.
    • No Account Feed. All requests for configuration data should be done through the Management API.
Management API

Version 3.0

Version 3.0 is the latest and greatest version of the Management API, with many advantages over the deprecated Version 2.3. Version 3.0 is the future of the Management API, and we encourage you to migrate to it now. This version is not backwards compatible with Version 2.3, and so you must be aware of the following differences and change your application accordingly.

  • You must register your application.
  • The supported authorization mechanisms are OAuth 1.0 or 2.0. We recommend that your application use OAuth 2.0, as described in Authorizing Requests.
  • The base URL has been changed to:
    https://www.googleapis.com/analytics/v3/management/...
  • The API uses a new, compact JSON response documented in the Management API Version 3.0 Reference Guide. The JSON responses can be up to 50% smaller than the equivalent XML responses.
  • Version 3.0 is much faster than the deprecated Version 2.3.
  • There is now support for Google API client libraries including Java, Python, PHP, .NET and Ruby.
  • A number of new fields for web properties and views (profiles) have been added.
  • Error messages have been improved.

Version 2.4

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:
    https://www.google.com/analytics/feeds/datasources/ga/...
    to
    https://www.googleapis.com/analytics/v2.4/management/...
  • 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.

Note: We highly recommend migrating to Version 3.0 because all upcoming features will be only added to that version. Version 2.4 of the API allows you to continue using the XML feeds, but Version 3.0 provides responses in a new, compact JSON format.

Appendix A: FAQs

Appendix B: API Version Reference, Tokens, and Migration Guidelines

This section includes a summary explanation on the status of all APIs, Auth Token considerations, and a migration summary:

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.