This document provides examples of basic Data Export API interactions using raw XML and HTTP. For details on the structure of the feed query and response elements, see the Feed Reference and corresponding documents on the Google Analytics Account Feed and Data Feed.
This document is intended for programmers who want to write client applications that read data from an existing Google Analytics profile that tracks data from a web property. The document provides examples of basic API operations using raw HTTP and XML. Java and Javascript developers might prefer to read the language-specific developer guides that explain how to use the client libraries to perform similar functions.
This document assumes that you are familiar with the following concepts:
If you want to test the examples in this document before writing any code, you might find the UNIX command-line utilities curl or wget useful.
For more information, see the manual pages for those utilities.
Before users can view reports on the Google Analytics web site, they must first authenticate by logging in with a Google Account.
In the same way, when users first access your application, they will need to be authenticated. The Google Account that users supply for authentication is typically their Gmail address, although any valid Google Account login will work. Your application should provide user login for access to the Analytics data requested by the feed. Your application can authenticate using one of the following approaches:
For detailed information on authentication to Google Analytics with HTTP Protocol, see the Authentication Guide.
With the Google Analytics Export API, you can use the Account Feed to retrieve
a list of all the accounts an authenticated user has access to. To access the Google Analytics Account Feed using the protocol, send an HTTP
GET request to:
https://www.google.com/analytics/feeds/accounts/default
Make sure to also add the authorization token to this request. Here's an example of an HTTP request, containing a non-secure token, that you might send to Analytics:
|
GET /analytics/feeds/accounts/default
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="l0g3SVzK0Q4m3t9fj1QscYPiAJ-trg6WyvhPNYlGy_A"
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.14) Gecko/20080404 Firefox/2.0.0.14
Host: www.google.com/analytics
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
The account feed can use a number of parameters. See the Account Feed Request section of the Account Feeds document.
Here is an example of how to access the account feed through the bourne shell using cUrl. You can download this script from the Google Analytics Sample Code section on Google Project Hosting and run the script using your preferred Linux environment.
USER_EMAIL="" #Insert your Google Account email here
USER_PASS="" #Insert your password here
googleAuth="$(curl https://www.google.com/accounts/ClientLogin -s \
-d Email=$USER_EMAIL \
-d Passwd=$USER_PASS \
-d accountType=GOOGLE \
-d source=curl-accountFeed-v1 \
-d service=analytics \
| awk /Auth=.*/)"
feedUri="https://www.google.com/analytics/feeds/accounts/default\
?prettyprint=true"
curl $feedUri -s --header "Authorization: GoogleLogin $googleAuth"
See the example account feed response on for an illustration of the raw XML returned when you use the protocol to request account data. For more information on the structure of an account feed response, see Account Feed Response in the Account Feeds document.
You can retrieve report data from an individual profile using the Google Analytics
Export API data feed. The data feed provides you access to all the data
in a selected profile. The following example illustrates a data feed request
using cUrl and client login authorization. You can download
this script from the Google
Analytics Sample Code section on Google Project Hosting and run the script
using your preferred Linux environment. Make sure to also add the authorization
token retrieved from the ClientLogin request and passed into the googleAuth variable.
USER_EMAIL="" #Insert your Google Account email address here USER_PASS="" #Insert your password here PROFILE_ID="" #Insert your profile ID here googleAuth="$(curl https://www.google.com/accounts/ClientLogin -s \ -d Email=$USER_EMAIL \ -d Passwd=$USER_PASS \ -d accountType=GOOGLE \ -d source=curl-accountFeed-v1 \ -d service=analytics \ | awk /Auth=.*/)" feedUri="https://www.google.com/analytics/feeds/data\ ?start-date=2008-10-01\ &end-date=2008-10-31\ &dimensions=ga:source,ga:medium\ &metrics=ga:visits,ga:bounces\ &sort=-ga:visits\ &filters=ga:medium%3D%3Dreferral\ &max-results=5\ &ids=ga:$PROFILE_ID\ &prettyprint=true" curl $feedUri -s --header "Authorization: GoogleLogin $googleAuth"
As you can see in this example, you use query parameters to indicate what Analytics data you want, as well as how you want it filtered and sorted. For details about the structure of a data feed request and all the parameters, see Data Feed Request in the Data Feed document.
See the example data feed response for an illustration of the raw XML returned when you use the protocol to request account data. For more information on the structure of an account feed response, see Data Feed Response in the Data Feeds document.
The Analytics service ignores the following request errors:
foo=bar).metric=ga:pageviews,ga:newVisitors,ga:pageviews). In this case, the duplicate name is ignored.The service returns a 400 BAD REQUEST for the following:
dimensions=ga:browser,ga:city&dimensions=ga:city,ga:country) dimensions or metrics respectivelyfilters=ga:pageviews%3D%3DFrance)
The official Data Export 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 Data Export API, or if you are creating your own client library for the Data Export API, the information here will help you minimize potential conflicts between your code and new or changing features of the API.
The Data Export 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.
The Data Export 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:
sort
parameter on your queryTo ensure that your application remains compatible with the Google Analytics Data Export 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.