Multi-Channel Funnels Reporting API - Reference Guide

This document provides the complete reference for both query and response for the Multi-Channel Funnels Reporting API.

Introduction
Request
1. Query Parameter Summary
2. Query Parameter Details

Response
1. Response Format
2. Response Fields

Error Codes
Sampling
Handling Large Data Results

Introduction

The Multi-Channel Funnels Reporting API enables you to request Google Analytics Multi-Channel Funnels report data. Every report consists of statistics derived from the data that the tracking code sends back to Analytics, organized as dimensions and metrics. By choosing your own combinations of dimensions and metrics, you can use the Reporting API to create customized reports tailored to your own specifications.

The API contains a single method that requests report data: report.get. With this method, you provide the table ID that corresponds to the view (profile) for which you want to retrieve data. In addition, you specify the following:

A combination of dimensions and metrics.
A date range.
A set of option parameters that control what data is returned

The API makes the report.get method available at a REST endpoint: https://www.googleapis.com/analytics/v3/data/mcf. The following section shows a sample request and describes each of the parameters.

Request

The API provides a single method to request data:

analytics.data.mcf.get()

The API also can be queried as a REST endpoint:

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/mcf
  ?ids=ga:12345
  &metrics=mcf:totalConversions,mcf:totalConversionValue
  &start-date=2011-10-01
  &end-date=2011-10-31

Each URL query parameter specifies an API query parameter that must be URL encoded.

All Requests to the Multi-Channel Funnels Reporting API must be authorized, preferably through OAuth 2.0.

Query Parameters Summary

The following table summarizes the all the query parameters accepted by the Multi-Channel Funnels Reporting API. Click each parameter name for a detailed description.

Name	Value	Required	Summary
`ids`	`string`	yes	The unique table ID of the form ga:XXXX, where XXXX is the Analytics view (profile) ID for which the query will retrieve the data.
`start-date`	`string`	yes	Start date for fetching Analytics data. Requests can specify a start date formatted as `YYYY-MM-DD`, or as a relative date (e.g., `today`, `yesterday`, or `NdaysAgo` where `N` is a positive integer).
`end-date`	`string`	yes	End date for fetching Analytics data. Request can specify an end date formatted as `YYYY-MM-DD`, or as a relative date (e.g., `today`, `yesterday`, or `NdaysAgo` where `N` is a positive integer).
`metrics`	`string`	yes	A list of comma-separated metrics, such as `mcf:totalConversions,mcf:totalConversionValue`. A valid query must specify at least one metric.
`dimensions`	`string`	no	A list of comma-separated dimensions for your Multi-Channel Funnels report, such as `mcf:source,mcf:keyword`.
`sort`	`string`	no	A list of comma-separated dimensions and metrics indicating the sorting order and sorting direction for the returned data.
`filters`	`string`	no	Dimension or metric filters that restrict the data returned for your request.
`samplingLevel`	`string`	no	The desired sampling level. Allowed Values: `DEFAULT` — Returns response with a sample size that balances speed and accuracy. `FASTER` — Returns a fast response with a smaller sample size. `HIGHER_PRECISION` — Returns a more accurate response using a large sample size, but this may result in the response being slower.
`start-index`	`integer`	no	The first row of data to retrieve, starting at 1. Use this parameter as a pagination mechanism along with the `max-results` parameter.
`max-results`	`integer`	no	The maximum number of rows to include in the response.

Query Parameter Details

ids

ids=ga:12345

Required.

The unique ID used to retrieve the Multi-Channel Funnels data. This ID is the concatenation of the namespace ga: with the view (profile) ID of the report. You can retrieve the view (profile) ID for your report by using the analytics.management.profiles.list method, which provides the id in the View (Profile) resource in the Google Analytics Management API.

start-date

start-date=2011-10-01

Required.

All Multi-Channel Funnels data requests must specify a date range. If you do not include start-date and end-date parameters in the request, the server returns an error. Date values can be for a specific date by using the pattern YYYY-MM-DD or relative by using today, yesterday, or the NdaysAgo pattern. Values must match [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).

The earliest valid start-date is 2011-01-01. There is no upper limit restriction for a start-date.

Relative dates are always relative to the current date at the time of the query and are based on the timezone of the view (profile) specified in the query.

Example date range for the last 7 days (starting yesterday) using relative dates:

  &start-date=7daysAgo
  &end-date=yesterday

end-date

end-date=2011-10-31

Required.

The earliest valid end-date is 2005-01-01. There is no upper limit restriction for an end-date.

Relative dates are always relative to the current date at the time of the query and are based on the timezone of the view (profile) specified in the query.

Example date range for the last 10 days (starting today) using relative dates:

  &start-date=9daysAgo
  &end-date=today

dimensions

dimensions=mcf:source,mcf:keyword

Optional.

The dimensions parameter defines the primary data keys for your Multi-Channel Funnels report, such as mcf:source or mcf:medium. Use dimensions to segment your conversion metrics. For example, while you can ask for the total number of conversions to your site, it might be more interesting to ask for the number of conversions segmented by medium. In this case, you'll see the number of conversions from organic, referral, email, 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.

Unavailable Values

When the value of the dimension cannot be determined, Analytics uses the special string (not set).

metrics

metrics=mcf:totalConversions,mcf:totalConversionValue

Required.

The aggregated statistics for user activity to your site, such as total conversion count or total conversion value. If a query has no dimensions parameter, the returned metrics provide aggregate values for the requested date range, such as overall total conversion value. However, when dimensions are requested, values are segmented by dimension value. For example, mcf:totalConversions requested with mcf:source returns the total conversions per source.

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.

sort

sort=mcf:source,mcf:medium

Optional.

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 conversion sources, and through which mediums?" you can make a query with the the following parameter. It sorts first by mcf:source and then by mcf:medium, both in ascending order:

sort=mcf:source,mcf:medium

To answer the related question "What are my top conversion mediums, and from which sources?", you can make a query with the the following parameter. It sorts first by mcf:medium and then by mcf:source, both in ascending order:

sort=mcf:medium,mcf:source

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

filters=mcf:medium%3D%3Dreferral

Optional.

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 mcf:totalConversions and mcf:source for view (profile) 12134, where the mcf:medium dimension is the string referral:

https://www.googleapis.com/analytics/v3/data/mcf
?ids=mcf:12134
&dimensions=mcf:source
&metrics=mcf:totalConversions
&filters=mcf:medium%3D%3Dreferral
&start-date=2011-10-01
&end-date=2011-10-31

Read the Core Reporting API Reference for details.

samplingLevel

samplingLevel=DEFAULT

Optional.

Use this parameter to set the sampling level (i.e. the number of visits used to calculate the result) for a reporting query. The allowed values are consistent with the web interface and include:

DEFAULT — Returns response with a sample size that balances speed and accuracy.
FASTER — Returns a fast response with a smaller sample size.
HIGHER_PRECISION — Returns a more accurate response using a large sample size, but this may result in the response being slower.

If not supplied, the DEFAULT sampling level will be used.

See the Sampling section for details on how to calculate the percentage of visits that were used for a query.

max-results

max-results=100

Optional.

Maximum number of rows to include in this response. You can use this in combination with start-index to retrieve a subset of elements, or use it alone to restrict the number of returned elements, starting with the first. If max-results is not supplied, the query returns the default maximum of 1000 rows.

The Multi-Channel Funnels Reporting API returns a maximum of 10,000 rows per request, no matter how many you ask for. It can also return fewer rows than requested, if there aren't as many dimension segments as you expect. For instance, there are fewer than 300 possible values for mcf:medium, so when segmenting only by medium, you can't get more than 300 rows, even if you set max-results to a higher value.

Response

If successful, this request returns a response body with the JSON structure defined below.

Note: the term "results" refers to the entire set of rows that match the query, while "response" refers to the set of rows returned on the current page of results. They can be different if the total number results is greater than the page size for the current response, as explained in itemsPerPage.

Response Format

JSON

{
  "kind": "analytics#mcfData",
  "id": string,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "sort": [
      string
    ],
    "filters": string,
    "samplingLevel": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "selfLink": string,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "containsSampledData": boolean,
  "sampleSize": string,
  "sampleSpace": string,
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
  "rows": [
    [
      McfData.Rows
    ]
  ],
}

Response Fields

The properties of the response body structure are defined as follows:

Property Name	Value	Description
`kind`	`string`	Resource type. Value is "analytics#mcfData".
`id`	`string`	An ID for this data response.
`query`	`object`	This object contains all the values passed as parameters to the query. The meaning of each field is explained in the description of its corresponding query parameter.
`query.start-date`	`string`	Start date.
`query.end-date`	`string`	End date.
`query.ids`	`string`	Unique table ID.
`query.dimensions[]`	`list`	List of analytics dimensions.
`query.metrics[]`	`list`	List of analytics metrics.
`query.sort[]`	`list`	List of metrics or dimensions on which the data is sorted.
`query.filters`	`string`	Comma-separated list of metric or dimension filters.
`query.samplingLevel`	`string`	`Requested sampling level.`
`query.start-index`	`integer`	The starting index of rows. Default value is 1.
`query.max-results`	`integer`	Maximum results per page.
`startIndex`	`integer`	The starting index of rows specified by the `start-index` query parameter. Default value is 1.
`itemsPerPage`	`integer`	The maximum number of rows the response can contain, regardless of the actual number of rows returned. If the `max-results` query parameter is specified, the value of `itemsPerPage` is the smaller of `max-results` or 10,000. The default value of `itemsPerPage` is 1000.
`totalResults`	`integer`	The total number of rows in the query result, regardless of the number of rows returned in the response. For queries that result in a large number of rows, `totalResults` can be greater than `itemsPerPage`. See Paging for more explanation of `totalResults` and `itemsPerPage` for large queries.
`selfLink`	`string`	Link to this page of results for this data query.
`previousLink`	`string`	Link to previous page of results for this data query.
`nextLink`	`string`	Link to next page of results for this data query.
`profileInfo`	`object`	Information about the view (profile) for which the data was requested. View (Profile) data is available through the Google Analytics Management API.
`profileInfo.profileId`	`string`	View (Profile) ID, such as `1174`.
`profileInfo.accountId`	`string`	Account ID to which this view (profile) belongs, such as `30481`.
`profileInfo.webPropertyId`	`string`	Web Property ID to which this view (profile) belongs, such as `UA-30481-1`.
`profileInfo.internalWebPropertyId`	`string`	Internal ID for the web property to which this view (profile) belongs, such as `UA-30481-1`.
`profileInfo.profileName`	`string`	Name of the view (profile).
`profileInfo.tableId`	`string`	Table ID for view (profile), consisting of "ga:" followed by the view (profile) ID.
`containsSampledData`	`boolean`	True if the response contains sampled data.
`sampleSize`	`string`	The number of samples used to calculate the sampled data.
`sampleSpace`	`string`	The total sampling space size. This indicates the total available sample space size from which the samples were selected.
`columnHeaders[]`	`list`	Column headers that list dimension names followed by the metric names. The order of dimensions and metrics is same as those specified in the request through the `metrics` and `dimensions` parameters. The number of headers is the number of dimensions + the number of metrics.
`columnHeaders[].name`	`string`	Name of the dimension or metric.
`columnHeaders[].columnType`	`string`	Column type. Either "DIMENSION" or "METRIC".
`columnHeaders[].dataType`	`string`	Data type. Dimension column headers have only `"STRING"` or `"MCF_SEQUENCE"` as data type. Metric column headers have data types for metric values such as `"INTEGER"`, `"DOUBLE"`, `"CURRENCY"` etc.
`totalsForAllResults`	`object`	Total values for the requested metrics as key-value pairs of metric names and values. The order of the metric totals is same as the metric order specified in the request.
`rows[]`	`list`	Report data rows, where each row contains a list of `Mcf.Rows`objects. This inner list represents dimension values followed by the metric values in the same order as specified in the request. Each row has a list of N fields, where N = the number of dimensions + the number of metrics. An `Mcf.Rows` object wraps another object that can be of either `primitiveValue` or `conversionPathValue` type. Dimension values can be of either type while all metric values are of `primitiveValue` type. A `primitiveValue` is simply a string wrapped in an object. For example: { "primitiveValue": "2183" } A `conversionPathValue` is an object wrapped around an array of objects, where each object contains a `nodeValue` string, and an optional `interactionType` string. For example: { "conversionPathValue": [ { "interactionType" : "CLICK", "nodeValue" : "google" }, { "interactionType" : "CLICK", "nodeValue" : "google" } ] }

Error Codes

The Multi-Channel Funnels Reporting API returns a 200 HTTP status code if a request is successful. If there an error occurs during processing of a query, the API returns an error code and description. Each application that uses the analytics API needs to implement proper error handling logic. For details on the error codes and how to handle them, read the Error Responses reference guide.

Try It!

You can try out queries to the Multi-Channel Funnels Reporting API.

To make a request on live data and see the response in JSON format, try the analytics.data.mcf.get method in the Google APIs Explorer.

Sampling

Google Analytics calculates certain combinations of dimensions and metrics on the fly. To return the data in a reasonable time, Google Analytics may only process a sample of the data.

You can specify the sampling level to use for a request by setting the samplingLevel parameter.

If a MCF Reporting API response contains sampled data, then the containsSampledData response field will be true. In addition, 2 properties will provide information about the sampling level for the query: sampleSize and sampleSpace. With these 2 values you can calculate the percentage of visits that were used for the query. For example, if sampleSize is 201,000 and sampleSpace is 220,000 then the report is based on (201,000 / 220,000) * 100 = 91.36% of visits.

See Sampling for a general description of sampling and how it is used in Google Analytics.

Handling Large Data Results

If you expect your query to return a large result set, use the guidelines below to help you optimize your API query, avoid errors, and minimize quota overruns. Note that we set a performance baseline by allowing a maximum of 7 dimensions and 10 metrics in any one API request. Although some queries that specify large numbers of metrics and dimensions may take longer to process than others, limiting the number of requested metrics might not be enough to improve query performance. Instead, you can use the following techniques for the best performance results.

Reducing Dimensions per Query

The API allows specifying up to 7 dimensions in any one request. Many times, Google Analytics must calculate the results of these complex queries on the fly. This can be especially time consuming if the number of resulting rows is high. For example, querying for keywords, by city by hour may match millions of rows of data. You can improve performance by reducing the number of rows Google Analytics needs to process by limiting the number of dimensions in your query.

Splitting the Query by Date Range

Instead of paging through the date-keyed results of one long date range, consider forming separate queries for one week — or even one day — at a time. Of course, for a large data set, even a request for a single day's data might return more than max-results, in which case paging cannot be avoided. But in any case, if the number of matching rows for your query is higher than max-results, breaking apart the date range may decrease the total time to retrieve the results. This approach can improve performance in both single-threaded and parallel queries.

Paging

Paging through results can be a useful way to break large results sets into manageable chunks. The totalResults field tells how many matching rows exist, and itemsPerPage gives the maximum number of rows that can be returned in the result. If there is a high ratio of totalResults to itemsPerPage, then the individual queries might be taking longer than necessary. If you need only a limited number of rows, such as for display purposes, you may find it convenient to set an explicit limit on response size through the max-results parameter. However, if your application needs to process a large set of results in its entirety, then requesting the maximum allowed rows may be more efficient.

Using gzip

An easy and convenient way to reduce the bandwidth needed for each request is to enable gzip compression. Although this requires additional CPU time to uncompress the results, the tradeoff with network costs usually makes it very worthwhile. In order to receive a gzip-encoded response you must do two things: Set an Accept-Encoding header, and modify your user agent to contain the string gzip. Here is an example of properly formed HTTP headers for enabling gzip compression:

Accept-Encoding: gzip
User-Agent: my program (gzip)

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.

Last updated October 15, 2013.

Google Analytics

Multi-Channel Funnels Reporting API - Reference Guide

Contents

Introduction

Request

Query Parameters Summary

Query Parameter Details

ids

start-date

end-date

dimensions

Unavailable Values

metrics

sort

filters

samplingLevel

max-results

Response

Response Format

Response Fields

Error Codes

Try It!

Sampling

Handling Large Data Results

Reducing Dimensions per Query

Splitting the Query by Date Range

Paging

Using gzip

Authentication required

Signing you in...