Management API - Protocol (v2.4)

The Google Analytics Management API provides five separate read-only feeds that allow you to access Google Analytics account and configuration data. Your applications can use the protocol to access these feeds. For example, if your application needs a list of views (profiles) for a user, it can request the View (Profile) Feed. Similarly, if your application needs all the goal configuration data, including goal names for a particular view (profile), it can request the Goal Feed.

Note: The Management API recently changed from Version 2.3 to Version 2.4. Details of the changes are given in What's New.

Overview

This document is intended for programmers who want to write client applications that read data from Google Analytics accounts, web properties, views (profiles), goals, and segments. The document describes basic API operations using raw HTTP and XML. Java developers might prefer to read the Java-specific developer guide that explains how to use the client library to perform similar functions.

This document assumes that you are familiar with the following concepts:

The general ideas behind the Google Data APIs protocol.
The mechanics of constructing a Management API feed request from Google Analytics. See Management API Feed for more information.
The basic process of using the Management API as described in Feed Retrieval Basics.

Each of the sections below provide a conceptual overview.

Authorization

Before users can view their account information on the Google Analytics web site, they must first login in with a Google Account. In the same way, when users first access your application, they will need to authorize your application to access their data. The authorization in the API works using tokens.

Every request your application sends to the Google Analytics API must include an authorization token. The token also identifies your application to Google.

About authorization protocols

Your application must use OAuth 2.0 to authorize requests. No other authorization protocols are supported. If your application uses Google Sign-In, some aspects of authorization are handled for you.

Authorizing requests with OAuth 2.0

All requests to the Google Analytics API must be authorized by an authenticated user.

The details of the authorization process, or "flow," for OAuth 2.0 vary somewhat depending on what kind of application you're writing. The following general process applies to all application types:

When you create your application, you register it using the Google API Console. Google then provides information you'll need later, such as a client ID and a client secret.
Activate the Google Analytics API in the Google API Console. (If the API isn't listed in the API Console, then skip this step.)
When your application needs access to user data, it asks Google for a particular scope of access.
Google displays a consent screen to the user, asking them to authorize your application to request some of their data.
If the user approves, then Google gives your application a short-lived access token.
Your application requests user data, attaching the access token to the request.
If Google determines that your request and the token are valid, it returns the requested data.

Some flows include additional steps, such as using refresh tokens to acquire new access tokens. For detailed information about flows for various types of applications, see Google's OAuth 2.0 documentation.

Here's the OAuth 2.0 scope information for the Google Analytics API:

Scope	Meaning
`https://www.googleapis.com/auth/analytics.readonly`	Read-only access to the Analytics API.

To request access using OAuth 2.0, your application needs the scope information, as well as information that Google supplies when you register your application (such as the client ID and the client secret).

Tip: The Google APIs client libraries can handle some of the authorization process for you. They are available for a variety of programming languages; check the page with libraries and samples for more details.

Retrieving Feeds

The Google Analytics Management API allows developers to access Google Analytics account and configuration information through 5 feeds. Each feed is based on the Google Data Protocol and has a series of entries. Each entry can be conceptually thought of as a row of data in a table. To access the data from each feed, you will need to retrieve the feed, then iterate through each of the entries.

There are a couple of important things to note about each feed:

In some cases you might need to paginate through the result set to display all the data.
- The number of rows Google Analytics found is represented in each feed response in the totalResults entity.
- The maximum number of rows a Management API response could contain is represented in each feed response in the itemsPerPage entity. By default, the maximum number of rows is 1000, but this can be changed to a value of up to 10,000 by specifying the max-results query parameter.
- To paginate through results, you can set the optional start-index query parameter when requesting each feed.
In some feeds, each entry contains a parent link URL that refers to an entry in the parent feed. While this URL reveals to you the hierarchy of relationship between the feed and its parent, you cannot it to retrieve individual entries directly, so requesting a parent link will only return a 400 status code. For more information on the feed hierarchy, see the Overview section of the Management API Feed

Account Feed

The Account Feed returns information about the all the Google Analytics Accounts for the authenticated user. The Account Feed is a top level entity in the Management API. Each Account Feed Entry has a Web Property Feed as a child. You can learn more about Google Analytics Account in the Analytics Accounts section of the Accounts and Views (Profiles) document.

Account Feed Request

To access the Account Feed using the protocol, set the authorization token in an HTTP header and send a GET request to:

https://www.googleapis.com/analytics/v2.4/management/accounts

The Account Feed URL also accepts a number of optional parameters. See the Common Request Parameters section of the Management API Feed Reference for details.

Account Feed Response

Here's an example of the Account Feed response from the server (only including relevant data):

<feed xmlns='http://www.w3.org/2005/Atom' xmlns:dxp='http://schemas.google.com/analytics/2009'
      xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:gd='http://schemas.google.com/g/2005'>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>1000</openSearch:itemsPerPage>
  <entry>
    <dxp:property name='ga:accountId' value='30481'/>
    <dxp:property name='ga:accountName' value='Google Store'/>
    <link rel='self' type='application/atom+xml' href='https://www.googleapis.com/analytics/v2.4/management/accounts/30481'/>
    <link rel='http://schemas.google.com/ga/2009#child' type='application/atom+xml'
          href='https://www.googleapis.com/analytics/v2.4/management/accounts/30481/webproperties'
          gd:targetKind='analytics#webproperties'/>
  </entry>
</feed>

The Account Feed response section in the Management API Feed Reference describes each field in detail.

Web Property Feed

The Web property Feed returns information about all web properties for the authenticated user. The web property feed is child of an Account Entry and each Web Property Entry has a View (Profile) Feed as a child. To learn more about web properties, see the Web Properties section in the Accounts and Views (Profiles) guide.

Web Property Feed Request

You can use the web property feed to filter the returned results by specifying an account ID. To access the web property feed using the protocol, set the authorization token in an HTTP header and send a GET request to:

https://www.googleapis.com/analytics/v2.4/management/accounts/[accountID]/webproperties

The accountID is the central string of numbers in the web property ID, which is used in the tracking code for any web property of the account. For example, if the web property ID is UA-12345-2, then 12345 is the account ID. For more information, see the Account ID section in the Accounts and Views (Profiles) document.

Using the `~all` Identifier

You can use the ~all identifier to get all web properties for all the accounts the user has access to:

https://www.googleapis.com/analytics/v2.4/management/accounts/~all/webproperties

Note: Retrieving all data is slow. Under the hood, Google Analytics performs a breadth first search through all accounts and all web properties. So for users with many accounts and many web propertiesU, a response can take a longer time to return. Generally you should provide a way for end users to supply a web property ID to help filter the results and speed up the response.

Optional Parameters

The Web Property Feed URL also accepts a number of optional parameters. See the Common Request Parameters section of the Management API Feed Reference for details.

Web Property Feed Response

Here's an example of the Web Property Feed response from the server (only including relevant data):

<feed xmlns='http://www.w3.org/2005/Atom' xmlns:dxp='http://schemas.google.com/analytics/2009'
      xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:gd='http://schemas.google.com/g/2005'>
  <generator version='1.0'>Google Analytics</generator>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>1000</openSearch:itemsPerPage>
  <entry>
    <dxp:property name='ga:accountId' value='30481'/>
    <dxp:property name='ga:webPropertyId' value='UA-30481-1'/>

    <link rel='self' type='application/atom+xml'
          href='https://www.googleapis.com/analytics/v2.4/management/accounts/30481/webproperties/UA-30481-1'/>
    <link rel='http://schemas.google.com/ga/2009#parent' type='application/atom+xml'
          href='https://www.googleapis.com/analytics/v2.4/management/accounts/30481'
          gd:targetKind='analytics#account'/>
    <link rel='http://schemas.google.com/ga/2009#child' type='application/atom+xml'
          href='https://www.googleapis.com/analytics/v2.4/management/accounts/30481/webproperties/UA-30481-1/profiles'
          gd:targetKind='analytics#profiles'/>
  </entry>
</feed>

If you need to navigate between feeds, each entry has a URL that can be used to get the child View (Profile) Feed. You can get this URL by looking for the link element whose targetKind attribute equals analytics#profiles.

The Web Property Feed Description in the Management API Feed Reference describes what each field represents in more detail.

View (Profile) Feed

The view (profile) feed returns all the Google Analytics views (profiles) for the authenticated user. This feed is important because it provides the tableId for each view (profile). The tableId value is used in Google Analytics Data Export API queries, specifically the ids query parameter, to identify the view (profile) to retrieve data from. The view (profile) feed is a child of a Web Property Entry and each View (Profile) Entry has a Goal Feed as a child. To learn more about view (profiles), see the Profiles section of the Accounts and Views (Profiles) document.

View (Profile) Feed Request

Use the view (profile) feed to filter the returned results by account and web property IDs. To access the view (profile) feed using the protocol, set the authorization token in an HTTP header and send a GET request to:

https://www.googleapis.com/analytics/v2.4/management/accounts/[accountID]/webproperties/[webPropertyID]/profiles

Where accountID is the ID for the Analytics account and webPropertyID is the ID for the web property being retrieved. The accountID is the central string of numbers in the web property ID used in the tracking code for any web property of the account. For more information, see the Account ID section of the Accounts and Views (Profiles) document. The webPropertyID is of the form UA-XXXX-YY, and is found in the tracking code.

Using the `~all` Identifier

You can use the ~all identifier to get a set of views (profiles) for the user, rather than specifying elements by ID. For example:

Get all the views (profiles) for a specific account:

https://www.googleapis.com/analytics/v2.4/management/accounts/30481/webproperties/~all/profiles

Get all the views (profiles) for all the accounts:

https://www.googleapis.com/analytics/v2.4/management/accounts/~all/webproperties/~all/profiles

Important: when using ~all for any ID, you must then use ~all for following children IDs. In other words, if you specify an ID for a child, you would need to specify which parent entity this child belongs to by specifying the parent ID. So if the accountId is set to ~all the webPropertyId must also be set to ~all.

Note: Retrieving all data is slow. Under the hood, Google Analytics performs a breadth first search through all accounts and all web properties. So 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 web property ID to help filter the results and speed up the response.

Optional Parameters

The View (Profile) Feed URL also accepts a number of optional parameters. See the Common Request Parameters section of the Management API Feed Reference for details.

View (Profile) Feed Response

Here's an example of the view (profile) feed response from the server (only including relevant data):

<feed xmlns='http://www.w3.org/2005/Atom' xmlns:dxp='http://schemas.google.com/analytics/2009'
      xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:gd='http://schemas.google.com/g/2005'>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>1000</openSearch:itemsPerPage>
  <entry>
    <dxp:property name='ga:accountId' value='30481'/>
    <dxp:property name='ga:webPropertyId' value='UA-30481-1'/>
    <dxp:property name='ga:profileName' value='www.googlestore.com'/>
    <dxp:property name='ga:profileId' value='1174'/>
    <dxp:property name='dxp:tableId' value='ga:1174'/>
    <dxp:property name='ga:currency' value='USD'/>
    <dxp:property name='ga:timezone' value='America/Los_Angeles'/>
    <link rel='self' type='application/atom+xml'
          href='https://www.googleapis.com/analytics/v2.4/management/accounts/30481/webproperties/UA-30481-1/profiles/1174'/>
    <link rel='http://schemas.google.com/ga/2009#parent' type='application/atom+xml'
          href='https://www.googleapis.com/analytics/v2.4/management/accounts/30481/webproperties/UA-30481-1'
          gd:targetKind='analytics#webproperty'/>
    <link rel='http://schemas.google.com/ga/2009#child' type='application/atom+xml'
          href='https://www.googleapis.com/analytics/v2.4/management/accounts/30481/webproperties/UA-30481-1/profiles/1174/goals'
          gd:targetKind='analytics#goals'/>
  </entry>
</feed>

If you need to navigate between feeds, each entry has a URL that can be used to get the child Goal Feed. You can get this URL by looking for the link element whose targetKind attribute equals analytics#goals.

The View (Profile) Feed Description in the Management API Feed Reference describes what each field represents in more detail.

Goal Feed

The goal feed lets you quickly access all the configured goal information for a particular view (profile). This feed is important because it provides access to goal names, goal types, and goal status (active or inactive). The goal feed is a child of a View (Profile) Feed Entry. Goal Entries have no children.

Goal Feed Request

Use the goal feed to filter the returned results by specifying account, web property, and view (profile) IDs. To access the goal feed using the protocol, set the authorization token in an HTTP header and send a GET request to:

https://www.googleapis.com/analytics/v2.4/management/accounts/[accountID]/webproperties/[webPropertyID]/profiles/[profileID]/goals

This URL requests all goals for the view (profile) ID 4849:

https://www.googleapis.com/analytics/v2.4/management/accounts/30481/webproperties/UA-30481-1/profiles/4849/goals

Using the `~all` Identifier

You can use the ~all identifier to get all goals for the user, rather than using the webPropertyId. For example:

Get all the goals for a specific view (profile):

https://www.googleapis.com/analytics/v2.4/management/accounts/30481/webproperties/UA-30481-1/profiles/~all/goals

Get all the goals for all the views (profiles) for all accounts:

https://www.googleapis.com/analytics/v2.4/management/accounts/~all/webproperties/~all/profiles/~all/goals

Note: Retrieving all data is slow. Under the hood, Google Analytics performs a breadth first search through all accounts and all web properties. So 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 web property ID to help filter the results and speed up the response.

Optional Parameters

The Goal Feed URL also accepts a number of optional parameters. See the Common Request Parameters section of the Management API Feed Reference for details.

Goal Feed Response

There are 2 types of goals in Google Analytics:

Destination Goals — which allow you to configure steps.
Engagement Goals — which are triggered when a user interacts with a site over a certain threshold.

Each type of goal has a slightly different representation as a Goal Entry.

Here's an example of the XML response from the server for Destination Goals:

<feed xmlns='http://www.w3.org/2005/Atom' xmlns:dxp='http://schemas.google.com/analytics/2009'
      xmlns:ga='http://schemas.google.com/ga/2009' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'
      xmlns:gd='http://schemas.google.com/g/2005'>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>1000</openSearch:itemsPerPage>
  <entry>
    <dxp:property name='ga:profileId' value='1174'/>
    <ga:goal active='true' name='Completing Order' number='1' value='10.0'>
      <ga:destination caseSensitive='false' expression='/purchaseComplete.html' matchType='regex' step1Required='false'>
        <ga:step name='View Product Categories' number='1' path='/Apps|Accessories|Fun|Kid\+s|Office|Wearables'/>
        <ga:step name='View Product' number='2' path='/Apps|Accessories|Fun|Kid\+s|Office|Wearables/(.*)\.axd'/>
        <ga:step name='View Shopping Cart' number='3' path='/shoppingcart.aspx'/>
        <ga:step name='Login' number='4' path='/login.html'/>
        <ga:step name='Place Order' number='5' path='/placeOrder.html'/>
      </ga:destination>
    </ga:goal>
    <link rel='self' type='application/atom+xml'
          href='https://www.googleapis.com/analytics/v2.4/management/accounts/30481/webproperties/UA-30481-1/profiles/1174/goals/1'/>
    <link rel='http://schemas.google.com/ga/2009#parent' type='application/atom+xml'
          href='https://www.googleapis.com/analytics/v2.4/management/accounts/30481/webproperties/UA-30481-1/profiles/1174'
          gd:targetKind='analytics#profile'/>
  </entry>
</feed>

Here's an example of the XMl response from the server which for Engagement Goals:

<feed xmlns='http://www.w3.org/2005/Atom' xmlns:dxp='http://schemas.google.com/analytics/2009'
      xmlns:ga='http://schemas.google.com/ga/2009' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'
      xmlns:gd='http://schemas.google.com/g/2005'>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>1000</openSearch:itemsPerPage>
  <entry>
    <dxp:property name='ga:profileId' value='1174'/>
    <ga:goal active='true' name='Browsed my site over 5 minutes' number='2' value='0.0'>
      <ga:engagement comparison='>' thresholdValue='300' type='timeOnSite'/>
    </ga:goal>
    <link rel='self' type='application/atom+xml'
          href='https://www.googleapis.com/analytics/v2.4/management/accounts/30481/webproperties/UA-30481-1/profiles/1174/goals/2'/>
    <link rel='http://schemas.google.com/ga/2009#parent' type='application/atom+xml'
          href='https://www.googleapis.com/analytics/v2.4/management/accounts/30481/webproperties/UA-30481-1/profiles/1174'
          gd:targetKind='analytics#profile'/>
  </entry>
</feed>

The Goal Feed Description in the Management API Feed Reference describes what each field represents in more detail.

Segment Feed

The segment feed provides a listing of all the built-in and user-created segments. You program can retrieve the ID of these segments and use them in the segment parameter of the Core Reporting API data feed request. Unlike the other feeds of the management API, this feed has no parent or child relationships.

To access the segment feed using the protocol, set the authorization token in an HTTP header and send a GET request to:

https://www.googleapis.com/analytics/v2.4/management/segments

The segment feed also accepts a number of optional parameters. See the Segment Feed Request section of the Management API Feed Reference document for details.

Semgent Feed Response

<feed xmlns='http://www.w3.org/2005/Atom' xmlns:dxp='http://schemas.google.com/analytics/2009' xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/' xmlns:gd='http://schemas.google.com/g/2005' gd:kind='analytics#segments'>
  <entry>
    <dxp:segment id='gaid::0' name='Sources Form Google'>
      <dxp:definition>ga:source=~^\Qgoogle\E</dxp:definition>
    </dxp:segment>
    <link rel='self' type='application/atom+xml'
          href='https://www.googleapis.com/analytics/v2.4/management/segments/gaid::0'/>
  </entry>
</feed>

Important:

Each segment ID is in the id attribute of the dxp:segment element.
This ID value distinguishes between built-in segments and custom segments:
- Segments with IDs < 0 are built-in segments available to all users through the web interface
- Segments with alphanumeric IDs are custom segments defined by each user
The definition element comes from the API attempting to recreate the syntax of the Segment. This can be used as the parameter to a dynamic segment. In some cases where the API does not know how to recreate the syntax, the element will have no value

The Segment Feed Description in the Management API Feed Reference describes what each field represents in more detail.

XML Parsing Guidelines

The official Management API client libraries will always be supported and work with any changes to the XML. However, if your application is interacting directly with the XML response of Management API, or if you are creating your own client library for the Management API, the information here will help you minimize potential conflicts between your code and new or changing features of the API.

Analytics Uses the Google Data Specification

The Management API relies on Google Data API protocol, and will always adhere to the standards specified in the Google Data protocol. The following links point to the key reference for Google Data and the Atom/RSS format.

Google Data 2.0 specification
Atom/RSS document format: https://developers.google.com/gdata/docs/2.0/reference#DocumentFormat

Versioning

The Management API supports versioning, as provided by the Google Data service.

Major Versions. To upgrade your application from a previous version to the most recent one, follow the Google Data API guidelines for updating a protocol-based client.

Minor Versions. Over time, there will be minor changes to the API, and the format of the XML response will change. Our policy for minor changes is:

All the current elements and attributes will not be removed
New elements and attributes might be added
Elements and their attributes might be reordered
We only guarantee the order of the feed response entries if you use the sort parameter on your query

To ensure that your application remains compatible with the Google Analytics Management API, always request an XML element by qualified namespace and name rather than by position. There are many technologies, such as XPath or SAX, that you can use to find groups of elements with common features.

Management API - Protocol (v2.4)

Overview

Authorization

About authorization protocols

Authorizing requests with OAuth 2.0

Retrieving Feeds

Account Feed

Account Feed Request

Account Feed Response

Web Property Feed

Web Property Feed Request

Using the ~all Identifier

Optional Parameters

Web Property Feed Response

View (Profile) Feed

View (Profile) Feed Request

Using the ~all Identifier

Optional Parameters

View (Profile) Feed Response

Goal Feed

Goal Feed Request

Using the ~all Identifier

Optional Parameters

Goal Feed Response

Segment Feed

Semgent Feed Response

XML Parsing Guidelines

Analytics Uses the Google Data Specification

Versioning

Using the `~all` Identifier

Using the `~all` Identifier

Using the `~all` Identifier