Google Analytics Reporting

Reporting gives you access to most of the report data in Google Analytics. With the Core Reporting API you can:

  • Build custom dashboards to display Google Analytics data.
  • Save time by automating complex reporting tasks.
  • Integrate your Google Analytics data with other business applications.

There are some intricacies with reporting that particularly raises the learning curve. We manage to simplify reporting to one call but with various optional methods and each option needs to be explained in detail. We'll first cover a full usage case, methods then go over these very details.

Figure 1. Usage: A Blown Out Call
$reporting
	->setStartIndex(0)
	->setMaxResults(1000)
	->setDimesion($dimensions)
	->setSort($sort)
	->setFilters($filters)
	->setSegment($segment)
	->setFields($fields)
	->setPrettyPrint($prettyPrint)
	->setUserIp($userIp)
	->setQuotaUser($quotaUser)
	->debug(true)
	->getInfo('ga:59435283', 
		time() - (3600 * 24 * 28), 
		time() - (3600 * 24 * 2), 
		'ga:visits');
Figure 2. Reporting Methods
Method Arguments Returns Description
$reporting->setStartIndex($startIndex);
  1. integer
Eden_Google_Analytics_Reporting Set start index
$reporting->setMaxResults($maxResults);
  1. integer
Eden_Google_Analytics_Reporting Set Max results
$reporting->setDimensions($dimensions);
  1. string|array
  2. - The dimensions parameter breaks down metrics by common criteria; for example, by ga:browser or ga:city.
Eden_Google_Analytics_Reporting Set dimensions
$reporting->setSort($sort);
  1. string|array
  2. - Example: ga:country,ga:browser.
Eden_Google_Analytics_Reporting Sorting order is specified by the left to right order of the metrics and dimensions listed. Sorting direction defaults to ascending and can be changed to descending by using a minus sign (-) prefix on the requested field.
$reporting->setFilters($filters);
  1. string
  2. - Example: ga:browser >= FireFox
Eden_Google_Analytics_Reporting Dimension or metric filters that restrict the data returned for your request.
$reporting->setSegments($segments);
  1. string|array
  2. - Example: dynamic::ga:medium%3D%3Dreferral.
Eden_Google_Analytics_Reporting Segments the data returned for your request.
$reporting->setFields($fields);
  1. string
  2. - Example: rows,columnHeaders(name,dataType).
Eden_Google_Analytics_Reporting Selector specifying a subset of fields to include in the response.
$reporting->setPrettyPrint($prettyPrint);
  1. integer
Eden_Google_Analytics_Reporting Returns response with indentations and line breaks.
$reporting->setUserIp($userIp);
  1. string
Eden_Google_Analytics_Reporting Specifies IP address of the end user for whom the API call is being made.
$reporting->setQuotaUser($quotaUser);
  1. string
Eden_Google_Analytics_Reporting Alternative to userIp in cases when the user's IP address is unknown.
$reporting->getInfo($id, $startDate, $endDate, $metrics);
  1. string
  2. - Unique table ID of the form
  3. string
  4. - First date of the date range for which you are requesting the data. YYYY-MM-DD.
  5. string
  6. - Last date of the date range for which you are requesting the data. YYYY-MM-DD.
  7. string
  8. - List of comma-separated metrics, such as ga:visits,ga:bounces.
array Returns all accounts to which the user has access.

Dimensions

The dimensions parameter breaks down metrics by common criteria; for example, by $reporting->addDimensionBrowser() or $reporting->addDimensionCity().

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 broken down by browser. In this case, you'll see the number of pageviews from Firefox, Internet Explorer, Chrome, and so forth.

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

  • You can supply a maximum of 7 dimensions in any query.
  • You can not send a query composed only of dimensions: you must combine any requested dimensions with at least one metric.
  • Only certain dimensions can be queried in the same query. Use the valid combination tool in the Dimensions and Metrics Reference to see which dimensions can be used together.

Metrics

The aggregated statistics for user activity to your site, such as clicks or pageviews.

If a query has no dimensions parameter, the returned metrics provide aggregate values for the requested date range,such as overall pageviews or total bounces. However, when dimensions are requested, values are segmented by dimension value. For example, pageViews requested with country returns the total pageviews per country. When requesting metrics, keep in mind:

  • Any request must supply at least one metric; a request cannot consist only of dimensions.
  • You can supply a maximum of 10 metrics for any query.
  • Most combinations of metrics from multiple categories can be used together, provided no dimensions are specified.
  • A metric can be used in combination with other dimensions or metrics, but only where valid combinations apply for that metric. See the Dimensions and Metrics Reference for details.

Sort

A list of metrics and dimensions indicating the sorting order and sorting direction for the returned data.

  • Sorting order is specified by the left to right order of the metrics and dimensions listed.
  • Sorting direction defaults to ascending and can be changed to descending by using a minus sign (-) prefix on the requested field.

Sorting the results of a query enables you to ask different questions about your data. For example, to address the question "What are my top countries, and which browsers do they use most?" you can make a query with the the following parameter. It sorts first by ga:country and then by ga:browser, both in ascending order:

$reporting->sortByCountry()->sortByBrowser();

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

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

Filters

The filters query string parameter restricts the data returned from your request. To use the filters parameter, supply a dimension or metric on which to filter, followed by the filter expression. For example, the following query requests ga:pageviews and ga:browser for profile 12134, where the ga:browser dimension starts with the string Firefox:

 $reporting->setFilter('browser =~ ^Firefox'); 

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 Google API client libraries automatically encode the filter operators.
  • 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 the Dimensions and Metrics Reference for more information.
Filter Syntax

A single filter uses the form:

name operator expression

In this syntax:

  • name — the name of the dimension or metric to filter on. For example: pageviews filters 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 to be included in or excluded from the results. Expressions use regular expression syntax.
Filter Operators

There are six filter operators for dimensions and six filter operators for metrics.

Metric Filters
Operator Description Examples
== Equals Return results where the time on the page is exactly ten seconds:
$reporting->setFilter('timeOnPage == 10');
!= Does not equal Return results where the time on the page is not ten seconds:
$reporting->setFilter('timeOnPage != 10');
> Greater than 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
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.*
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 result in a 400 Bad Request status code returned from the server.
    • Case sensitivity — Regular expression matching is case-insensitive.
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 visits are greater than 5:
ga:country==United%20States;ga:visits>5


© 2012 Openovate Labs. All rights reserved.