Справочное руководство по Multi-Channel Funnels Reporting API

В этой статье описываются все запросы и ответы для Multi-Channel Funnels Reporting API.

Введение

Multi-Channel Funnels Reporting API позволяет запрашивать из Google Analytics данные о многоканальных последовательностях. В отчет включаются статистические данные, отправленные в Google Analytics кодом отслеживания. Задавая необходимые сочетания параметров и показателей, вы можете создавать собственные отчеты на основе Reporting API.

В API представлен единый метод запроса данных: report.get. Он принимает идентификатор таблицы, указывающий на представление (профиль), из которого нужно извлечь данные. Вы также можете указать:

  • сочетание параметров и показателей;
  • диапазон дат;
  • набор необязательных параметров, определяющих возвращаемые данные.

Метод report.get предоставляется в конечной точке REST https://www.googleapis.com/analytics/v3/data/mcf. Далее в этой статье будет показан пример запроса с подробным описанием всех параметров.

Запрос

В API представлен единый метод запроса данных:

analytics.data.mcf.get()

Кроме того, запрос к API может быть выполнен из конечной точки REST:

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

Каждый параметр URL определяет параметр запроса к API, который должен иметь кодировку URL.

Все запросы к Multi-Channel Funnels Reporting API должны быть авторизованы (рекомендуется использовать протокол OAuth 2.0).

Список параметров запроса

В этой таблице представлены все параметры запроса, принимаемые Multi-Channel Funnels Reporting API. Чтобы узнать о параметре больше, нажмите на него.

Название Значение Обязательно? Описание
ids string Да Уникальный идентификатор таблицы в формате ga:XXXX, где XXXX – это идентификатор представления (профиля) Google Analytics, для которого запрос будет извлекать данные.
start-date string Да Дата начала загрузки данных Google Analytics. Может задаваться в формате ГГГГ-ММ-ДД или относительно сегодняшнего дня. Примеры: сегодня (today), вчера (yesterday) или несколько дней назад (NdaysAgo, где N – целое положительное число).
end-date string Да Дата окончания загрузки данных Google Analytics. Может задаваться в формате ГГГГ-ММ-ДД или относительно сегодняшнего дня. Примеры: сегодня (today), вчера (yesterday) или несколько дней назад (NdaysAgo, где N – целое положительное число).
metrics string Да Список разделенных запятыми показателей, например: mcf:totalConversions,mcf:totalConversionValue. Запрос должен содержать хотя бы один показатель.
dimensions string Нет Список разделенных запятыми параметров для отчета по многоканальным последовательностям, например: mcf:source,mcf:keyword.
sort string Нет Список разделенных запятыми параметров и показателей, определяющий порядок и направление сортировки возвращаемых данных.
filters string Нет Фильтры параметров и показателей, ограничивающие возвращаемые запросом данные.
samplingLevel string Нет Уровень выборки. Допустимые значения:
  • DEFAULT – оптимальное соотношение между скоростью и точностью выборки данных для запроса.
  • FASTER – быстрый ответ с меньшим размером выборки
  • HIGHER_PRECISION – точный ответ с большей выборкой и меньшей скоростью выполнения.
start-index integer Нет Первая строка извлекаемых данных (начинается с 1). Используется совместно с параметром max-results для разбиения результатов на страницы.
max-results integer Нет Максимальное количество строк, включаемое в ответ.

Описание параметров запроса

ids

ids=ga:12345
Обязательное поле.
Уникальный идентификатор, используемый для извлечения данных по многоканальным последовательностям. Состоит из названия пространства имен (ga:) и идентификатора представления (профиля) для отчета. Этот идентификатор можно получить с помощью метода analytics.management.profiles.list, который возвращает свойство id. Этот метод представлен в Google Analytics Management API.

К началу


start-date

start-date=2011-10-01
Обязательное поле.
Для каждого запроса данных по многоканальным последовательностям необходимо определить временной диапазон. Если среди параметров запроса отсутствуют start-date или end-date, сервер вернет ошибку. Даты можно задавать в формате ГГГГ-ММ-ДД, а также относительно сегодняшнего дня: сегодня (today), вчера (yesterday) и несколько дней назад (NdaysAgo) по шаблону [0-9]{4}-[0-9]{2}-[0-9]{2}|{1/}today|yesterday|[0-9]+({1/}daysAgo).
Самая ранняя допустимая дата начала (start-date) – 2011-01-01. Верхний предел для параметра start-date отсутствует.
Относительные значения задаются по времени выполнения запроса с учетом часового пояса представления (профиля), для которого задан запрос.

Например, чтобы задать семидневный период, оканчивающийся вчерашним днем, используйте следующий код:

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

К началу


end-date

end-date=2011-10-31
Обязательное поле.
Для каждого запроса данных по многоканальным последовательностям необходимо определить временной диапазон. Если среди параметров запроса отсутствуют start-date или end-date, сервер вернет ошибку. Даты можно задавать в формате ГГГГ-ММ-ДД, а также относительно сегодняшнего дня: сегодня (today), вчера (yesterday) и несколько дней назад (NdaysAgo) по шаблону [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
Самая ранняя допустимая дата окончания (end-date) – 2005-01-01. Верхний предел для параметра end-date отсутствует.
Относительные значения задаются по времени выполнения запроса с учетом часового пояса представления (профиля), для которого задан запрос.

Например, чтобы задать десятидневный период, оканчивающийся сегодняшним днем, используйте следующий код:

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

К началу


параметры

dimensions=mcf:source,mcf:keyword
Необязательное поле.

Этот параметр определяет ключи основных данных для отчета по многоканальным последовательностям, например mcf:source или mcf:medium, и позволяет сегментировать показатели конверсии. Например, общее количество конверсий для вашего сайта, как правило, лучше разбить по используемым каналам, чтобы просматривать отдельно данные по обычному поиску, переходам, электронной почте и т. д.

Обратите внимание на следующие ограничения, связанные с использованием параметра dimensions:

  • В одном запросе можно указывать не более 7 параметров.
  • Помимо параметров в запрос обязательно включать хотя бы один показатель.

Недоступные значения

Если не удается определить значение параметра, Google Analytics использует специальную строку "(not set)".

К началу


metrics

metrics=mcf:totalConversions,mcf:totalConversionValue
Обязательное поле.

Совокупные статистические показатели, описывающие активность пользователя на сайте, например общие количество или ценность конверсий. Если в запросе не указан параметр dimensions, возвращаемые показатели будут содержать общие значения, то есть ценность всех конверсий. В остальных случаях значения будут сегментированы по заданным параметрам. Так, если заданы параметры mcf:totalConversions и mcf:source, общее количество конверсий будет разбито по источникам.

При запросе показателей помните о следующем.

  • Запрос не может состоять только из параметров и должен содержать хотя бы один показатель.
  • В запросе можно указать не более 10 показателей.

К началу


sort

sort=mcf:source,mcf:medium
Необязательное поле.

Список показателей и параметров, определяющий порядок и направление сортировки возвращаемых данных.

  • Порядок сортировки определяется расположением показателей и параметров в списке (слева направо).
  • Направление сортировки по умолчанию устанавливается по возрастанию. Чтобы реализовать сортировку по убыванию, укажите в префиксе запрашиваемого поля знак минуса (-).

Сортировка результатов помогает эффективно анализировать данные. Например, чтобы определить источники конверсий с наибольшей эффективностью и используемые ими каналы, выполните запрос с приведенным ниже параметром. В этом случае будет выполнена сортировка по возрастанию сначала по параметру mcf:source, а затем – mcf:medium:

sort=mcf:source,mcf:medium

Чтобы определить наиболее эффективные каналы конверсии и их источники, выполните сортировку по возрастанию сначала по параметру mcf:medium, а затем – mcf:source:

sort=mcf:medium,mcf:source

При работе с параметром sort учитывайте следующие особенности:

  • Сортировка выполняется только по тем параметрам и показателям, которые заданы в параметрах dimensions и metrics parameters. При попытке сортировать по любому другому полю будет возвращена ошибка.
  • По умолчанию сортировка выполняется по возрастанию в алфавитном порядке согласно региональным настройкам en-US.
  • Числовые значения по умолчанию сортируются в порядке возрастания.
  • Даты по умолчанию сортируются по возрастанию.

К началу


filters

filters=mcf:medium%3D%3Dreferral
Необязательное поле.

С помощью строкового параметра filters можно ограничить возвращаемый запросом набор данных. Для этого нужно указать параметр или показатель, по которому будет выполнена фильтрация, а затем выражение фильтра. Например, в следующем коде запрашиваются те параметры mcf:totalConversions и mcf:source для представления (профиля) 12134, в которых параметр mcf:medium имеет значение 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

Подробнее...

К началу


samplingLevel

samplingLevel=DEFAULT
Необязательное поле.
Задает уровень выборки для запроса отчетов, то есть количество сеансов, на основе которых рассчитывается результат. Поддерживаются те же значения, что и в веб-интерфейсе:
  • DEFAULT – оптимальное соотношение между скоростью и точностью выборки данных для запроса.
  • FASTER – быстрый ответ с меньшим размером выборки.
  • HIGHER_PRECISION – точный ответ с большей выборкой и меньшей скоростью выполнения.
По умолчанию задается уровень выборки DEFAULT.
Подробнее о расчете доли сеансов, обрабатываемой запросом...

К началу


max-results

max-results=100
Необязательное поле.

Максимальное количество строк, включаемое в отчет. Может использоваться вместе с параметром start-index для извлечения подмножества элементов, а также отдельно, ограничивая количество возвращаемых элементов (начиная с первого). Если параметр max-results не задан, по умолчанию запрос возвращает не более 1000 строк.

Multi-Channel Funnels Reporting API, независимо от заданного ограничения, возвращает не более 10 000 строк на запрос. Если сегментов недостаточно, строк будет возвращено меньше. Например, параметр mcf:medium не может иметь более 300 значений, поэтому при большем значении max-results и сегментировании только по каналу будет в любом случае возвращено не более 300 строк.

К началу


Ответ

В случае успеха этот запрос возвращает тело ответа в формате JSON со следующей структурой.

Примечание. Под результатами понимаются все строки, соответствующие запросу. Ответ – это набор строк, возвращаемый на текущей странице результатов. Если общее число результатов превышает размер страницы, эти значения могут отличаться. Подробнее читайте в описании параметра itemsPerPage.

Формат ответа

Файл в формате 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
    ]
  ],
}

К началу

Поля ответа

Структура тела ответа имеет следующие свойства:

Название свойства Значение Описание
kind string Тип ресурса. Значение: analytics#mcfData.
id string Идентификатор ответа с данными.
query object Этот объект содержит все значения, переданные в запрос в качестве параметров. Значение каждого поля раскрывается в описании соответствующего параметра запроса.
query.start-date string Дата начала.
query.end-date string Дата окончания.
query.ids string Уникальный идентификатор таблицы.
query.dimensions[] list Список параметров Google Analytics.
query.metrics[] list Список показателей Google Analytics.
query.sort[] list Список показателей и параметров, на основе которого сортируются данные.
query.filters string Список разделенных запятыми фильтров по показателям или измерениям.
query.samplingLevel string Запрошенный уровень выборки.
query.start-index integer Начальный индекс строки. Значение по умолчанию: 1.
query.max-results integer Максимальное количество результатов на странице.
startIndex integer Начальный индекс строки для параметра start-index. Значение по умолчанию: 1.
itemsPerPage integer Максимальное количество строк, которые может содержать ответ, независимо от фактически возвращаемого количества строк. Если задан параметр max-results, значение параметра itemsPerPage должно быть меньше max-results или 10 000. Значение параметра itemsPerPage по умолчанию: 1000.
totalResults integer Общее количество строк в результатах запроса, независимо от количества строк, возвращаемых в ответе. Для запросов, содержащих большое количество строк, значение totalResults может быть больше itemsPerPage. Подробнее о параметрах totalResults и itemsPerPage для крупных запросов читайте в разделе Разбиение на страницы.
profileInfo object Сведения о представлении (профиле), для которого были запрошены данные. Эта информация предоставляется через Google Analytics Management API.
profileInfo.profileId string Идентификатор представления (профиля), например 1174.
profileInfo.accountId string Идентификатор аккаунта, которому принадлежит представление (профиль), например 30481.
profileInfo.webPropertyId string Идентификатор веб-ресурса, которому принадлежит представление (профиль), например UA-30481-1.
profileInfo.internalWebPropertyId string Внутренний идентификатор веб-ресурса, которому принадлежит представление (профиль), например UA-30481-1.
profileInfo.profileName string Название представления (профиля).
profileInfo.tableId string Идентификатор таблицы представления (профиля), состоящий из префикса "ga:" и идентификатора самого представления (профиля).
containsSampledData boolean Имеет значение true, если запрос содержит выборку данных.
sampleSize string Количество образцов, используемое для выборки.
sampleSpace string Общий размер выборочного пространства, из которого отбираются образцы.
columnHeaders[] list Заголовки столбцов с названиями параметров и показателей в том порядке, в котором они определены с помощью параметров запроса metrics и dimensions. Количество заголовков соответствует общему количеству параметров и показателей.
columnHeaders[].name string Название параметра или показателя.
columnHeaders[].columnType string Тип столбца. Допустимые значения: DIMENSION или METRIC.
columnHeaders[].dataType string Тип данных. Заголовки столбцов параметров могут иметь тип STRING или MCF_SEQUENCE. Заголовки столбцов показателей имеют тип показателя (INTEGER, DOUBLE, CURRENCY и т. д.).
totalsForAllResults object Итоговые значения запрошенных показателей в виде пар, состоящих из ключа (название показателя) и значения. Порядок итоговых значений соответствует порядку показателей, заданному в запросе.
rows[] list

Строки с данными отчета, каждая из которых содержит список объектов Mcf.Rows. Порядок параметров и показателей соответствует заданному в запросе. Количество полей в каждой строке соответствует общему количеству параметров и показателей.

В объекте Mcf.Rows содержится объект типа primitiveValue или conversionPathValue. Параметры могут иметь значения любого из этих типов, а показатели – только типа primitiveValue.

primitiveValue представляет собой обычный объект, содержащий строковое значение. Пример:


{
  "primitiveValue": "2183"
}

Объект conversionPathValue включает массив объектов, каждый из которых содержит строку nodeValue, а также необязательный строковый параметр interactionType. Пример:


{
  "conversionPathValue": [
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    },
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    }
  ]
}

К началу

Коды ошибок

Если запрос успешен, Multi-Channel Funnels Reporting API возвращает код статуса HTTP 200, а если возникает ошибка – ее код и описание. В каждом приложении, работающем с Google Analytics API, должны быть реализованы функции обработки ошибок. Подробнее...

К началу

Попробуйте!

Ознакомьтесь с различными примерами запросов к Multi-Channel Funnels Reporting API.

  • Чтобы запросить реальные данные и просмотреть ответ в формате JSON, попробуйте метод analytics.data.mcf.get в Google API Explorer.

К началу

Выборка

Некоторые комбинации параметров и показателей вычисляются в Google Analytics в момент запроса. Иногда, чтобы не выйти за временные рамки ответа, Google Analytics обрабатывает лишь определенную выборку данных.

Уровень выборки можно задать с помощью параметра samplingLevel.

В ответе MCF Reporting API, содержащем выборку, поле containsSampledData имеет значение true. Уровень выборки задается с помощью свойств sampleSize и sampleSpace, на основе которых можно рассчитать долю сеансов, которая использовалась в запросе. Например, при значениях sampleSize=201,000 и sampleSpace=220,000 отчет будет построен на основе (201000 / 220000) * 100 = 91,36% сеансов.

Подробнее о выборке...

К началу

Обработка результатов с большим объемом данных

Из этого раздела вы узнаете, как избежать ошибок и превышения квот, а также оптимизировать запросы к API, которые могут возвращать большой объем данных. Чтобы обеспечить приемлемую эффективность, в одном запросе допускается использовать не более 7 параметров и 10 показателей, однако зачастую этого оказывается недостаточно. Вместо этого для повышения эффективности результатов можно использовать указанные ниже способы.

Уменьшение количества параметров в запросе

В одном запросе к API можно задавать до 7 параметров. При большом количестве результатов его выполнение может занимать длительное время. Например, при запросе ключевых слов по городу с разбивкой по часам может возвращаться несколько миллионов строк. Чтобы повысить эффективность, можно уменьшить их количество, убрав некоторые параметры из запроса.

Разделение запроса по диапазону дат

Если запрос охватывает большой диапазон дат, результаты будут разбиты по страницам. Чтобы этого избежать, можно создать отдельные запросы для каждой недели и даже для каждого дня. Конечно, и в таком случае набор данных может оказаться слишком большим. Если количество результатов, возвращенных запросом, превысит max-results, все равно потребуется постраничное разбиение. Тем не менее получение результатов займет гораздо меньше времени. Такой подход позволяет заметно повысить эффективность как при отдельном, так и при параллельном выполнении запросов.

Разбиение на страницы

Просмотр результатов по страницам может быть полезен для разбиения больших наборов данных на удобные части. В поле totalResults указывается общее количество подходящих строк, а параметр itemsPerPage ограничивает их количество в результатах запроса. Если соотношение между totalResults и itemsPerPage достаточно велико, отдельные запросы могут выполняться слишком долго. В таком случае можно явно ограничить размер ответа с помощью параметра max-results. Тем не менее, если требуется обрабатывать весь возвращаемый объем данных, зачастую эффективнее будет запрашивать максимально допустимое количество строк.

Использование GZIP

Сжатие GZIP позволяет легко сократить требования к пропускной способности при выполнении запросов. Извлечение результатов из архива оказывает дополнительную нагрузку на процессор, однако экономия сетевых ресурсов того стоит. Чтобы получить ответ в архиве GZIP, необходимо, во-первых, задать заголовок Accept-Encoding, а во-вторых – добавить в агент пользователя строку gzip. Вот пример правильного оформления заголовков HTTP, которое обеспечивает сжатие GZIP:

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

К началу