This document provides a detailed reference on the data feed for version 2.4 of the Core Reporting API.
Reports in the Analytics user interface are generally organized into these categories:
- Traffic Sources
- Internal Site Search
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).
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.
&segment=gaid::-10 OR segment=sessions::condition::ga:medium%3D%3Dreferral
<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.
dimensionsparameter defines the primary data keys for your Analytics report, such as
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 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.
|(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.
ga:countryreturns 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.
Indicates the sorting order and direction for the returned data. For example,
the following parameter would first sort by
ga:browser and then
ga:pageviews in ascending order.
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:
Sorting occurs first by
ga:browser, then by
However, if the query uses a different order:
dimensions=ga:country,ga:browserSorting occurs first by
ga:country, then by
When using the
sort parameter, keep in mind the following:
- Sort only by dimensions or metrics value that you have used in the
metricsparameter. 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:
|sorts ascending by
||sorts first in descending order by
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:browser from view (profile)
12134, where the
ga:browser dimension starts with the string
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.
- 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.
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:pageviewswill 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.
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.
|Operator||Description||URL Encoded Form||Examples|
||Return results where the time on the page is exactly ten seconds:
||Does not equal||
||Return results where the time on the page is not ten seconds:
||Return results where the time on the page is strictly greater than ten seconds:
||Return results where the time on the page is strictly less than ten seconds:
||Greater than or equal to||
||Return results where the time on the page is ten seconds or more:
||Less than or equal to||
||Return results where the time on the page is ten seconds or less:
|Operator||Description||URL Encoded Form||Example|
||Aggregate metrics where the city is Irvine:
||Does not match||
||Aggregate metrics where the city is not Irvine:
||Aggregate metrics where the city contains York:
||Does not contain substring||
||Aggregate metrics where the city does not contain York:
||Contains a match for the regular expression||
||Aggregate metrics where the city starts with New:
(%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:
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.
- Regular Expressions — You can also use regular expressions in filter expressions
!~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 Requeststatus code returned from the server.
- Case sensitivity — Regular expression matching is case-insensitive.
- Maximum length of 128 characters — Regular expressions longer than 128 characters will result in a
For more information on common regular expression matches supported by Google Analytics, see What are regular expressions in the Help Center.
Filters can be combined using
AND boolean logic. This
allows you to effectively extend the 128 character limit of a filter expression.
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):
Firefox users on (Windows OR Macintosh) operating systems:
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:
Country is United States AND language does not start with 'en':
Operating system is (Windows OR Macintosh) AND browser is (Firefox OR Chrome):
Country is United States AND sessions are greater than 5:
For complete details on how to request a segment in the Core Reporting API see the Segments Dev Guide.
Dimensions and Metrics allowed in
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.
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.
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.
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
totalResultsexceeds 10,000 and you want to retrieve entries indexed at 10,001 and beyond.
start-indexto 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-resultsparameter in your query, your feed returns the default maximum of 1000 entries.
ga:country, so when segmenting only by country, you can't get more than 300 entries, even if you set
max-resultsto a higher value.
false, where the default is
false. Use this parameter for debugging if you're looking at the feed responses directly.
Data Feed Response
The data feed returns data that is entirely dependent on the fields you specify in your request using the
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
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
dxp:endDate—the ending date for the query as indicated in the
end-datequery 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
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
dxp:property name=ga:webPropertyId—The web property ID of the source, such as
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
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
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
Types of authentication issues include:
- Invalid username or password
- Invalid authorization token
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-Commandheader to determine whether a retry is allowed.
- Server error
- Service unavailable
- Insufficient quota
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.
containsSampledData top-level response element to
determine if any metric values in the response entries contain sampled
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 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.