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

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.

Back to Top


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

Back to Top


end-date

end-date=2011-10-31
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 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

Back to Top


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

Back to Top


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.

Back to Top


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

Back to Top


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.

Back to Top


samplingLevel

samplingLevel=DEFAULT
Optional.
Use this parameter to set the sampling level (i.e. the number of sessions 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 sessions that were used for a query.

Back to Top


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.

Back to Top


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
    ]
  ],
}

Back to Top

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.
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.Rowsobjects. 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"
    }
  ]
}

Back to Top

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.

Back to Top

Try it!

Use the APIs Explorer below to call this method on live data and see the response.

Back to Top

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

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

Back to Top

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)