В этой статье описываются все запросы и ответы для 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 |
Нет | Уровень выборки. Допустимые значения:
|
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
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.
Формат ответа
{
"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 |
Requested sampling level. |
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 для крупных запросов рассматривается подробнее.
|
selfLink |
string |
Ссылка на эту страницу результатов запроса. |
previousLink |
string |
Ссылка на предыдущую страницу результатов запроса. |
nextLink |
string |
Ссылка на следующую страницу результатов запроса. |
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 |
Строки с данными отчета, каждая из которых содержит список объектов В объекте
{ "primitiveValue": "2183" } Объект { "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)