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 the Multi-Channel Funnels Reporting API and the data it provides.

Back to Top

Before You Begin

This guide demonstrates how to access the Multi-Channel Funnels Reporting API using the Java programming language.

• Read the Reference Guide to access the API without a client library

Each client library provides a single analytics service object to access all Multi-Channel Funnels Reporting API data. To create the service object you generally have to go through the following steps:

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

Analytics analytics = // Read Hello Analytics Tutorial for details.

Once you create an analytics service object, you are ready to make requests to the Multi-Channel Funnels Reporting API.

Back to Top

Overview

An application that uses the Multi-Channel Funnels Reporting API will generally follow two steps:

• Query the Multi-Channel Funnels Reporting API
• Work with the API results

Let's look at both steps.

Back to Top

Query the Multi-Channel Funnels Reporting API

Build a Multi-Channel Funnels Reporting API query

The analytics service object contains a method to build a Multi-Channel Funnels Reporting API query.

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.

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);

A complete listing of all the query parameters and what they do can be found in the Multi-Channel Funnels Reporting API reference guide. Also the dimension and metric parameters allow you to specify what data to retrieve from Multi-Channel Funnels. A complete list can be found on the dimensions and metrics reference page.

Making a Multi-Channel Funnels Reporting API data request

Once you have a query defined, you call it's execute method to send the query to Multi-Channel Funnels servers.

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();
}

HttpResponse response = apiQuery.executeUnparsed();

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.

Back to Top

Work with the API Results

If the Multi-Channel Funnels Reporting API query was successful, the API returns with the reporting data as well as other related information about the data.

Multi-Channel Funnels 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.

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 contains a single cell information which is either a primitive value of String type, or a conversion path value 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.

The following examples print both the headers and rows of the table.

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 format a string.

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

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:

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 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.

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

Each Multi-Channel Funnels Reporting API response contains an object that contains all the query parameter values used to create the response.

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
  System.out.println("Dimensions: " + query.getDimensions()); // List
  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());
}

The metrics and sort parameters are returned as values in a list, while the other parameters are returned as strings.

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 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.

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 totalResults field represents the total number of rows of data that your query matched in Multi-Channel Funnels. 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 Multi-Channel Funnels Reporting API.

Totals for all results

As mentioned in the pagination information section above, a query to the Multi-Channel Funnels Reporting API can match many rows of data in Multi-Channel Funnels, 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.

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());
  }
}

Back to Top

Working Samples

To see the full working samples check out the Multi-Channel Funnels Reporting API Sample in each client library's sample directory.

Back to Top

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.