API Google Analytics 4 (Data API)

Хотите иметь возможность гибко работать с данными, собранными в Google Analytics 4, вне интерфейса GA4? Тогда самое время познакомиться с Google Analytics Data API (GA4).

Введение

Основная работа интернет-маркетолога или владельца сайта, который установил счетчик веб-аналитики к себе на сайт, приходится на интерфейсную часть Google Analytics 4. Отчеты, таблицы, графики, параметры, показатели, фильтры, сегменты, аудитории - все это нам может предоставить система аналитики. Благодаря собранной информации и наглядным визуализациям, вы можете с помощью отчетов и Исследований GA4 провести ряд анализов, которые позволят вам впоследствии повысить эффективность маркетинговых каналов, увеличить показатель конверсии, числа заявок, клиентов и прибыли.

Это может быть:

• анализ посещаемости сайта. Хотим знать все об аудитории, которая посещает наш сайт: максимальный охват, активных пользователей, их пол, возраст, интересы, с какого браузера или устройства был осуществлен переход на сайт, из какого местоположения и т.д., а также их динамику и тенденции к ухудшению или улучшению ситуации в целом;
• анализ e-commerce (электронная торговля). К этой категории относятся различные виды электронной коммерции (b2b, b2c, c2c и т.д.) и их данные: популярные товары, количество транзакций, доход, средний чек, цикл продаж;
• анализ юзабилити и поведение пользователей на страницах сайта. Собираем данные о том, как посетитель взаимодействует с формами (кнопками) на сайте, по каким элементам на странице чаще или реже всего кликает, по каким страницам переходит, какие совершает действия;
• сравнение с конкурентами и общими трендами в мире (бенчмаркинг). За основу берется товар или услуга конкурента «лучшего» качества на рынке (эталон) с целью улучшения собственного продукта и тех аспектов, по которым проводится сравнение.

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

Но это далеко не все, что заложено в Google Analytics. Компания Google, наряду с новым функционалом GA4, где отдельное место отводится интеграции с облачным хранилищем Google BigQuery и работе с данными с помощью SQL-запросов, предоставляет всем пользователям Google Analytics программные методы для доступа к данным отчетов. Другими словами, не используя интерфейс GA4, вы можете:

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

Никогда не встречались с таким функционалом? Точно встречались, только не задумывались об этом. Любые сторонние сервисы и SaaS-платформы, которые запрашивают авторизацию ваших аккаунтов, работают с данными именно посредством запросов через API. Яркий пример - сервисы сквозной аналитики. Вы привязываете свой аккаунт того или иного сервиса (Google Analytics, Google Ads, Яндекс.Директа, Яндекс.Метрики и т.д.) внутри личного кабинета такой платформы и даете разрешение на просмотр или редактирование вашего аккаунта. Как только вы это сделаете, данный сервис сможет выполнять с вашим счетчиком аналитики все вышеперечисленные действия (если речь идет именно о Google Analytics). Для других инструментов - свой набор разрешений.

Разрешение дается через специальное приложение, которое имеет свой набор доступов. Например, для работы с API Яндекс.Директа и выгрузки данных, непосредственно, с серверов Яндекса, необходимо сначала создать приложение с определенным уровнем прав, а затем получить токен доступ (OAuth-токен) для своего рекламного кабинета. И только после этого вы сможете работать со статистикой ваших рекламных кампаний программно.

Вот так выглядит пример отчета в Yandex DataLens со статистикой рекламных кампаний Яндекс.Директа, выгруженной через API в базу данных ClickHouse с использованием встроенного коннектора, так как по умолчанию в DataLens нет готового решения для Яндекс.Директа:

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

Если вы не планируете использовать сторонние решения, а хотите построить сквозную аналитику, объединить данные из разных систем в единое целое в какой-нибудь базе данных (в облаке, на собственном сервере), чтобы в дальнейшем отследить путь клиента от клика по рекламе до его повторных продаж, а затем создать BI-решение и набор отчетов, вам тоже придеться столкнуться с выгрузкой данных посредством API.

Из всего того, что я написал выше, осталась нераскрыта только аббревиатура API.

Что такое API?

API (Application Programming Interface) - это программный интерфейс, позволяющий приложениям возможность взаимодействовать друг с другом. Под «приложением» понимается любое программное обеспечение (ПО) или программа, выполняющая определенные функции. Например, одно приложение может запросить данные у другого приложения и получить их в ответ. API содержит наборы методов, классов, библиотек и функций (готовых конструкций кода), позволяющих разработчику строить сложную функциональность на разных языках программирования (например, JavaScript или Python) с меньшими усилиями.

Ваш браузер - это тоже программа (приложение), поэтому в ней присутствует множество API. Их можно разделить на две категории:

1. API браузера. Они встроены в веб-браузер и способны использовать данные браузера и компьютерной среды для осуществления более сложных действий с этими данными. К примеру, API геолокации (Geolocation API) предоставляет простые в использовании конструкции JavaScript для работы с данными местоположения, так что вы сможете, допустим, отметить свое расположение на карте Google Maps или Яндекс.Картах. На самом деле, в браузере выполняется сложный низкоуровневый код (например, на C++) для подключения к устройству GPS (или любому другому устройству геолокации), получения данных и передачи их браузеру для обработки вашей программой. Однако эти детали и процессы скрыты благодаря API;
2.  Сторонние API. Они не встроены в браузер по умолчанию. Такие API и информацию о них обычно необходимо искать в документации самого сервиса или в интернете. Например, API Яндекс.Метрики позволяет управлять счетчиками, их настройками, правами доступа, не используя веб-интерфейс, а также получать информацию о посещаемости сайта, формировать отчеты, выполнять сегментацию и фильтрацию статистики.

Наиболее простой пример, который может проиллюстрировать работу API - это авторизация на сайте с помощью стороннего приложения. Например, на сайте OWOX BI авторизация происходит посредством входа через учетную запись Google:

Пользователь вводит свои данные от Gmail, разрешает доступ приложению к своим данным (например, имени, адресу электронной почты, языковым настройкам, фото профиля и т.д.), а затем авторизуется. После этого он заходит на сайт и без каких-либо проблем начинает использовать сервис. Казалось бы, как сайт OWOX и учетная запись человека от Gmail (совершенно другого сервиса) связаны между собой? Вот именно благодаря API и "общению" двух программ между собой посредством определенных команд существенно упрощается процесс регистрации/авторизации для пользователя. А поскольку в Gmail вся информация о человеке уже заполнена и известна, ему не нужно при регистрации на OWOX вручную вводить в поля свое имя, адрес электронной почты, пароль и т.д. Все это происходит автоматически (за несколько кликов) и подставляется в его профиль на OWOX из доступных данных Gmail.

У многих компаний и инструментов есть собственные API. Есть API YouTube, Twitter API, API Facebook *, API Яндекс.Директа, API Метрики, ВКонтакте API, API myTarget и т.д. У Google Analytics 4 есть Data API.

* Деятельность американской компании Meta (бывшая Facebook) запрещена в России, организация признана экстремистской

API Google Analytics 4 (GA4)

Работа с API любого сервиса ложится на человека, знающего один или несколько языков программирования (например, Java, Python, R, PHP и другие) и любящего работать с технической документацией. Такими навыками, как правило, обладает разработчик/программист. Однако в последнее время аналогичные задачи решает и аналитик данных, и инженер данных, и даже интернет-маркетолог, поскольку при прочих равных при трудоустройстве на работу приоритет отдают тому специалисту, кто владеет JavaScript, Python/R и умеет работать с API рекламных и аналитических инструментов.

Кроме того, с учетом последних трендов аналитики, одним из которых является умение прогнозировать будущие показатели бизнеса на основе исторических данных компании, некоторые задачи из этой области так же связаны с программными методами и API. Поэтому работа с Google Analytics Data API не является какой-то призрачной или не востребованной (не нужной) для интернет-маркетолога. Напротив, из года в год такие умения будут все больше и больше ценятся на рынке труда. И мне бы очень хотелось, чтобы такими навыками обладали и вы. Тем более, что существуют клиентские библиотеки на Java, Python, Node.js и других языках, упрощающие реализацию и работу с API Google Analytics.

Примечание: в моем блоге есть материал по прогнозированию SEO-трафика Google Analytics 4 с помощью Python и Prophet. Если вам интересна данная тема, то можете ознакомиться с публикацией здесь.

Если вы раньше работали с API Google Analytics, то знаете, что Google обычно разделяет API в соответствии с их функциональным значением. Есть API управления и API отчетов. В отличие от старой версии Google Analytics (Universal Analytics, GA3), где можно было использовать такие API, как: Google Analytics Reporting API v4, Google Analytics Reporting API v3, Management API, Multi-Channel Funnels, Real-time Reporting, Metadata API, User Deletion API, в новом Google Analytics 4 используется два API:

1. Data API
2. Admin API

Google Analytics Data API предоставляет вам программный доступ к данным отчетов Google Analytics 4 (GA4). Он помогает понять, как люди используют ваше веб-приложение, приложение для iOS или Android.

Ссылка на официальную документацию Data API:

https://developers.google.com/analytics/devguides/reporting/data/v1

Data API можно использовать только для доступа к ресурсам Google Analytics 4, и он несовместим с Universal Analytics. Именно с Data API вы будете работать 99% времени.

Google Analytics Admin API предоставляет программный доступ к данным конфигурации/настройкам Google Analytics 4 (GA4), которые вы видите в интерфейсе вашего ресурса.

В их числе:

• управление новыми потоками данных (Web, Android, iOS);
• предоставление новых учетных записей и свойств;
• создание фрагментов глобального тега сайта;
• управление связями между Firebase, Google Ads и GA4;
• управление разрешениями пользователей во всех иерархиях учетных записей;
• управление специальными параметрами и показателями;
• управление событиями-конверсиями;
• управление настройками Google Signals для ресурса;
• управление настройками хранения данных в GA4;
• и т.д.

Ссылка на официальную документацию Admin API:

https://developers.google.com/analytics/devguides/config/admin/v1

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

Однако после появления встроенный интеграции между Google Analytics 4 и Google BigQuery, где данные о всех ваших событиях хранятся в облачном хранилище и к которым вы всегда можете обратиться посредством SQL-запросов, у вас может возникнуть вопрос - зачем тогда использовать API Google Analytics 4 (Data API)?

На это есть несколько причин:

• работа с API - бесплатная, в отличие от Google BigQuery, где ценообразование зависит от хранения и анализа запроса. И если у вас большой проект, много данных, и к статистике в течение дня обращается несколько человек из вашей компании, вы можете быстро преодолеть лимиты и начать платить большие суммы за использование BigQuery. В моем блоге есть статья Дорогостоящая ошибка при подключении GA4 - BigQuery к Looker Studio (Data Studio). Обязательно прочтите ее.
• если вы желаете выгружать данные Google Analytics с помощью программирования на Python/R или другом языке и не хотите изучать SQL, то использование API - верное решение;
• BigQuery - это инструмент, предназначенный для "сырых", необработанных, и главное - больших данных! Если у вас веб-сайт или мобильное приложение с небольшим количеством трафика, то и использование облачных решений не даст вам никаких преимуществ по сравнению с API;
• работая с API, вам не нужно переживать за выборку данных (ее нет, но есть система квот и категорий).

Чтобы получать последние новости и быть в курсе всех изменений API Google Analytics, подпишитесь на группу Google Analytics API Notify.

Начало работы

Самый простой способ начать работу с API Google Analytics 4 - это загрузить одну из клиентских библиотек (Java, PHP, Python, Node.js, Ruby, Go, .NET). Во всех последующих материалах своего блога я буду использовать Python, поскольку он сейчас является наиболее популярным языком программирования у интернет-маркетологов и веб-аналитиков.

Примечание: если вы хотите научиться работать с API Google Analytics 4 на языке R и знаете английский язык, то можете использовать материалы Марка Эдмондсона (Mark Edmondson). Для русскоязычной аудитории очень хорошо освещает R для интернет-маркетинга Алексей Селезнёв.

Для получения фактических данных Google Analytics 4 в Data API существуют различные методы:

1. runReport
2. batchRunReports
3. runPivotReport
4. batchRunPivotReports
5. getMetadata
6. runRealtimeReport
7. runFunnelReport

Первые два метода являются самыми простыми и включают в себя получение только одного отчета с данными о ваших событиях (runReport) или нескольких отчетов одного типа с помощью одного вызова API (batchRunReports).

Следующие два используются для получения более сложных отчетов о ваших событиях GA4, так называемых сводных отчетов. runPivotReport - для одного сводного отчета; batchRunPivotReports - пакетная версия метода, позволяющая создавать несколько сводных отчетов одного типа с помощью одного вызова API.

Как и в предыдущей версии Universal Analytics (Real Time Reporting API), вы также можете получать данные в реальном времени в Google Analytics 4. Метод runRealtimeReport возвращает настраиваемый отчет с данными о событиях в реальном времени для вашего ресурса за последние 30 минут на вашем веб-сайте или в мобильном приложении (до 60 минут для Google Analytics 360). События появляются в отчетах в реальном времени через несколько секунд после их отправки в GA4. Обратите внимание, что пакетной версии этого вызова API нет.

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

Примечание: список параметров и показателей, поддерживаемых в Data API, также доступен в официальной документации Google.

В Data API есть еще один метод - runFunnelReport. Он возвращает данные о последовательности выполненных вашими пользователями событий. С помощью этого метода можно визуализировать шаги пользователей на пути к выполнению определенного действия на сайте / в приложении и быстро узнать, насколько успешно они проходят каждый из этапов, а в случае обнаружения "узкого места", устранить неисправности или скорректировать работу проекта. В интерфейсе Google Analytics 4 есть такое Исследование - оно называется Исследование воронки.

Квоты и категории

Перед тем, как создать свой первый запрос, необходимо остановиться на еще одной теме - квоты (quotas). Когда вы выполняете тот или иной запрос к серверам Google, чтобы получить статистику по вашему счетчику GA4, система проверяет, не были ли исчерпаны квоты. Если какая-либо квота была исчерпана, запрос завершается с соответствующим сообщением об ошибке. Каждый запрос в Data API проверяет несколько наборов квот.

Data API имеет три категории запросов:

1. Core (runReport, runPivotReport, batchRunReports, batchRunPivotReports, runAccessReport, getMetadata, checkCompatibility)
2. Realtime (runRealtimeReport)
3. Funnel (runFunnelReport)

Запросы API к методам Core взимают квоты Core. Запросы API к методам реального времени требуют квот реального времени, и так далее. В официальной документации разработчиков приведена таблица, в которой обозначены лимиты на те или иные операции для каждой категории запросов:

Standard Property Limit - квоты для стандартных ресурсов Google Analytics 4, Analytics 360 Property Limit - для ресурсов Google Analytics 360. Единица измерения - токены. Токены рассчитываются с каждым запросом в зависимости от сложности запроса. Большинство запросов будет взимать 10 или меньше токенов. Когда запрос потребляет большое количество токенов квоты, как правило, это связано со следующими факторами:

• большое количество строк;
• большое количество столбцов;
• сложные критерии фильтрации;
• длинный диапазон дат.

С каждым запросом API вы можете указать "returnPropertyQuota": true в тексте запроса, чтобы он возвращал текущий статус токенов квоты ресурса. Этот статус содержит как сумму, потребленную этим запросом, так и оставшуюся сумму для каждой группы квот.

Почему квоты важны? Все дело в том, что такие ограничения доставляют пользователям (нам) существенные неудобства, даже в работе с продуктами внутри экосистемы Google. Например, с 7 ноября 2022 г. на отчеты Looker Studio (Google Data Studio), использующие встроенный коннетор Google Analytics 4, стали распространяться те самые квоты Google Analytics Data API (GA4).

Наверняка у вас есть отчет в Looker Studio и при работе с ним вы могли наблюдать ошибку, связанную с квотами (Quota Error):

Или такую:

Сами того не ведая, вы как и прежде работали с отчетом, анализировали данные, меняли диапазоны дат, использовали разные типы визуализации данных. И в один "прекрасный день" ваш отчет стал отображать ошибку. Токены расходуются каждый раз, когда вы меняете фильтры, редактируете диапазоны дат или даже при обновлении данных на панели инструментов Looker Studio. Стандартным пользователям GA4 выделяется 1250 часовых токенов и 25 000 ежедневных токенов. Визуализация, использующая совмещенные данные, потребует вдвое больше токенов, чем визуализация с одним источником подключения.

Исходя из таблицы квот, пользователям выделяется 10 вызовов API одновременно. Это означает, что на странице вашего отчета Looker Studio с 10 графиками вы сразу же уткнётесь в потолок квот для одновременных запросов. Точно так же будет происходить, если два пользователя, работающих одновременно с одним и тем же отчетом, получают доступ к дашборду, на котором 5 графиков. И такая ошибка не случайна - не может же Google делать все свои продукты бесплатными и без каких-либо ограничений. Если вы желаете увеличить порог и анализировать данные в полном объеме, Google предлагает вам перейти на Google Analytics 4 (в Google Analytics 360), подписка на который начинается от 50 000$ в год.

Безусловно, такая цена на продукт непозволительна для малых предприятий и небольших проектов. А раз такие компании не могут позволить себе подписку, то они и не смогут получить доступ ко всем своим данным в Looker Studio. Но есть определенные решения, которые позволяют обойти данные ограничения. Подробнее об этом разберем в отдельной статье.

Как вы понимаете, квоты Data API - это не просто лимиты и токены, которые прописаны в таблице где-то далеко в справке Google. Они - реальность и могут влиять на вашу работу, даже в других продуктах Google. А для крупных компаний - это критическая проблема, требующая немедленного реагирования.

Уверен, что если вы только начинаете изучать API Google Analytics 4 по моим материалам (или статьям других авторов), то работа с API у вас будет строиться "от простого к сложному", на бытовом, но практическом уровне. А тех лимитов, что предоставляет Google для Data API, для вашего проекта вам хватит с лихвой.

Первый запуск API

После того, как вы теоретически познакомились с возможностями API Google Analytics 4 (Data API), пришло время выполнить свой первый запрос.