This document explains how to use the Multi-Channel Funnels Reporting API to access Multi-Channel Funnels Data.
Introduction
The Multi-Channel Funnels Reporting API provides access to the tabular data in Multi-Channel Funnels 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 Multi-Channel Funnels Reporting API and The Multi-Channel Funnels Reporting API returns all the data in the form of a table.
If you are new to the API, read the Multi-Channel Funnels Reporting API Overview for an introduction to purpose of the Multi-Channel Funnels Reporting API and the data it provides.
Before You Begin
This guide uses the Java client library to access the Multi-Channel Funnels Reporting API. Each client library provides a single Analytics service object to call the Multi-Channel Funnels Reporting API to get the data. If you don't use a client library to access the API, read the Multi-Channel Funnels Reporting API - Reference Guide.
To create the Analytics service object:
- Register your application in Google API Console.
- Authorize access to Google Analytics data.
- Write code to create the Analytics service object.
If you haven't completed these steps, stop and read the Hello Analytics API Tutorial, which walks you through the initial steps of building a Google Analytics API application. After completing the tutorial, continue to read the following guide.
For example, the following code creates an authorized Analytics service object:
Java
Analytics analytics = initializeAnalytics();
Use the Analytics service object analytics
to call
the Multi-Channel Funnels Reporting API.
Overview
To use the Multi-Channel Funnels Reporting API to retrieve data, write an application to:
- Query the Multi-Channel Funnels Reporting API.
- Work with the results returned from the API.
Query the Multi-Channel Funnels Reporting API
To request data from the Multi-Channel Funnels Reporting API:
- Build a Multi-Channel Funnels Reporting API query object.
- Use the query object to request the data from the Multi-Channel Funnels servers.
Build a Multi-Channel Funnels Reporting API query
To build a Multi-Channel Funnels Reporting API query object, call this method:
analytics.data.mcf.get() // analytics is the Analytics service object
The first parameter supplied to the method is a unique table ID
in the form of ga:XXXX
, where XXXX
is the
ID of an Analytics view (profile) containing the requested data.
Use the query object to specify query parameters
(i.e., setDimensions
). For example:
Java
Get apiQuery = analytics.data().mcf() .get(tableId, "2012-01-01", // Start date "2012-03-31", // End date "mcf:totalConversions") // Metrics .setDimensions("mcf:sourcePath") .setSort("-mcf:totalConversions") .setMaxResults(25);
For a list of all query parameters, see Query Parameters Summary. The metrics and dimensions parameters let you specify what data from Multi-Channel Funnels to retrieve. For a list of all dimensions and metrics, see the Dimensions & Metrics Reference.
Making a Multi-Channel Funnels Reporting API data request
After creating the query object, call the execute
method
on the object to request data from Multi-Channel Funnels servers. For example:
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,
call the executeUnparsed()
method on the
query object:
HttpResponse response = apiQuery.executeUnparsed();
If the query is successful, it returns the requested data. If an error
occurs, the execute
method throws an exception containing
a status code for the error and a description of the error. The application
should catch and handle the exception.
Work with the API Results
If the Multi-Channel Funnels Reporting API query is successful, it returns the reporting data and information about the data.
Multi-Channel Funnels reporting data
The query returns the following tabular reporting data:
- Column header data
- Row data
Column header data
The query response has a column header field that contains the table
header information. The field is a list (or an array) of
ColumnHeaders
objects, each of which contains column name,
column type, and column data type. The column order is dimensions columns
followed by metric columns in the same order as specified
in the original query. For example, the following method prints the
columns headers:
Java
private static void printColumnHeaders(McfData mcfData) { System.out.println("Column Headers:"); for (ColumnHeaders header : mcfData.getColumnHeaders()) { System.out.println("Column Name: " + header.getName()); System.out.println("Column Type: " + header.getColumnType()); System.out.println("Column Data Type: " + header.getDataType()); } }
Row data
The main data returned from the API is returned as a 2-dimensional
List
of McfData.Rows
. Each McfData.Rows
represents a single cell which is either a primitive value of String
type, or a conversion path value of McfData.Rows.ConversionPathValue
type. The order of cells in a row is the same as the fields in the column header
object described above.
Since data in each cell is returned either as a string or as a Multi-Channel Funnels
sequence type, the DataType
field in each column header object
is particularly useful for parsing values into appropriate types.
See the
reference guide for all the possible data types.
For example, the following method prints the table headers and rows:
Java
private static void printDataTable(McfData mcfData) { System.out.println("Data Table:"); if (mcfData.getTotalResults() > 0) { // Print the column names. List<ColumnHeaders> headers = mcfData.getColumnHeaders(); for (ColumnHeaders header : headers) { System.out.print(header.getName()); } System.out.println(); // Print the rows of data. for (List<McfData.Rows> row : mcfData.getRows()) { for (int columnIndex = 0; columnIndex < row.size(); ++columnIndex) { ColumnHeaders header = headers.get(columnIndex); McfData.Rows cell = row.get(columnIndex); if (header.getDataType().equals("MCF_SEQUENCE")) { System.out.print(getStringFromMcfSequence(cell.getConversionPathValue())); } else { System.out.print(cell.getPrimitiveValue()); } } System.out.println(); } } else { System.out.println("No rows found"); } }
The following example shows how to parse a Multi-Channel Funnels sequence type object and convert it to a string:
Java
private static String getStringFromMcfSequence(List<McfData.Rows.ConversionPathValue> path) { StringBuilder stringBuilder = new StringBuilder(); for (McfData.Rows.ConversionPathValue pathElement : path) { if (stringBuilder.length() > 0) stringBuilder.append(" > "); stringBuilder.append(pathElement.getNodeValue()); } return stringBuilder.toString(); }
Report information
In addition to the reporting data, the query returns information (report ID, for example) about the data. For example, the following method prints the report information:
Java
private static void printReportInfo(McfData mcfData) { System.out.println("Report Info:"); System.out.println("ID:" + mcfData.getId()); System.out.println("Self link: " + mcfData.getSelfLink()); System.out.println("Kind: " + mcfData.getKind()); System.out.println("Contains Sampled Data: " + mcfData.getContainsSampledData()); }
The containsSampledData
field
tells you whether the query response has been sampled.
Because sampling can affect the query results,
sampled values returned from the query (API) do not match those
shown on the web interface. See
Sampling
for more details.
View (Profile) information
The query response includes the web property ID, view (profile) name and ID, and the ID of the Analytics account containing the view (profile). For example, the following method prints them to the terminal (standard output):
Java
private static void printProfileInfo(McfData mcfData) { ProfileInfo profileInfo = mcfData.getProfileInfo(); System.out.println("View (Profile) Info:"); 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()); }
Query information
The query response includes a Query
object that contains
the values of all data request query parameters. For example,
the following method prints the values of such parameters:
Java
private static void printQueryInfo(McfData mcfData) { Query query = mcfData.getQuery(); System.out.println("Query Info:"); 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 of Analytics metrics System.out.println("Dimensions: " + query.getDimensions()); // List of Analytics dimensions System.out.println("Sort: " + query.getSort()); // List of sorte metrics or dimensions 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()); }
Methods other than query.getMetrics()
,
query.getDimensions()
, and query.getSort()
return a String
. For example, query.getStartDate()
returns the start date (a String
) of the report.
Pagination information
Any Multi-Channel Funnels Reporting API request might match hundreds of thousands of rows of Multi-Channel Funnels data. The Multi-Channel Funnels Reporting API will return only a subset, referred to as a single page of the data, at a given time. To retrieve all pages of data, use the pagination field. The following method prints the pagination information:
Java
private static void printPaginationInfo(McfData mcfData) { System.out.println("Pagination Info:"); System.out.println("Previous Link: " + mcfData.getPreviousLink()); System.out.println("Next Link: " + mcfData.getNextLink()); System.out.println("Items Per Page: " + mcfData.getItemsPerPage()); System.out.println("Total Results: " + mcfData.getTotalResults()); }
The method call mcfData.getTotalResults()
returns the total
number of rows for the query, which can be greater than the total number
of rows returned by the query. And the method call
mcfData.getItemsPerPage()
returns the maximum number of rows
the query response can contain.
The method call mcfData.getPreviousLink()
returns the link to the
previous page and mcfData.getNextLink()
returns the
link to the next page.
Totals for all results
To get the total values for the requested metrics over all the results,
not just the results returned in the query response, call the
getTotalsForAllResults()
method on the query response,
a McfData
object. Use the total values to calculate the
averages.
Java
private static void printTotalsForAllResults(McfData mcfData) { System.out.println("Metric totals over all results:"); Map<String, String> totalsMap = mcfData.getTotalsForAllResults(); for (Map.Entry<String, String> entry : totalsMap.entrySet()) { System.out.println(entry.getKey() + " : " + entry.getValue()); } }
Working Sample
Java
Google API Java client library Multi-Channel Funnels Reporting API Sample