Migration Guide: Moving from v2.4 APIs to Management API v3.0 and Analytics Reporting v4.0

This article provides a set of guidelines to migrate from v2.4 to Management API v3.0 and Analytics Reporting API v4.0.

Introduction

If your application currently uses v2.4 APIs, it is important that you migrate to Management API v3.0 and/or Core Reporting API v4.0 so that your application continues to work.

Migration Guidelines Summary

Analytics Reporting v4.0 and Management API v3.0

  • New versions of the API are not backwards compatible with prior versions. The new versions of the Analytics APIs return a JSON response compared to XML responses in v2.4. Moreover, Analytics Reporting API v4.0 expects JSON payload as input, opposed to the URL-based input of earlier versions of the API.
  • Any existing auth tokens authorized for the v2.4 scope will work with v3.0 and v4.0 APIs.
  • All requests for configuration data should be done through the Management API.
  • All reporting requests should be done through the Analytics Reporting API. Refer to the Analytics Reporting API Migration Guide for help with migrating the legacy code to Reporting API v4.0

Differences between v2.4 and newer APIs

Reporting API

Version 4.0

  • The Analytics Reporting API version 4.0 is the latest major version of our Reporting API. All future development of the API will be done on this version.

  • New Features
    • New JSON based input and output.
    • Metric expressions.
    • Multiple date ranges.
    • Cohorts and Lifetime value.
    • Multiple segments.
    • from the previous XML output.
  • Updates
    • New URL to make requests: https://analyticsreporting.googleapis.com/v4/reports....
    • All requests for configuration data should be done through the Management API.

Version 3.0

  • The Core Reporting API version 3.0 is no longer actively developed. It is recommended to migrate to Analytics Reporting API v4.0

  • Updates
    • New URL to make requests: https://www.googleapis.com/analytics/v3/data/ga....
    • All requests for configuration data should be done through the Management API.

Version 2.4

  • The Core Reporting API version 2.4 is an XML-based API, deprecated and will be shutdown on December 12th, 2019.

Management API

Version 3.0

Version 3.0 is the latest version of the Management API, with many advantages over the deprecated Version 2.4. This version is not backwards compatible with Version 2.4, and so you must be aware of the following differences and change your application accordingly.

  • 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.
  • 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.
  • For the full list of new features and changes, see the Management API v3 changelog.

Version 2.4

Version 2.4 of the Management API is a XML-only API that is currently deprecated.

API Version Reference

The list below provides the following information for each API version: the current status, whether it is active or shutdown (inactive), the API Endpoint (Request Base URL), and the Auth Scope.

Core Reporting API

Analytics Reporting API v4.0
  • The Analytics Reporting API version 4.0 is the latest major version of our Reporting API and is not backwards compatible.
  • Active
  • Request Base URL: https://analyticsreporting.googleapis.com/v4/reports
  • Auth Scope: https://www.googleapis.com/auth/analytics.readonly
Core Reporting API v3.0
  • This version is no longer actively developed. It is recommended to migrate to Analytics Reporting API v4.0
  • Active - No future development except for bug fixes
  • Request Base URL: https://www.googleapis.com/analytics/v3/data/ga
  • Auth Scope: https://www.googleapis.com/auth/analytics.readonly
Core Reporting API v2.4
  • Deprecated
  • Any requests you make to this API will fail after December 12th, 2019
  • Request Base URL: https://www.googleapis.com/analytics/v2.4/data
  • Auth Scope: https://www.googleapis.com/auth/analytics.readonly

Management API

Management API v3.0
  • Recommended Version - All future development of the API will be done on this version
  • Active
  • Request Base URL: https://www.googleapis.com/analytics/v3/management/
  • Auth Scope: https://www.googleapis.com/auth/analytics.readonly
Management API v2.4
  • Deprecated
  • Any requests you make to this API will fail after December 12th, 2019
  • Request Base URL: https://www.googleapis.com/analytics/v2.4/management/
  • Auth Scope: https://www.googleapis.com/auth/analytics.readonly