Что такое Google Ads API и зачем он нужен?
Google Ads API предоставляет программный доступ к вашей учетной записи Google Ads. Он позволяет разработчикам напрямую взаимодействовать с платформой, автоматизируя сложные задачи и интегрируя данные Google Ads с другими системами.
В отличие от веб-интерфейса, API предназначен для масштабного управления и глубокого анализа. Он используется для создания собственных инструментов отчетности, автоматизации управления кампаниями, интеграции с CRM, биддинг-платформами и другими аналитическими или операционными системами.
Преимущества использования API вместо интерфейса Google Ads
Использование Google Ads API открывает возможности, недоступные через стандартный веб-интерфейс:
Автоматизация: Выполнение рутинных задач (создание/обновление кампаний, получение отчетов) по расписанию без ручного вмешательства.
Масштабирование: Управление большим количеством аккаунтов или объектов (кампании, объявления, ключевые слова) значительно эффективнее, чем через интерфейс.
Интеграция: Соединение данных Google Ads с данными из других источников (например, CRM, веб-аналитика) для создания комплексных отчетов и принятия решений.
Гибкость: Получение специфических срезов данных или метрик, которые могут быть недоступны или сложно извлекаемы через стандартные отчеты интерфейса.
Собственные инструменты: Создание кастомных инструментов для анализа, мониторинга и управления, адаптированных под уникальные бизнес-процессы.
Основные понятия и термины (ресурсы, отчеты, запросы)
Для работы с API необходимо усвоить несколько ключевых концепций:
Ресурсы (Resources): Основные сущности в Google Ads API, представляющие объекты учетной записи (например, Campaign, AdGroup, Keyword, Ad). Каждый ресурс имеет уникальное имя и набор полей (атрибутов).
Поля ресурсов (Resource Fields): Атрибуты ресурса, содержащие конкретные данные (например, campaign.id, campaign.name, ad_group.status).
Метрики (Metrics): Количественные показатели эффективности (например, metrics.clicks, metrics.impressions, metrics.cost_micros). Они всегда связаны с определенным временным интервалом и доступны при запросе вместе с ресурсами.
Сегменты (Segments): Поля, позволяющие разбить данные по определенным атрибутам (например, segments.date, segments.device). Использование сегментов приводит к получению отдельной строки для каждого сегмента в результатах запроса.
Google Ads Query Language (GAQL): Мощный язык запросов, используемый для извлечения данных из API. Он синтаксически похож на SQL и позволяет выбирать поля ресурсов, метрики и сегменты, применять фильтры (WHERE), сортировку (ORDER BY) и ограничения (LIMIT).
Подготовка к работе с Google Ads API
Получение учетных данных (Google Cloud Project, API Key, OAuth 2.0)
Доступ к Google Ads API требует прохождения нескольких шагов авторизации и аутентификации:
Google Cloud Project: Создайте проект в Google Cloud Platform (GCP). Это базовая единица для управления ресурсами и API Google.
Включение Google Ads API: Внутри вашего GCP проекта найдите и включите Google Ads API в разделе APIs & Services -> Library.
Получение учетных данных (Credentials): Перейдите в раздел APIs & Services -> Credentials.
Developer Token: Этот токен нужен для идентификации вашего разработчика и связан с вашим Аккаунтом Центра Клиентов (MCC). Он выдается после одобрения заявки на доступ к API (изначально тестовый, затем стандартный). Указывается в каждом запросе.
OAuth 2.0 Client ID & Secret: Эти учетные данные используются для аутентификации конечного пользователя (владельца аккаунта Google Ads), к данным которого вы хотите получить доступ. Вам потребуется настроить OAuth consent screen и создать OAuth client ID типа Desktop app или Web application в зависимости от вашего приложения. Для большинства оффлайн-сценариев получения данных предпочтителен Desktop app или Web application с получением refresh_token.
Процесс OAuth 2.0 включает получение authorization_code через браузер пользователя, который затем обменивается на access_token (кратковременный) и refresh_token (долговременный). Для автоматического получения данных вам нужен refresh_token, который позволит получать новые access_token без повторной авторизации пользователя.
Установка и настройка клиентской библиотеки (Python, Java, PHP, etc.)
Google предоставляет клиентские библиотеки для популярных языков программирования, которые значительно упрощают взаимодействие с API. Рекомендуется использовать именно их.
Например, для Python установка выполняется через pip:
pip install google-adsПосле установки необходимо настроить библиотеку, предоставив ей учетные данные. Обычно это делается через конфигурационный файл google-ads.yaml или переменные окружения. Файл google-ads.yaml должен содержать информацию о вашем developer_token, client_id, client_secret, refresh_token и login_customer_id (MCC ID, если вы работаете с несколькими аккаунтами).
Пример структуры google-ads.yaml:
general:
developer_token: YOUR_DEVELOPER_TOKEN
login_customer_id: YOUR_MCC_ID # Укажите MCC ID, если работаете с несколькими аккаунтами
oauth2:
client_id: YOUR_CLIENT_ID
client_secret: YOUR_CLIENT_SECRET
refresh_token: YOUR_REFRESH_TOKENПоместите этот файл в домашнюю директорию пользователя или укажите путь к нему в коде или переменной окружения.
Настройка среды разработки
Убедитесь, что в вашей среде установлены необходимые зависимости (например, Python и pip). Создайте виртуальное окружение для проекта, чтобы избежать конфликтов зависимостей.
python -m venv venv
source venv/bin/activate # или `venv\Scripts\activate` в Windows
pip install google-ads pandas # pandas пригодится для обработки данныхРазместите файл google-ads.yaml в доступном месте, либо используйте переменные окружения для передачи учетных данных.
Подключение к аккаунту Google Ads (получение refresh token)
Для получения данных из конкретного аккаунта Google Ads вам нужен customer_id этого аккаунта и авторизация для доступа к нему через OAuth 2.0. Процесс получения refresh_token включает следующие шаги:
Используйте client_id и client_secret для генерации URL авторизации.
Перейдите по этому URL в браузере, войдите в аккаунт Google, который имеет доступ к целевому аккаунту Google Ads, и разрешите вашему приложению доступ.
После успешной авторизации браузер будет перенаправлен на redirect_uri с параметром code (authorization_code).
Используйте client_id, client_secret и code для запроса к серверу Google OAuth 2.0 endpoint, чтобы обменять code на access_token и refresh_token.
Клиентские библиотеки часто предоставляют утилиты для упрощения этого процесса. Полученный refresh_token следует сохранить (например, в google-ads.yaml), так как он требуется для всех последующих авторизованных запросов.
Для запросов к аккаунту, не являющемуся MCC (если ваш login_customer_id — это ID MCC), вам нужно будет указать ID клиентского аккаунта в заголовке customer_id каждого запроса или в конфигурации клиента.
Получение данных с помощью Google Ads API
Основные типы запросов: GAQL (Google Ads Query Language)
Основной способ извлечения данных из Google Ads API — это использование языка GAQL. GAQL позволяет запрашивать ресурсы, их поля, метрики и сегменты, а также применять условия фильтрации, сортировки и ограничения выборки.
Структура GAQL запроса похожа на SQL SELECT:
SELECT
field_resource.field_name,
metrics.metric_name,
segments.segment_name
FROM
resource_name
WHERE
condition_on_field
ORDER BY
field_to_sort
LIMIT
number_of_resultsSELECT: Определяет, какие поля ресурсов, метрики и сегменты вы хотите получить.
FROM: Указывает основной ресурс, который вы запрашиваете (например, campaign, ad_group, keyword).
WHERE: Применяет условия фильтрации к полям или метрикам.
ORDER BY: Определяет порядок сортировки результатов.
LIMIT: Ограничивает количество возвращаемых строк.
Примеры запросов GAQL для получения различных данных
Получение списка кампаний и их статусов:
SELECT
campaign.id,
campaign.name,
campaign.status
FROM
campaign
ORDER BY
campaign.nameПолучение данных по кликам, показам и расходам на уровне групп объявлений за определенный период:
SELECT
ad_group.id,
ad_group.name,
metrics.clicks,
metrics.impressions,
metrics.cost_micros
FROM
ad_group
WHERE
segments.date BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'
ORDER BY
metrics.clicks DESCПримечание: cost_micros возвращается в микро-единицах (миллионные доли валюты), необходимо делить на 1,000,000 для получения фактической суммы..
Получение данных по ключевым словам с разбивкой по устройствам:
SELECT
keyword_view.resource_name,
ad_group_criterion.keyword.text,
segments.device,
metrics.clicks,
metrics.ctr
FROM
keyword_view
WHERE
segments.date = 'YYYY-MM-DD'
AND ad_group_criterion.status = 'ENABLED'Фильтрация и сортировка данных в GAQL запросах
Фильтрация (WHERE): Используйте оператор WHERE для применения условий. Доступны стандартные операторы сравнения (=, !=, >, <, >=, <=), логические операторы (AND, OR), а также специфические для GAQL операторы (LIKE для частичного совпадения строк, IN для списка значений, BETWEEN для диапазонов дат).
Пример фильтрации по статусу и имени кампании:
WHERE campaign.status = 'ENABLED' AND campaign.name LIKE '%Brand%'Пример фильтрации по метрике (показы > 1000):
WHERE metrics.impressions > 1000Сортировка (ORDER BY): Указывайте поля, по которым нужно отсортировать результаты, и направление сортировки (ASC или DESC). Можно сортировать по нескольким полям.
Пример сортировки по имени кампании (прямой порядок), затем по кликам (обратный порядок):
ORDER BY campaign.name ASC, metrics.clicks DESCПолучение данных отчетов (performance reports)
GAQL запросы по сути являются запросами к отчетным данным. Когда вы включаете метрики (metrics.*) и/или сегменты (segments.*) в свой запрос GAQL, API автоматически собирает и агрегирует данные, формируя производительный отчет. Ресурсы, которые часто используются для получения отчетов, включают campaign, ad_group, ad_group_criterion (для ключевых слов), ad.
Важно понимать, что метрики и сегменты доступны не для всех ресурсов. Документация API четко указывает, какие метрики и сегменты совместимы с каким ресурсом FROM.
Обработка и анализ полученных данных
Форматы данных, возвращаемых API (JSON, протокол буферы)
Google Ads API использует протокол буферы (Protocol Buffers) для сериализации данных в процессе передачи, что обеспечивает эффективность и скорость. Однако клиентские библиотеки, как правило, автоматически десериализуют эти данные в структуры, более удобные для работы в вашем языке программирования. Для Python клиентская библиотека преобразует данные в объекты, к полям которых можно обращаться как к атрибутам.
Хотя API напрямую не возвращает чистый JSON в ответ на GAQL запросы (он использует gRPC с Protobuf), клиентские библиотеки позволяют легко преобразовать полученные объекты в формат, который можно далее сериализовать в JSON или экспортировать.
Парсинг и обработка данных в вашем приложении
После выполнения GAQL запроса клиентская библиотека возвращает итератор или список объектов-ресурсов. Каждый такой объект содержит запрошенные поля ресурсов, метрики и сегменты.
В Python это выглядит примерно так:
# Предполагается, что `googleads_client` уже инициализирован
# и `customer_id` целевого аккаунта известен.
def get_campaign_performance(client, customer_id: str, date_range: tuple) -> list:
"""
Получает клики и расходы кампаний за указанный диапазон дат.
Args:
client: Инициализированный клиент Google Ads API.
customer_id: ID клиентского аккаунта.
date_range: Кортеж (start_date, end_date) в формате YYYY-MM-DD.
Returns:
Список словарей с данными кампаний.
"""
ga_service = client.get_service("GoogleAdsService")
query = f"""
SELECT
campaign.id,
campaign.name,
metrics.clicks,
metrics.cost_micros
FROM
campaign
WHERE
segments.date BETWEEN '{date_range[0]}' AND '{date_range[1]}'
ORDER BY
metrics.clicks DESC
"""
# Выполняем запрос
response = ga_service.search(customer_id=customer_id, query=query)
results = []
# Обрабатываем полученные строки
for row in response:
campaign = row.campaign
metrics = row.metrics
results.append({
'campaign_id': campaign.id,
'campaign_name': campaign.name,
'clicks': metrics.clicks,
'cost': metrics.cost_micros / 1_000_000 # Переводим микро-единицы в валюту
})
return results
# Пример использования (после настройки клиента)
# data = get_campaign_performance(googleads_client, 'YOUR_CUSTOMER_ID', ('2023-01-01', '2023-01-31'))
# print(data)Полученные данные удобно загружать в структуры данных, такие как списки словарей в Python, или в библиотеки для анализа данных, например, Pandas DataFrame.
Примеры анализа данных: расчет ROI, определение наиболее эффективных кампаний
Имея данные о расходах (metrics.cost_micros) и, при наличии, данные о конверсиях (metrics.conversions, metrics.conversions_value) из Google Ads, или объединяя их с данными о доходах из других источников (например, CRM), можно проводить анализ:
Расчет ROI (Return on Investment): Если у вас есть данные о доходе, принесенном кампаниями (revenue), ROI можно рассчитать как ((revenue - cost) / cost) * 100%. Для этого вам нужно будет сопоставить данные Google Ads с данными о доходе.
Расчет ROAS (Return on Ad Spend): (conversions_value / (cost_micros / 1_000_000)) * 100%. Это более прямой показатель эффективности рекламных расходов, использующий данные о ценности конверсий, если они отслеживаются.
Определение наиболее эффективных кампаний/групп объявлений/ключевых слов: Сортировка данных по ключевым метрикам (клики, конверсии, цена конверсии — CPA, ROAS) позволяет выявить объекты с наилучшей или наихудшей производительностью.
Pandas DataFrame отлично подходит для такого анализа, предоставляя мощные инструменты для фильтрации, агрегации, объединения данных и расчетов метрик.
Практические примеры и советы
Пример скрипта на Python для автоматического получения данных и сохранения в CSV
Этот скрипт демонстрирует, как получить клики, показы и расходы по кампаниям за вчерашний день и сохранить их в CSV файл.
import pandas as pd
from google.ads.googleads.client import GoogleAdsClient
from google.api_core import protobuf_helpers
from datetime import datetime, timedelta
import yaml
import os
def main():
# Путь к конфигурационному файлу (может быть переменной окружения)
# Или настройте клиент без файла, передав dict
config_file = os.path.expanduser('~/.config/google-ads/google-ads.yaml')
# Инициализация клиента Google Ads API
try:
googleads_client = GoogleAdsClient.load_from_storage(config_file)
except Exception as e:
print(f"Ошибка загрузки конфигурации: {e}")
print("Убедитесь, что файл ~/.config/google-ads/google-ads.yaml существует и корректен.")
return
# --- Параметры запроса ---
# Замените на реальный ID вашего клиентского аккаунта или MCC
customer_id = 'YOUR_CUSTOMER_ID'
# Определяем диапазон дат (вчера)
yesterday = datetime.now() - timedelta(days=1)
date_str = yesterday.strftime('%Y-%m-%d')
# Запрос GAQL для получения данных кампаний
query = f"""
SELECT
campaign.id,
campaign.name,
campaign.status,
metrics.clicks,
metrics.impressions,
metrics.cost_micros
FROM
campaign
WHERE
segments.date = '{date_str}'
ORDER BY
metrics.cost_micros DESC
"""
ga_service = googleads_client.get_service("GoogleAdsService")
print(f"Выполняем запрос GAQL для аккаунта {customer_id} за {date_str}...")
results_list = []
try:
# Выполнение запроса
response = ga_service.search(customer_id=customer_id, query=query)
# Обработка результатов и сбор данных в список словарей
for row in response:
camp = row.campaign
metrics = row.metrics
results_list.append({
'Date': date_str,
'Campaign ID': camp.id,
'Campaign Name': camp.name,
'Campaign Status': camp.status,
'Clicks': metrics.clicks,
'Impressions': metrics.impressions,
'Cost': metrics.cost_micros / 1_000_000 if metrics.cost_micros else 0.0 # Делим на 1М, обрабатываем None/0
})
print(f"Получено {len(results_list)} строк данных.")
except Exception as e:
print(f"Произошла ошибка при выполнении запроса: {e}")
return
# Проверка наличия данных и сохранение в CSV
if results_list:
df = pd.DataFrame(results_list)
# Имя файла для сохранения
output_filename = f"google_ads_campaign_performance_{date_str}.csv"
# Сохранение в CSV
try:
df.to_csv(output_filename, index=False)
print(f"Данные успешно сохранены в {output_filename}")
except Exception as e:
print(f"Ошибка при сохранении файла CSV: {e}")
else:
print("Нет данных для сохранения.")
if __name__ == '__main__':
main()Перед запуском: Убедитесь, что установлен пакет google-ads и pandas, а файл ~/.config/google-ads/google-ads.yaml настроен с вашими учетными данными и customer_id в коде заменен на фактический ID аккаунта.
Лучшие практики работы с API (ограничения запросов, обработка ошибок)
Лимиты запросов: Google Ads API имеет ограничения на количество запросов в день и на скорость запросов (рейт-лимиты). Для стандартного уровня доступа лимит составляет 15 000 запросов в день и 1000 запросов в минуту. Превышение лимитов приведет к ошибкам RESOURCE_EXHAUSTED. Планируйте свои запросы и используйте пагинацию (LIMIT, OFFSET — хотя в GAQL search пагинация автоматическая при итерации по ответу) или запрашивайте данные большими блоками по датам или аккаунтам.
Обработка ошибок: Всегда используйте блоки try...except для перехвата ошибок API. Google Ads API возвращает специфические коды ошибок и сообщения, которые помогают понять причину сбоя (например, неверный запрос GAQL, проблемы с аутентификацией, превышение лимита). Логируйте ошибки для последующего анализа.
Идемпотентность: При выполнении операций модификации данных (не получение), старайтесь делать запросы идемпотентными, чтобы повторное выполнение не привело к дублированию сущностей или некорректным изменениям.
Версионирование API: Google Ads API регулярно обновляется, появляются новые версии. Используйте актуальную версию API и клиентской библиотеки. Учитывайте, что при обновлении API могут устаревать некоторые поля или ресурсы – следите за анонсами.
Login Customer ID: При работе через MCC аккаунт, используйте login_customer_id (ID вашего MCC) в конфигурации клиента. Это позволит выполнять запросы от имени MCC. Для запросов к конкретному клиентскому аккаунту указывайте его ID (customer_id) в параметрах вызова метода API (ga_service.search(customer_id='...')).
Полезные ресурсы и документация Google Ads API
Официальная документация Google Ads API: https://developers.google.com/google-ads/api/docs/start — Ваш основной источник информации. Содержит руководства, справочники по ресурсам и полям, примеры кода.
Справочник по GAQL: https://developers.google.com/google-ads/api/docs/query/overview — Детальное описание синтаксиса и возможностей GAQL.
Инструмент Query Validator: https://developers.google.com/google-ads/api/fields/v16/query_validator — Полезен для проверки ваших GAQL запросов перед их использованием в коде.
Репозитории клиентских библиотек на GitHub: Содержат примеры кода и исходники библиотек.
Решение распространенных проблем и ошибок
AUTHENTICATION_ERROR: Проверьте правильность developer_token, client_id, client_secret и refresh_token. Убедитесь, что refresh_token не просрочен или не отозван. Проверьте, что аккаунт, связанный с refresh_token, имеет доступ к customer_id, который вы запрашиваете.
RESOURCE_EXHAUSTED: Вы превысили лимиты API. Проверьте количество запросов. Внедрите механизм задержки между запросами или пересмотрите логику получения данных для сокращения их общего числа.
Ошибки парсинга GAQL (INVALID_QUERY, BAD_REQUEST): Внимательно проверьте синтаксис вашего GAQL запроса. Убедитесь, что запрашиваемые поля, метрики и сегменты совместимы с ресурсом FROM. Используйте Query Validator.
AUTHORIZATION_ERROR: У аккаунта, от имени которого вы выполняете запрос (связанного с refresh_token), нет достаточных прав доступа к аккаунту с customer_id. Убедитесь, что пользователь имеет как минимум доступ только для чтения к целевому аккаунту Google Ads.
Пустые результаты при запросе метрик: Убедитесь, что в запросе с метриками присутствует сегмент segments.date или другой временной сегмент, и что указанный диапазон дат содержит данные. Проверьте, что фильтры (WHERE) не исключают все данные.