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.

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 API 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 API Console

To get started using Analytics API, you need to first use the setup tool, which guides you through creating a project in the Google API Console, enabling the API, and creating credentials.

If using OAuth v2.0 for authentication purposes:

  1. From the Credentials page, click Create credentials > OAuth client ID to create your OAuth 2.0 credentials or Create credentials > Service account key to create a service account.
  2. If you created an OAuth client ID, then select your application type.
  3. Fill in the form and click Create.

Your application's client IDs and service account keys are now listed on the Credentials page. For details, click a client ID; parameters vary depending on the ID type, but might include email address, client secret, JavaScript origins, or redirect URIs.

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:

If you haven't done so already, create your application's API key by clicking Create credentials > API key. Next, look for your API key in the API keys section.

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 API 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 API 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 API 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 API 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: