Google Analytics

Data API - Data Feed

This document provides a detailed reference on the data feed for version 2.4 of the Core Reporting API.

Contents

  1. Overview
  2. Data Feed Request
  3. Data Feed Response
  4. Data Feed Error Codes
  1. Sampling
  2. Handling Large Data Results

Overview

Reports in the Analytics user interface are generally organized into these categories:

  • Users
  • Traffic Sources
  • Content
  • Internal Site Search
  • Goals
  • Ecommerce

Each report, regardless of the section to which it belongs, consists of two primary fields—metrics, and dimensions. Analytics reports use a combination of metrics and dimensions to describe key types of user activity to your website, such as which search engine users used to reach your site in the Search Engines report, or which pages on your site received the most traffic in the Top Content report. Similarly, the Core Reporting API groups both dimensions and metrics into several categories of report data. By choosing your own combinations of dimensions and metrics, you can create a customized report tailored to your specifications.

Keep in mind that not all categories of data can be combined in a single request. When you request a combination of dimensions and metrics that are not allowed, you will receive an error response instead of an actual feed. This causes no harm, so feel free to experiment with combinations of metrics and dimensions that seem most useful. For a detailed list of the metrics and dimensions you can query, see the Dimensions & Metrics Reference

To understand how Analytics data is applied to the view (profile) you are requesting data for, see the background document on Accounts and Views (Profiles).

Back to Top

Data Feed Request

This section describes all the elements and parameters that make up a data feed request. In general, you provide the table ID corresponding to the view (profile) you want to retrieve data from, choose the combination of dimensions and metrics, and provide a date range along with other parameters in a query string.

https://www.googleapis.com/analytics/v2.4/data

?ids=ga:12345

&dimensions=ga:source,ga:medium

&metrics=ga:sessions,ga:bounces

&sort=-ga:sessions

&filters=ga:medium%3D%3Dreferral

&segment=gaid::-10 OR segment=sessions::condition::ga:medium%3D%3Dreferral

&start-date=2008-10-01

&end-date=2008-10-31

&start-index=10

&max-results=100

&prettyprint=true

Base URL

https://www.googleapis.com/analytics/v2.4/data
Required.
The base URL for a data feed request.

ids

ids=ga:12345
Required.
The unique table ID used to retrieve the Analytics Report data. This ID is provided by the <ga:tableId> element for each entry in the account feed. This value is composed of the ga: namespace and the view (profile) ID of the web property.

Back to Top



dimensions

dimensions=ga:source,ga:medium
Optional.
The dimensions parameter defines the primary data keys for your Analytics report, such as ga:browser or ga:city. Use dimensions to segment your metrics. For example, while you can ask for the total number of pageviews to your site, it might be more interesting to ask for the number of pageviews segmented by browser. In this case, you'll see the number of pageviews from Firefox, Internet Explorer, Chrome, and so forth.

When the value of the dimension cannot be determined, Analytics uses the special string (not set). There are a number of situations where the dimension value will not be set. For example, suppose you want to query your reports for country, city, and pageviews, and suppose the following is true for your view (profile) data:

  • Pageviews on your site came from only two identified countries
  • Each of those countries had only two identifiied cities
  • Some number of pageviews also came from areas that could not be mapped to either a country or a city
  • Some pageviews could be mapped to a country, but not to a city within that country

The results for this request would return data as illustrated by the following example table.

Country City Pageviews
(not set) (not set) 23
Country A (not set) 13
Country A City A1 10
Country A City A2 5
Country B (not set) 10
Country B City B1 5
Country B City B2 13

When using dimensions in a feed request, be aware of the following constraints:

  • You can supply a maximum of 7 dimensions for any query.
  • You can not send a query comprised only of dimensions: you must combine any requested dimension with at least one metric.
  • Any given dimension can be used with other dimensions or metrics, but only where Valid Combinations apply for that dimension.

For more information and the list of all dimensions, see the Dimensions section in the Dimensions and Metrics Reference.

Back to Top



metrics

metrics=ga:sessions,ga:bounces
Required.
The aggregated statistics for user activity in a view (profile), such as clicks or pageviews. When queried by alone, metrics provide the total values for the requested date range, such as overall pageviews or total bounces. However, when requested with dimensions, values are segmented by the dimension. For example, ga:pageviews requested with ga:country returns the total pageviews per country. When requesting metrics, keep in mind:
  • All requests require at least one metric.
  • You can supply a maximum of 10 metrics for any query.
  • Not all dimensions and metrics can be used together. Consult the Valid Combinations tool to see which combinations work together.
For more information and the list of all metrics, see the Metrics section in the Dimensions and Metrics Reference.

Back to Top



sort

sort=-ga:sessions
Optional.

Indicates the sorting order and direction for the returned data. For example, the following parameter would first sort by ga:browser and then by ga:pageviews in ascending order.

sort=ga:browser,ga:pageviews

If you do not indicate a sorting order in your query, the data is sorted by dimension from left to right in the order listed. For example, if the query looks like this:

dimensions=ga:browser,ga:country

Sorting occurs first by ga:browser, then by ga:country. However, if the query uses a different order:

dimensions=ga:country,ga:browser
Sorting occurs first by ga:country, then by ga:browser.

When using the sort parameter, keep in mind the following:

  • Sort only by dimensions or metrics value that you have used in the dimensions or metrics parameter. If your request sorts on a field that is not indicated in either the dimensions or metrics parameter, you will receive a request error.
  • Strings are sorted in ascending alphabetical order in an en-US locale.
  • Numbers are sorted in ascending numeric order.
  • Dates are sorted in ascending order by date.

The sort direction can be changed from ascending to descending by using a minus sign (-) prefix on the requested field. For example:

sort=ga:browser,ga:date sorts ascending by ga:browser and then ascending by ga:date
sort=-ga:pageviews,ga:browser sorts first in descending order by ga:pageviews and then in ascending order by ga:browser.

Back to Top



filters

filters=ga:medium%3D%3Dreferral
Optional.

The filters query string parameter restricts the data returned from your request to the Analytics servers. When you use the filters parameter, you supply a dimension or metric you want to filter, followed by the filter expression. For example, the following feed query requests ga:pageviews and ga:browser from view (profile) 12134, where the ga:browser dimension starts with the string Firefox:

  https://www.googleapis.com/analytics/v2.4/data
  ?ids=ga:12134
  &dimensions=ga:browser&metrics=ga:pageviews
  &filters=ga:browser%3D~%5EFirefox
  &start-date=2007-01-01
  &end-date=2007-12-31

Filtered queries restrict the rows that do (or do not) get included in the result. Each row in the result is tested against the filter: if the filter matches, the row is retained and if it doesn't match, the row is dropped.

  • URL Encoding: The Java client library automatically encodes the filter operators. However, when you use the JavaScript client library, or make requests directly to the protocol, you must explicitly encode filter operators as indicated in the table below.
  • Dimension filtering: Filtering occurs before any dimensions are aggregated, so that the returned metrics represent the total for only the relevant dimensions. In the example above, the number of pageviews would be only those pageviews where Firefox is the browser.
  • Metrics filtering: Filtering on metrics occurs after the metrics are aggregated.
  • Valid combinations: You can filter for a dimension or metric that is not part of your query, provided all dimensions/metrics in the request and the filter are valid combinations. For example, you might want to query for a dated list of pageviews, filtering on a particular browser. See Valid Combinations for more information.

Back to Top

Filter Syntax


A single filter uses the form:

ga:name operator expression

In this syntax:

  • name — the name of the dimension or metric to filter on. For example: ga:pageviews will filter on the pageviews metric.
  • operator — defines the type of filter match to use. Operators are specific to either dimensions or metrics.
  • expression — states the values included or excluded from the results. Expressions use regular expression syntax.

Filter Operators


There are six filter operators for dimensions and six operators for metrics. The operators must be URL encoded in order to be included in URL query strings.

Tip: Use the Data Feed Query Explorer to design filters that need URL encoding, since the explorer will automatically URL encode necessary strings and spaces for you.

Metric Filters
Operator Description URL Encoded Form Examples
== Equals %3D%3D Return results where the time on the page is exactly ten seconds:
filters=ga:timeOnPage%3D%3D10
!= Does not equal !%3D Return results where the time on the page is not ten seconds:
filters=ga:timeOnPage!%3D10
> Greater than %3E Return results where the time on the page is strictly greater than ten seconds:
filters=ga:timeOnPage%3E10
< Less than %3C Return results where the time on the page is strictly less than ten seconds:
filters=ga:timeOnPage%3C10
>= Greater than or equal to %3E%3D Return results where the time on the page is ten seconds or more:
filters=ga:timeOnPage%3E%3D10
<= Less than or equal to %3C%3D Return results where the time on the page is ten seconds or less:
filters=ga:timeOnPage%3C%3D10

Back to Top

Dimension Filters
Operator Description URL Encoded Form Example
== Exact match %3D%3D Aggregate metrics where the city is Irvine:
filters=ga:city%3D%3DIrvine
!= Does not match !%3D Aggregate metrics where the city is not Irvine:
filters=ga:city!%3DIrvine
=@ Contains substring %3D@ Aggregate metrics where the city contains York:
filters=ga:city%3D@York
!@ Does not contain substring !@ Aggregate metrics where the city does not contain York:
filters=ga:city!@York
=~ Contains a match for the regular expression %3D~ Aggregate metrics where the city starts with New:
filters=ga:city%3D~%5ENew.*
(%5E is the URL encoded from of the ^ character that anchors a pattern to the beginning of the string.)
!~ Does not match regular expression !~ Aggregate metrics where the city does not start with New:
filters=ga:city!~%5ENew.*

Back to Top

Filter Expressions


There are a couple of important rules for filter expressions:

  • URL-reserved characters — Characters such as & must be url-encoded in the usual way.
  • Reserved characters — The semicolon, comma, and backslash must all be backslash escaped when they appear in an expression.
    • semicolon \;
    • comma \,
    • backslash \\
  • Regular Expressions — You can also use regular expressions in filter expressions using the =~ and !~ operators. Their syntax is similar to Perl regular expressions and have these additional rules:
    • Maximum length of 128 characters — Regular expressions longer than 128 characters will result in a 400 Bad Request status code returned from the server.
    • Case sensitivity — Regular expression matching is case-insensitive.

For more information on common regular expression matches supported by Google Analytics, see What are regular expressions in the Help Center.

Combining Filters


Filters can be combined using OR and AND boolean logic. This allows you to effectively extend the 128 character limit of a filter expression.

OR

The OR operator is defined using a comma (,). It takes precedence over the AND operator and may NOT be used to combine dimensions and metrics in the same expression.

Examples: (each must be URL encoded)

Country is either (United States OR Canada):
ga:country==United%20States,ga:country==Canada

Firefox users on (Windows OR Macintosh) operating systems:
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

AND

The AND operator is defined using a semi-colon (;). It is preceded by the OR operator and CAN be used to combine dimensions and metrics in the same expression.

Examples: (each must be URL encoded)

Country is United States AND the browser is Firefox:
ga:country==United%20States;ga:browser==Firefox

Country is United States AND language does not start with 'en':
ga:country==United%20States;ga:language!~^en.*

Operating system is (Windows OR Macintosh) AND browser is (Firefox OR Chrome):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome

Country is United States AND sessions are greater than 5:
ga:country==United%20States;ga:sessions>5

Back to Top



segment

segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
Optional.

For complete details on how to request a segment in the Core Reporting API see the Segments Dev Guide.

For a conceptual overview of segments, see the Segments Feature Reference and Segments in the Help Center.

Dimensions and Metrics allowed in segments.
Not all dimensions and metrics can be used in segments. To review which dimensions and metrics are allowed in segments visit the Dimensions and Metrics Explorer.


start-date

start-date=2009-04-20
Required.
All Analytics feed requests must specify a beginning and ending date range. If you do not indicate start- and end-date values for the request, the server returns a request error. Date values are in the form YYYY-MM-DD.
The earliest valid start-date is 2005-01-01. There is no upper limit restriction for a start-date. However, setting a start-date that is too far in the future will most likely return empty results.

Back to Top

end-date

end-date=2009-05-20
Required.
All Analytics feed requests must specify a beginning and ending date range. If you do not indicate start- and end-date values for the request, the server returns a request error. Date values are in the form YYYY-MM-DD.
The earliest valid end-date is 2005-01-01. There is no upper limit restriction for an end-date. However, setting an end-date that is too far in the future might return empty results.

start-index

start-index=10
Optional.
If not supplied, the starting index is 1. (Feed indexes are 1-based. That is, the first entry is entry 1, not entry 0.) Use this parameter as a pagination mechanism along with the max-results parameter for situations when totalResults exceeds 10,000 and you want to retrieve entries indexed at 10,001 and beyond.


max-results

max-results=100
Optional.
Maximum number of entries to include in this feed. You can use this in combination with start-index to retrieve a subset of elements, or use it alone to restrict the number of returned elements, starting with the first. If you do not use the max-results parameter in your query, your feed returns the default maximum of 1000 entries.
The Analytics Core Reporting API returns a maximum of 10,000 entries per request, no matter how many you ask for. It can also return fewer entries than requested, if there aren't as many dimension segments as you expect. For instance, there are fewer than 300 possible values for ga:country, so when segmenting only by country, you can't get more than 300 entries, even if you set max-results to a higher value.

Back to Top



prettyprint

prettyprint=true
Optional.
Adds extra whitespace to the feed XML to make it more readable. This can be set to true or false, where the default is false. Use this parameter for debugging if you're looking at the feed responses directly.

Back to Top

Data Feed Response

The data feed returns data that is entirely dependent on the fields you specify in your request using the dimensions and metrics parameters. For a list of the available dimensions and metrics that you can query in the data feed, see the Dimensions & Metrics Reference. This section describes the general structure of the data feed as returned in XML, with a description for the key elements of interest for the data feed.

  • Data Feed
    • title—the string Google Analytics Data for View (Profile), followed by the ID of the selected view (profile)
    • id—the feed URL
    • totalResults—the total number of results for the query, regardless of the number of results in the response
    • startIndex—the starting index of the entries, which is 1 by default or otherwise specified by the start-index query parameter
    • itemsPerPage—the number of items in the current request, which is a maximum of 10,000
    • dxp:startDate—the first date for the query as indicated in the start-date query parameter
    • dxp:endDate—the ending date for the query as indicated in the end-date query parameter, inclusive of the date provided
    • dxp:containsSampledData—boolean value indicating whether any of the entries in this response contain sampled data. See Sampling below for details.
    • dxp:aggregates—contains the total values of each metric matched by the query. Some queries match more values in Google Analytics than can be returned by the API in a single page. When this happens, you will have to paginate through the results. The aggregate metric values contain the sum of each metric for the un-paginated data. This is different than the sum of the metric values returned in a single page, which the API does not return.
      • dxp:metric—metrics representing the total values of all metrics the query matched
        • name—the name of the metric
        • value—the un-paginated value of this metric
        • type—the type of the value returned. Can be: currency, float, percent, time, us_currency, an unknown type, or not set
    • dxp:dataSource—summary information about the Analytics source of the data
      • dxp:tableId —The unique, namespaced view (profile) ID of the source, such as ga:1174
      • dxp:tableName—The name of the view (profile) as it appears in the Analytics administrative UI
      • dxp:property name=ga:profileId—The view (profile) ID of the source, such as 1174
      • dxp:property name=ga:webPropertyId—The web property ID of the source, such as UA-30481-1
      • dxp:property name=ga:accountName—The name of the account as it appears in the Analytics interface.
    • dxp:segment—For both default and custom advanced segments, the feed returns the name and ID associated with the segment. For dynamic segments, the feed returns the expression contained in the request.
  • entry—Each entry in the response contains the following elements
    • title—the list of dimensions in the query and the matching result for that entry
    • dxp:dimension—one element for each dimension in the query
      • name—the name of the dimension
      • value—the value of the dimension
    • dxp:metric—one element for each metric in the query
      • name—the name of the metric
      • value—the aggregate value for the query for that metric (e.g. 24 for 24 pageviews)
      • type—the type of the value returned. Can be: currency, float, percent, time, us_currency, an unknown type, or not set

Back to Top

Data Feed Error Codes

The Core Reporting API returns a 200 HTTP status code if your request is successful. If an error or problem occurs with your request, the Data Feed returns HTTP status codes based on the type of error, along with a reason describing the nature of the error.

Note: The descriptive reason returned by the API may change at any time. For that reason, your application should not use string matching on the reason, but rather rely only on the error code.

The following list shows the possible error codes and corresponding reasons.

  • 400 Bad Request
    Types of bad requests include:
    • Invalid dimensions and/or metrics
    • Quantity: either no metric, or too many dimensions/metrics
    • Using OR on a filter where one side is a metric and the other a dimension
    • Invalid filter/segment syntax
    • Illegal dimension/metric combination or advanged segment
  • 401 Unauthorized
    Types of authentication issues include:
    • Invalid username or password
    • Invalid authorization token
  • 403 Forbidden
    Types of authorization issues include:
    • Permissions: user is not authorized to access the requested view (profile)
    • Using account ID (instead of view (profile) ID)
  • 500 Internal Server Error
    Do not retry.
  • 503 Service Unavailable
    Types of service issues are listed below. Be sure to check the X-Google-Command header to determine whether a retry is allowed.
    • Timeout
    • Server error
    • Service unavailable
    • Insufficient quota

Back to Top

Sampling

Google Analytics calculates certain combinations of dimensions and metrics on the fly. To return the data in a reasonable time, Google Analytics only processes a sample of the data.

If the data you see from the Core Reporting API doesn't match the web interface, use the containsSampledData top-level response element to determine if the data has been sampled.

Use the containsSampledData top-level response element to determine if any metric values in the response entries contain sampled data.

See Sampling for a general description of sampling and how it is used with Google Analytics.

Handling Large Data Results

If you expect your query to return large result sets, the guidelines below will help you optimize your API query, avoid errors, and minimize quota overruns. Keep in mind that we establish a baseline level of optimization for any given API request by allowing a maximum number of dimensions (7) and metrics (10). While some queries that specify large numbers of metrics and dimensions can take longer to process than others, limiting the number of requested metrics does not generally improve query performance. Instead, you can use the following techniques for the best performance results.

Paging

Paging through results can be a useful way to break large results sets into manageable chunks.  The data feed tells you how many matching rows exist, along with giving you the requested subset of rows.  If there is a high ratio of total matching rows to number of rows actually returned, then the individual queries might be taking longer than necessary. If you need only a limited number of rows, such as for display purposes, setting an explicit limit is fine. However, if the purpose of your application is to process a large set of results in its entirety, then it is most efficient to request the maximum allowed rows.

Splitting the Query by Date Range

Instead of paging through the date-keyed results of one long date range, consider forming separate queries for one week—or even one day—at a time.  For a very large data set, it may still be necessary to page through results, such as when a request for one day still contains more than the maximum number of result rows per query.  In any case, if the number of matching rows for your query is higher than the max results rows, breaking apart the date range may improve the total time to retrieve the answer. This is true whether the queries are being sent in a single thread or in parallel.

Use Filters Intelligently

Consider whether additional filters might reduce the data while still providing the information you need.  Can a dimension filter, such as a regular expression match on a page path, return the subset of the data you care about?  Can value thresholds (such as ignoring matches with less than 5 sessions) filter out less interesting results?  This approach can be used as a complement to any of the other suggestions mentioned earlier. With this technique, the actual time to get each result set is likely to be about the same, but fewer result pages would be retrieved, thus reducing the overall interaction time and minimizing impact on your quota allowance.

Back to Top

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.