Google Analytics

Core Reporting API - Protocol

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.

    1. Audience
    2. Authentication
    3. Specifying a Version
    1. Retrieving Report Data
    2. HTTP Error Responses
    3. XML Parsing Guidelines

Audience

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:

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.

Authentication

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:

GData-Version: 2

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 precedence.

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 googleAuth variable.

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:sessions,ga:bounces\
&sort=-ga:sessions\
&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. foo=bar).
  • duplicate use of dimension or metric name (e.g. metric=ga:pageviews,ga:newUsers,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.

Versioning

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 sort parameter 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.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.