Введение в Google Analytics Reporting API с использованием Python

Получи нашу книгу «Контент-маркетинг в социальных сетях: Как засесть в голову подписчиков и влюбить их в свой бренд».

Подпишись на рассылку и получи книгу в подарок!

Введите e-mail

Я подтверждаю свою дееспособность и даю согласие на обработку своих персональных данных в соответствии с соглашением

Подписаться

Сегодня говорим о структуре запросов в Reporting API, что означают основные поля, и как создать их под задачи бизнеса. Также вам пригодятся: документация Гугл, понимание языка программирования Python. Сначала об основах, а потом начнем писать код.

Как выглядит запрос

На картинках ниже — все возможные поля, которые вы можете заполнить и отправить:

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

Каждое поле состоит из названия и типа допустимого значения. Например:

• "viewId": string
  • "viewId" — название поля, в данном случае — идентификатор представления.
  • string — строковое значение.
• “pageSize”: number
  • “pageSize” — название поле, ответственного за число строк на странице.
  • тип number — число. Если вы укажите 1 — это верно, а «один» — будет ошибкой.

Некоторые поля требуют отдельное руководство для объяснения (сегментация, фильтрация), другие понятны из названия (“viewId”).

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

Первый и второй пункты — обязательны при построении, остальные — нет.

1. viewId — идентификатор представления

Первый этап в начале работы — выбрать идентификатор представления. Где найти:

1. В адресе GA после «р».
2. Через панель администратора в настройках представления.

Уникальный ID используется для извлечения данных из правильного представления.

2. dateRanges — диапазон

Еще одно важное поле, с которым вы будете работать очень часто. Все запросы должны содержать временной диапазон, иначе сервер вернет ошибку. Здесь вы указываете, за какой промежуток времени хотите получить свои данные из Google Analytics.

Передать можно максимум два диапазона.

Установите начальную и конечную даты с помощью двух шаблонов:

• фиксированного — YYYY-MM-DD;
• относительного — сегодня, вчера.

Например:

• start-date=2019-05-05
• end-date=14daysAgo

Помните, что относительные даты всегда относятся к текущей и основаны на часовом поясе представления.

Еще одна важная деталь — вместо ввода строки или числа система предлагает объект, в который можно ввести несколько сведений.

3. samplingLevel — размер выборки

Выборка — основная причина, почему данные в интерфейсе и в API расходятся. Можно уменьшить ее влияние, указав размер.

Google Analytics выполняет анализ только на некоторой части данных, а не полностью, если у вас очень много сеансов — 500 000+ для бесплатных пользователей.

Такая настройка гарантирует возвращение результата в разумные сроки. Иногда это может быть лишним или сбивать с толку начинающих пользователей.

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

samplingLevel=DEFAULT

Всего три возможных варианта:

В зависимости от значения, система будет регулировать соотношение скорости и достоверности данных.

Для быстрого результата выберите SMALL. Разница составляет всего несколько секунд на один запрос, но время суммируется в сложных случаях.

4. metrics — показатели

Это актуальные значения вашего сайта, например, количество сеансов, среднее время или показатель отказов домашней страницы.

В API все метрики должны быть в формате:

{

“expression”: string,

“alias”: string (optional),

“formattingType”: enum(MetricType),

}

Пройдемся по каждой строке.

“expression” — основное поле, в котором вы определяете, какой именно показатель нужен в отчете. Можно использовать стандартные или создавать пользовательские метрики.

Например, вы работаете с количеством сеансов на одного пользователя. Используйте готовое “ga:sessionsPerUser” или пропишите свое выражение “ga:sessions/ga:users”. Начинающим пока что будет достаточно предлагаемой системной базы.

“alias” — псевдоним или альтернативное название. Поле необязательное, даже в пользовательских выражениях.

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

“formattingType” — необязательное поле, предлагающее несколько вариантов заполнения: INTEGER, FLOAT, CURRENCY, PERCENT, TIME. Их описание можно посмотреть в таблице.

Чаще всего придется менять настройки по умолчанию, чтобы лучше сформировать отчет. Система аналитика плохо предсказывает формат нового показателя.

Например, GA по умолчанию возвращает показатель отказов в виде числа с плавающей запятой — с несколькими цифрами после запятой: 0,5432. Но удобнее будет представить его в процентах (формат PERCENT) — 54,32%.

5. dimensions — параметры

Используя только показатели, вы получите сводку данных за фиксированный диапазон времени. Например, общее количество сеансов за последний месяц. Этого мало для глубокого анализа. Нужны параметры — правила, в которых можно преобразовать изменения в читаемое число.

Они разбивают информацию по общим критериям. Например, с помощью ga: userType или ga: browser.

Структура параметра:

Первое поле "name" не вызывает затруднений.

"histogramBuckets" поможет сгруппировать параметры (количество сеансов, их продолжительность) в отдельные сегменты, для построения графиков и анализа.

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

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

Каждый дополнительный параметр приведет к значительному увеличению количества строк в ответах.

Ограничения на один запрос

1. Максимум 10 показателей и параметров.
2. Хотя бы один показатель должен быть включен.
3. Максимум 7 параметров.
4. Не все показатели и параметры могут быть объединены в одной области видимости.

6. orderBys — сортировка

Пример:

Здесь действуют два простых правила:

• Порядок сортировки указывается слева направо в порядке перечисления показателей и параметров.
• Направление сортировки по умолчанию возрастает. Порядок можно изменить на нисходящий, используя минус в запрашиваемом поле. Например: sort=-ga:country.

Допустим, вы создаете панель мониторинга в Google Таблицах или Google Data Studio. И ваш первый шаг — поместить данные в Таблицы. Информацию удобно размещать в определенном порядке, чтобы упростить дальнейшую настройку.

7. segments — сегменты

Для составления запросов потребуется базовое понимание сегментации. Подробная информация с поясняющими примерами:

• Официальное справочное руководство.
• Разрешенные показатели и параметры.

Новичкам в GA пока нужно просто помнить о сегментах. Это сложная тема.

8. filtersExpression — фильтры

Фильтры — еще одна тема для отдельного руководства. В таблицах приведены операторы и их значение.

Пример:

Из таблиц мы уже знаем, что %3D%3 это двойной знак равенства (==). А на читаемом языке это будет filters=ga:medium==referral.

Фильтр проверит все наборы на равенство «источник=реферальный», и если условие выполняется, строка данных сохраняется. Иначе — удаляется.

Подробнее о каналах.

Как и с сегментами, фильтры в начале изучения GA пока не требуются.

Подробные руководства:

• Синтаксис фильтров с примерами.

9. pageToken — токен

Поле обязательно, только если вам нужно получить более 10.000 строк.

Чтобы избежать ситуаций, когда начинающий пользователь запрашивает 100.000, и сервер падает, Google Analytics по умолчанию ограничивает их до 10 000.

Поэтому для получения 100.000 строк отправьте 10 отдельных запросов подряд. Поле pageToken — это токен. Так Гугл понимает, что отправляемый запрос — продолжение предыдущего незавершенного.

10. pageSize — число строк на страницу

Еще одно обязательное поле, когда в ответе должно быть более 10.000 строк.

pageSize определяет, сколько строк будет содержать каждый запрос. По умолчанию это число равно 1.000 и может изменяться от 0 до 10.000.

Обычно 1000 строк достаточно.

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

11. includeEmptyRows — включение нулевых строк в ответ

Значение по умолчанию — ложь.

Возьмем для примера ежедневное количество сеансов. Вы точно знаете, что в некоторые дни — это 0.

По умолчанию Google пропускает эти дни и возвращает данные только с сессиями.

Установите значение true (правда), чтобы избежать пробелов в анализе.

12. hideTotals — показ суммарных показателей

Необязательное поле со значением умолчанию false.

Google Analytics возвращает дополнительную информацию. Установите true, чтобы отключить вывод в отчет суммарных показателей.

Обычно это поле не меняют при малом числе запросов, где экономить время не надо.

13. hideValueRanges — показ максимальных и минимальных значений

hideValueRanges относится к дополнительным полям, как и hideTotals. По умолчанию определяется false, но если в приоритете скорость при больших объемах — установите true.

Инструменты

Писать вручную код не нужно: используйте Account Explorer и Query Explorer. Они предлагают простую форму для заполнения и сами генерируют конечные инструкции.

Попробовать запросы можно еще в официальной документации.

Несколько источников по Python

Если вы не знакомы с Питоном или пришли с другого языка программирования, посмотрите эти ссылки:

• Stepic:
  • Программирование на Python.
  • Python: основы и применение.
  • Адаптивный тренажер Python.
• Курс на Интуит.
• Курс на Hexlet.
• Лекции на Лекториум.

Они помогут ответить на базовые вопросы при изучении Питона.

Настройка проекта на Python

Создайте виртуальную среду gaapi на Python 3.5.2. Версия 3.x лучше обрабатывает специальные символы в строках, чем 2.7.

Теперь создадим структуру проекта. Какие файлы нам понадобятся:

• require.txt — список используемых пакетов.
• credentials.py — учетные данные для соединения.
• connect.py — код подключения к API Google Analytics.
• functions.py — общая функциональность.
• run.py — файл для запуска и получения данных отчета.

Теперь установим соединение с API.

Этап 1. Подключение к Google Oauth

Помните о ключевых моментах:

• Получение доступа к данным неизвестного пользователя.
• Создание веб-приложения.

Чтобы настроить проект, выполните следующие действия:

1. Войдите в учетную запись разработчика.
2. Нажмите «Создать проект».
3. Введите название, измените идентификатор по необходимости — отредактировать позже уже нельзя.
4. Нажмите «Создать». Google настроит проект, это недолго. По завершению вы получите уведомление.
5. Перейдите в «Окно запроса доступа OAuth» в левом меню. Это запрос аутентификации для пользователя, когда он будет использовать ваше приложение.
6. Выберите в адресе электронной почты свой аккаунт разработчика и введите название продукта. Все остальные поля необязательны.
7. Нажмите «Сохранить».
8. Выберите в левом меню «Библиотека», чтобы добавить API в ваш проект для доступа к службам Google.
9. Выберите или найдите нужный API.
10. Нажмите «Включить».
11. Кликните в левом меню «Учетные данные». Здесь вы создадите токены аутентификации для приложения.
12. Нажмите на стрелочку и «Создать новый идентификатор клиента».
13. Выберите «Веб-приложение».
14. В разделе «Разрешенные источники JavaScript» введите адрес хоста приложения. Это может быть только один URL.
15. В поле «Разрешенные URI перенаправления» введите URL-адрес, по которому вы хотите выполнить аутентификацию.
16. Нажмите «Создать».

Вы создали учетные данные приложения для доступа к проекту API.

С помощью идентификатора клиента и секрета клиента приложение может подключиться к проекту Google. На данный момент это не нужно, т.к. нет пользователей, которые разрешили приложению доступ к их данным.

Когда проект будет готов в консоли разработчика Google, можно установить соединение API. Начните с добавления учетных переменных из вашего проекта в файл credentials.py.

Первые три значения скопируйте. Остальные вы сгенерируете в следующих шагах.

1.1. Настройка кода

После ввода учетных данных напишите следующий код в файл connect.py:

Добавим пакеты для новых библиотек. Выполните следующую инструкцию в командной строке (не забудьте изменить gaapi на имя вашей виртуальной среды и установить все три пакета):

Добавьте строку для каждого пакета в ваш файл needs.txt. PyCharm предложит пользователям установить недоступные библиотеки (особенно удобно, когда вы делитесь своим проектом).

Теперь вставьте этот код:

Это настройка для проверки различных состояний вашего соединения, чтобы сгладить процесс подключения.

1.2. Запускаем скрипт трижды

1. При первом запуске будет напечатан URL. Откройте его, разрешите приложению использовать вашу учетную запись Google и скопируйте значение за параметром &code. Это ваш код доступа. Установите его как переменную access_code скрипта. Он позволяет подключиться к Google API один раз.
2. Во втором запуске мы используем код доступа для печати токена доступа и обновления токена. Установите выведенные значения в качестве переменных access_token и refresh_token. Оба позволяют вам подключиться к Google API в дальнейшем.
3. Третий и последующие запуски используют токен доступа и токен обновления для установления соединения с Google API.

После третьего запуска вы увидите печатную строку, похожую на эту:

Теперь вы подключены к API Google Analytics. Удалите служебную строку печати в конце вашего кода.

Этап 2. Первый отчет

Оставьте credentials.py и connect.py как есть и перейдите к файлу run.py. Первое — испортируйте файл connect.py:

После этого добавьте две функции из краткого руководства Reporting API v4: get_report (дает данные) и print_response (печатает данные в консоли).

Не забудьте добавить свой идентификатор представления.

Теперь выведите первые данные. Добавьте эту строку в конец run.py:

Она напечатает данные, получаемые с помощью get_report, и подключится через сервис, который вы создали в файле подключения. Запустите run.py.

Прежде чем продолжим, нужно привести код в порядок. Переместите функцию print_response в файл functions.py. Чтобы использовать ее, импортируйте print_response из функций в файле run.py. Также удалите все комментарии.

Файл run.py теперь выглядит аккуратнее:

Упростите get_reports. Переместите в functions.py. Сейчас вы можете передавать только переменные connect.service, start_date и end_date. А вам нужны еще идентификатор представления, показатели, параметры и многое другое. Для этого сначала добавьте новые значения в функцию и измените текущие следующим образом:

Вы можете использовать этот шаг, чтобы добавить поддержку других значений, например, segments.

Не забудьте импортировать функцию в файл run.py:

Последний шаг — упростите вызов функции в файле run.py:

Импортируйте connect в functions.py и удалите импорт из run.py. После этого добавьте новую функцию:

Теперь в run.py нужно импортировать и вызвать return_ga_data:

Этап 3. Экспорт данных

Вы можете экспортировать информацию в несколько стандартных форматов, например, Excel.

Сначала создайте новую функцию в functions.py. Установите пакет xlsxwriter (его не нужно импортировать) и после этого добавьте функцию:

Теперь можно экспортировать в Excel.

Подводим итоги

Шаги, приведенные выше — только основа для начинающих путь в GA API. С помощью Питона вы сможете гибко использовать функции разработчиков без классических ограничений пользовательского интерфейса.