This document explains how to use the Core Reporting API to access Google Analytics Data.
Introduction
The Core Reporting API provides access to the tabular data in Google Analytics standard and custom reports. To access data, you create a query that specifies: the view (profile), the start and end dates, and the dimensions and metrics that make up the column headers in the table. This query is sent to the Core Reporting API and The Core Reporting API returns all the data in the form of a table.
If you are new to the API, read the Core Reporting API Overview for an introduction to purpose of the Core Reporting API and the data it provides.
Before You Begin
This guide demonstrates how to access the Google Analytics API using the Java, Python, PHP, and JavaScript programming languages.
- Read the client libraries page for a complete list of programming language specific client libraries that work with the API.
- Read the Reference Guide to access the API without a client library.
Each client library provides a single analytics service object to access all Core Reporting API data. To create the service object you generally have to go through the following steps:
- Register your application in the Google API Console.
- Authorize access to Google Analytics data.
- Create an Analytics service object.
If you haven't completed these steps, please stop and read the Hello Google Analytics API Tutorial. This tutorial will walk you through the initial steps of building a Google Analytics API application. Once complete, you will be able to use this guide to perform real-world tasks.
The following code snippet contains a variable to store an authorized service object.
Java
Analytics analytics = // Read Hello Analytics Tutorial for details.
Python
analytics = # Read Hello Analytics Tutorial for details.
PHP
$client = // Read Hello Analytics Tutorial for details. // Return results as objects. $client->setUseObjects(true); $analytics = new apiAnalyticsService($client);
The PHP library will return all the API results as an associative array. To return real
objects instead, you can call the client useObject
method
as demonstrated in the example above.
JavaScript
<script src="https://apis.google.com/js/client.js?onload=loadLib"</script> <script> function loadLib() { // Handle all the authorization work. // Read Hello Analytics Tutorial for details. gapi.client.load('analytics', 'v3', makeApiCall); } </script>
The first script tag loads the Google API JavaScript library. Once
loaded, loadLib
is executed to load the analytics service class.
Once complete, the object gapi.client.analytics
should exist
in the DOM and be ready to use to query the Core Reporting API.
Once you create an analytics service object, you are ready to make requests to the Core Reporting API.
Note: The analytics service object can also be used to access the Management API.
Overview
An application that uses the Core Reporting API will generally follow 2 steps:
- Query the Core Reporting API
- Work with the API results
Let's look at both steps.
Query the Core Reporting API
Build a Core Reporting API query
The analytics service object contains a method to build a Core Reporting API query.
Each Core Reporting API query contains a set of parameters which specify what data to return.One of the most important query parameters is the ids
parameter, or the table ID. This parameter specifies from which
Google Analytics view (profile) to retrieve data. The value is in the format
ga:xxx
where xxx
is the view (profile) ID.
Java
Get apiQuery = analytics.data().ga() .get(tableId, // Table Id. "2012-01-01", // Start date. "2012-01-15", // End date. "ga:sessions") // Metrics. .setDimensions("ga:source,ga:keyword") .setSort("-ga:sessions,ga:source") .setFilters("ga:medium==organic") .setMaxResults(25);
Python
api_query = service.data().ga().get( ids=TABLE_ID, start_date='2012-01-01', end_date='2012-01-15', metrics='ga:sessions', dimensions='ga:source,ga:keyword', sort='-ga:sessions,ga:source', filters='ga:medium==organic', max_results='25')
PHP
private function queryCoreReportingApi() { $optParams = array( 'dimensions' => 'ga:source,ga:keyword', 'sort' => '-ga:sessions,ga:source', 'filters' => 'ga:medium==organic', 'max-results' => '25'); return $service->data_ga->get( TABLE_ID, '2010-01-01', '2010-01-15', 'ga:sessions', $optParams); }
In this library, the get
method not only creates a Core Reporting API query,
but also executes the request to the API.
JavaScript
function makeApiCall() { var apiQuery = gapi.client.analytics.data.ga.get({ 'ids': TABLE_ID, 'start-date': '2010-01-01', 'end-date': '2010-01-15', 'metrics': 'ga:sessions', 'dimensions': 'ga:source,ga:keyword', 'sort': '-ga:sessions,ga:source', 'filters': 'ga:medium==organic', 'max-results': 25 }); // ... }
In this example, the makeApiCall
function is called once the
JavaScript client library has loaded. Inside, the function creates a new
Google Analytics API query and stores the object in the apiQuery
variable.
A complete listing of all the query parameters and what they do can be found in the Core Reporting API reference guide. Also the dimension and metric parameters allow you to specify what data to retrieve from Google Analytics. A complete list can be found on the dimensions and metrics reference page.
Making a Core Reporting API data request
Once you have a query defined, you call it's execute
method
to send the query to Google Analytics servers.
Java
try { apiQuery.execute(); // Success. Do something cool! } catch (GoogleJsonResponseException e) { // Catch API specific errors. handleApiError(e); } catch (IOException e) { // Catch general parsing network errors. e.printStackTrace(); }
If you prefer to access the raw API response instead,
use the executeUnparsed()
method:
HttpResponse response = apiQuery.executeUnparsed();
Python
try: results = get_api_query(service).execute() print_results(results) except TypeError, error: # Handle errors in constructing a query. print ('There was an error in constructing your query : %s' % error) except HttpError, error: # Handle API service errors. print ('There was an API error : %s : %s' % (error.resp.status, error._get_reason()))
PHP
try { $results = queryCoreReportingApi(); // Success. Do something cool! } catch (apiServiceException $e) { // Handle API service exceptions. $error = $e->getMessage(); }
JavaScript
function makeApiCall() { // ... apiQuery.execute(handleCoreReportingResults); } function handleCoreReportingResults(results) { if (!results.error) { // Success. Do something cool! } else { alert('There was an error: ' + results.message); } }
This example follows from the previous step where a Core
Reporting API query was created. In this step, the query is executed.
The parameter to the execute
method is a reference to a callback
function that will get executed once data is returned from the API.
Once the API returns with results, the callback function is executed and
is passed the data from the API. If an error occurs, the results will
contain a property named error
.
In this example, a check is made to see if error
exists or whether
the API returned successfully.
If the query was successful, the API will return the requested data. If any errors occur, the API will return a specific status code and a message describing the error. All applications should properly catch and handle errors.
Working with the API results
If the Core Reporting API query was successful, the API returns with the Analytics reporting data as well as other related information about the data.
Analytics reporting data
The main data returned from the API can be thought of as a table with 2 main types of data:
- The header that describes the types of values in each column
- The rows of data in the table
Column header data
Each API response contains a column header field that represents the header information of the table. The field is a list (or an array) of objects where each object describes the type of data in the column. The column order is dimensions columns followed by metric columns in the same order as specified in the original query.
Java
private void printColumnHeaders(GaData gaData) { System.out.println("Column Headers:"); for (GaDataColumnHeaders header : gaData.getColumnHeaders()) { System.out.println("Column Name: " + header.getName()); System.out.println("Column Type: " + header.getColumnType()); System.out.println("Column Data Type: " + header.getDataType()); } }
Python
def print_column_headers(): headers = results.get('columnHeaders') for header in headers: # Print Dimension or Metric name. print 'Column name = %s' % header.get('name')) print 'Column Type = %s' % header.get('columnType') print 'Column Data Type = %s' % header.get('dataType')
PHP
private function printColumnHeaders(&results) { $html = ''; $headers = $results->getColumnHeaders(); foreach ($headers as $header) { $html .= <<<HTML Column Name = {$header->getName()} Column Type = {$header->getColumnType()} Column Data Type = {$header->getDataType()} HTML; print $html; }
JavaScript
function printColumnHeaders(results) { var output = []; for (var i = 0, header; header = results.columnHeaders[i]; ++i) { output.push( 'Name = ', header.name, '\n', 'Column Type = ', header.columnType, '\n', 'Data Type = ', header.dataType, '\n' ); } alert(output.join('')); }
Row data
The main data returned from the API is returned as a 2-dimensional
List
of strings. The outer list represents all the rows of data.
Each inner list represents a single row, where the order of cells in a row
is same as the fields in the column header object described above.
Since data in each cell is returned as a string, the DataType
field
in each column header object is particularly useful since it can be used
to parse string values into an appropriate type. See the
metadata API response for all the possible data types.
The following examples print both the headers and rows of the table.
Java
private void printDataTable(GaData gaData) { if (gaData.getTotalResults() > 0) { System.out.println("Data Table:"); // Print the column names. for (GaDataColumnHeaders header : gaData.getColumnHeaders()) { System.out.format("%-32s", header.getName() + '(' + header.getDataType() + ')'); } System.out.println(); // Print the rows of data. for (List<String> rowValues : gaData.getRows()) { for (String value : rowValues) { System.out.format("%-32s", value); } System.out.println(); } } else { System.out.println("No Results Found"); }
Python
def print_data_table(results): # Print headers. output = [] for header in results.get('columnHeaders'): output.append('%30s' % header.get('name')) print ''.join(output) # Print rows. if results.get('rows', []): for row in results.get('rows'): output = [] for cell in row: output.append('%30s' % cell) print ''.join(output) else: print 'No Results Found'
PHP
private function printDataTable(&$results) { if (count($results->getRows()) > 0) { $table .= '<table>'; // Print headers. $table .= '<tr>'; foreach ($results->getColumnHeaders() as $header) { $table .= '<th>' . $header->name . '</th>'; } $table .= '</tr>'; // Print table rows. foreach ($results->getRows() as $row) { $table .= '<tr>'; foreach ($row as $cell) { $table .= '<td>' . htmlspecialchars($cell, ENT_NOQUOTES) . '</td>'; } $table .= '</tr>'; } $table .= '</table>'; } else { $table .= '<p>No Results Found.</p>'; } print $table; }
JavaScript
function printRows(results) { output = []; if (results.rows && results.rows.length) { var table = ['<table>']; // Put headers in table. table.push('<tr>'); for (var i = 0, header; header = results.columnHeaders[i]; ++i) { table.push('<th>', header.name, '</th>'); } table.push('</tr>'); // Put cells in table. for (var i = 0, row; row = results.rows[i]; ++i) { table.push('<tr><td>', row.join('</td><td>'), '</td></tr>'); } table.push('</table>'); output.push(table.join('')); } else { output.push('<p>No Results Found</p>'); } alert(output.join('')); }
Report information
Along with the main table data, the data returned from the API contains some high level information about the response. You can print it using:
Java
private void printResponseInfo(GaData gaData) { System.out.println("Contains Sampled Data: " + gaData.getContainsSampledData()); System.out.println("Kind: " + gaData.getKind()); System.out.println("ID:" + gaData.getId()); System.out.println("Self link: " + gaData.getSelfLink()); }
Python
def print_response_info(results): print 'Contains Sampled Data = %s' % results.get('containsSampledData') print 'Kind = %s' % results.get('kind') print 'ID = %s' % results.get('id') print 'Self Link = %s' % results.get('selfLink')
PHP
private function printReportInfo(&$results) { $html = <<<HTML <pre> Contains Sampled Data = {$results->getContainsSampledData()} Kind = {$results->getKind()} ID = {$results->getId()} Self Link = {$results->getSelfLink()} </pre> HTML; print $html; }
JavaScript
function printReportInfo(results) { var output = []; output.push( 'Contains Sampled Data = ', results.containsSampledData, '\n', 'Kind = ', results.kind, '\n', 'ID = ', results.id, '\n', 'Self Link = ', results.selfLink, '\n'); alert(output.join('')); }
The containsSampledData
field is important because it
describes whether the API response has been sampled.
Sampling can affect the results of your data and a common reason
why the values returned from the API do not match the web interface. See the
Sampling
concept guide for more details.
View (Profile) information
Each response contains a group of parameters which indicate the Account, Web Property, and View (Profile) this data belongs to.
Java
private void printProfileInfo(GaData gaData) { GaDataProfileInfo profileInfo = gaData.getProfileInfo(); System.out.println("Account ID: " + profileInfo.getAccountId()); System.out.println("Web Property ID: " + profileInfo.getWebPropertyId()); System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId()); System.out.println("View (Profile) ID: " + profileInfo.getProfileId()); System.out.println("View (Profile) Name: " + profileInfo.getProfileName()); System.out.println("Table ID: " + profileInfo.getTableId()); }
Python
def print_profile_info(result): info = results.get('profileInfo') print 'Account Id = %s' % info.get('accountId') print 'Web Property Id = %s' % info.get('webPropertyId') print 'Web Property Id = %s' % info.get('internalWebPropertyId') print 'View (Profile) Id = %s' % info.get('profileId') print 'Table Id = %s' % info.get('tableId') print 'View (Profile) Name = %s' % info.get('profileName')
PHP
private function printProfileInformation(&$results) { $profileInfo = $results->getProfileInfo(); $html = <<<HTML <pre> Account ID = {$profileInfo->getAccountId()} Web Property ID = {$profileInfo->getWebPropertyId()} Internal Web Property ID = {$profileInfo->getInternalWebPropertyId()} Profile ID = {$profileInfo->getProfileId()} Table ID = {$profileInfo->getTableId()} Profile Name = {$profileInfo->getProfileName()} </pre> HTML; print $html; }
JavaScript
function printProfileInfo(results) { var output = []; var info = results.profileInfo; output.push( 'Account Id = ', info.accountId, '\n', 'Web Property Id = ', info.webPropertyId, '\n', 'View (Profile) Id = ', info.profileId, '\n', 'Table Id = ', info.tableId, '\n', 'View (Profile) Name = ', info.profileName); alert(output.join('')); }
Each of these ID corresponds to various entities in the Management API hierarchy. You can use these IDs to form Management API queries to get additional configuration information about the view (profile). For example, you can query the Management API Goals Collection to see which Goals are active along with their configured goal names.
Query information
Each Core Reporting API response contains an object that contains all the query parameter values used to create the response.
Java
private void printQueryInfo(GaData gaData) { GaDataQuery query = gaData.getQuery(); System.out.println("Ids: " + query.getIds()); System.out.println("Start Date: " + query.getStartDate()); System.out.println("End Date: " + query.getEndDate()); System.out.println("Metrics: " + query.getMetrics()); // List System.out.println("Dimensions: " + query.getDimensions()); System.out.println("Sort: " + query.getSort()); // List System.out.println("Segment: " + query.getSegment()); System.out.println("Filters: " + query.getFilters()); System.out.println("Start Index: " + query.getStartIndex()); System.out.println("Max Results: " + query.getMaxResults()); }
Python
def print_query_info(results): query = results.get('query') for key, value in query.iteritems(): print '%s = %s' % (key, value)
PHP
private function printQueryParameters(&$results) { $query = $results->getQuery(); $html = '<pre>'; foreach ($query as $paramName => $value) { $html .= "$paramName = $value\n"; } $html .= '</pre>'; print $html; }
JavaScript
function printQuery(results) { output = []; for (var key in results.query) { output.push(key, ' = ', results.query[key], '\n'); } alert(output.join('')); }
The metrics
and sort
parameters are returned as values in a list, while the other
parameters are returned as strings.
Pagination information
Any Core Reporting API request might match hundreds of thousands of rows of Google Analytics data. The Core Reporting API will only return a subset at a given time, which can be referred to as a single page of data. You use the pagination fields to retrieve all pages of data.
Java
private void printPaginationInfo(GaData gaData) { System.out.println("Items Per Page: " + gaData.getItemsPerPage()); System.out.println("Total Results: " + gaData.getTotalResults()); System.out.println("Previous Link: " + gaData.getPreviousLink()); System.out.println("Next Link: " + gaData.getNextLink()); }
Python
def print_pagination_info(results): print 'Items per page = %s' % results.get('itemsPerPage') print 'Total Results = %s' % results.get('totalResults') print 'Previous Link = %s' % results.get('previousLink') print 'Next Link = %s' % results.get('nextLink')
PHP
private function getPaginationInfo(&$results) { $html = <<<HTML <pre> Items per page = {$results->getItemsPerPage()} Total results = {$results->getTotalResults()} Previous Link = {$results->getPreviousLink()} Next Link = {$results->getNextLink()} </pre> HTML; print $html; }
JavaScript
function printPaginationInfo(results) { var output = []; output.push( 'Items Per Page = ', results.itemsPerPage, '\n', 'Total Results = ', results.totalResults, '\n', 'Previous Link = ', results.previousLink, '\n', 'Next Link = ', results.nextLink, '\n'); alert(output.join('')); }
The totalResults
field represents the total number of
rows of data that your query matched in Google Analytics. This can be greater than
the actual number of rows returned in a single page of the response.
The itemsPerPage
field represents the number of rows returned in this page.
The previousLink
and nextLink
parameters
are only present if there exists a previous or next page. Check these
links to see if more pages of data can be retrieved
from the Core Reporting API.
Totals for all results
As mentioned in the
pagination information section above,
a query to the Core Reporting API can match many rows
of data in Google Analytics, but only return a subset of data.
The total metric values for all the matched rows are returned
in the totalsForAllResults
object.
This data is useful for calculating averages.
Java
private void printTotalsForAllResults(GaData gaData) { MaptotalsMap = gaData.getTotalsForAllResults(); for (Map.Entry entry : totalsMap.entrySet()) { System.out.println(entry.getKey() + " : " + entry.getValue()); } }
Python
def print_totals_for_all_results(results): totals = results.get('totalsForAllResults') for metric_name, metric_total in totals.iteritems(): print 'Metric Name = %s' % metric_name print 'Metric Total = %s' % metric_total
PHP
private function printTotalsForAllResults(&$results) { $totals = $results->getTotalsForAllResults(); foreach ($totals as $metricName => $metricTotal) { $html .= "Metric Name = $metricName\n"; $html .= "Metric Total = $metricTotal"; } print $html; }
JavaScript
function printTotalsForAllResults(results) { var output = []; var totals = results.totalsForAllResults; for (metricName in totals) { output.push( 'Metric Name = ', metricName, '\n', 'Metric Total = ', totals[metricName], '\n'); } alert(output.join('')); }
Working Samples
To see the full working samples check out the Core Reporting API Sample in each client library's sample directory.
Java
Google API Java client library Core Reporting API Sample
Python
Google API Python client library Core Reporting API Sample
PHP
Google API PHP client library Core Reporting API Sample
JavaScript
Google API JavaScript client library Core Reporting API Sample