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 advanced 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
We recommend using OAuth 2.0 to authorize requests.
The Google Analytics API also supports older authorization options, such as OAuth 1.0, AuthSub, or ClientLogin; however, in most cases we don't recommend using those other options. If your application already uses those options, we recommend migrating to OAuth 2.0 if possible.
If your application has certain unusual authorization requirements, such as logging in at the same time as requesting data access (hybrid) or domain-wide delegation of authority (2LO), then you cannot currently use OAuth 2.0 tokens. In such cases, you must instead use OAuth 1.0 tokens and an API key. To find your application's API key:
- Go to the Google Developers Console.
- Select a project.
- In the sidebar on the left, select APIs & auth. In the displayed list of APIs, make sure the Google Analytics API status is set to ON.
- In the sidebar on the left, select Credentials.
- Find the line or lines labeled API key. If there is no API key, then create one by selecting Create New Key. For more about API keys, see the Console help.
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 Developers 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 Developers Console. (If the API isn't listed in the Developers 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
totalResultsentity. - The maximum number of rows a Management API response could
contain is
represented in each feed response in the
itemsPerPageentity. 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-resultsquery parameter. - To paginate through results, you can set the optional
start-indexquery 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
400status 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 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 visitor 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.
Advanced Segment Feed
The advanced segment feed provides a listing of all the default and user-created advanced 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 advanced 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 advanced segment feed also accepts a number of optional parameters. See the Advanced Segment Feed Request section of the Management API Feed Reference document for details.
Advanced 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 advanced segment ID is in the
idattribute of thedxp:segmentelement. - This ID value distinguishes between default segments and custom segments:
- Segments with IDs < 0 are default segments available to all users through the web interface
- Segments with IDs >= 0 are custom segments defined by each user
- The
definitionelement comes from the API attempting to recreate the syntax of the Advanced Segment. This can be used as the parameter to a dynamic advanced segment. In some cases where the API does not know how to recreate the syntax, the element will have no value
The Advanced 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
sortparameter 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.