This document provides examples of basic Core Reporting API interactions using raw XML and HTTP. For details on the structure of the feed query and response elements, see the Data Feed reference.
This document is intended for programmers who want to write client applications that read data from an existing Google Analytics view (profile) that tracks data from a web property. The document provides examples of basic API operations using raw HTTP and XML. Java developers might prefer to read to Java Getting Started Guide to read how to use the API using the Google-APIs-Java client library.
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 Data Feed request.
- The basic Application Overview of a Core Reporting API application.
If you want to test the examples in this document before writing any code, you might find the UNIX command-line utilities
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:
- ClientLogin username/password authentication
- AuthSub proxy authentication
- OAuth authentication for web applications
For detailed information on authentication to Google Analytics with HTTP Protocol, see the Authentication Guide.
Specifying a Version
Every request that you send using the Analytics Core Reporting API should specify version 2 of the API via the GData-Version HTTP header:
If you can't set HTTP headers, you can specify
v=2 as a query
parameter in the URL, but the HTTP header is the recommend method. If the
version is present in both the HTTP header and in the query, the header takes
Feature changes from one major release to another are not backwards compatible. However, minor versions are backwards compatible with the previous release. For example, if your application uses features developed in version 2.1 and version 2.2 is released, its changes will be compatible with version 2.1 and not harm your application.
In general, you should specify versions only using the major version number in order to get the most recent updates for that major version. For example, if you supply v=2 as the version parameter and the most recent minor version is 2.3, then that version is returned. Requests from applications specifying a minor version are generally treated as requests for the latest minor version for that major version.
Note: The official client libraries supply appropriate version headers
automatically, so you don't nee to use use the
v=2 query parameter.
Retrieving Report Data
You can retrieve report data from an individual view (profile) using the Google Analytics
Export API data feed. The data feed provides you access to all the data
in a selected view (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
USER_EMAIL="" #Insert your Google Account email address here USER_PASS="" #Insert your password here TABLE_ID="" #Insert your table ID here (ie ga:1234) googleAuth="$(curl https://www.google.com/accounts/ClientLogin -s \ -d Email=$USER_EMAIL \ -d Passwd=$USER_PASS \ -d accountType=GOOGLE \ -d source=curl-dataFeed-v2 \ -d service=analytics \ | awk /Auth=.*/)" feedUri="https://www.google.com/analytics/feeds/data\ ?ids=$TABLE_ID\ &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\ &prettyprint=true" curl $feedUri --silent \ --header "Authorization: GoogleLogin $googleAuth" \ --header "GData-Version: 2"
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 the 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.
HTTP Error Responses
The Google Analytics API service ignores the following request errors:
- unrecognized query string parameter (e.g.
- duplicate use of dimension or metric name (e.g.
metric=ga:pageviews,ga:newVisitors,ga:pageviews). In this case, the duplicate name is ignored.
For more details about error codes returned by the API service, see the Error Code section in the Core Reporting API reference.
XML Parsing Guidelines
The official Core Reporting 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 the Core Reporting API, or if you are creating your own client library for the Core Reporting 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 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.
- Google Data 2.0 specification
- Atom/RSS document format: http://code.google.com/apis/gdata/docs/2.0/reference.html#DocumentFormat
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:
- 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 Core Reporting 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.