Multi-Channel Funnels Reporting API - Developer Guide

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:

  1. Register your application in Google API Console.
  2. Authorize access to Google Analytics data.
  3. 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:

  1. Query the Multi-Channel Funnels Reporting API.
  2. 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:

  1. Build a Multi-Channel Funnels Reporting API query object.
  2. 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