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 themax-results
query parameter. - To paginate through results, you can set the optional
start-index
query parameter when requesting each feed.
- The number of rows Google Analytics found is represented
in each feed response in the
- 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
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. The profileID
is the numeric view (profile) ID.
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
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
and the view (profile) must 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 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 thedxp: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.