Запросить отчеты

Новый API отчетов Search Ads 360 теперь доступен. Новый API обеспечивает повышенную гибкость для создания пользовательских отчетов и интеграции данных в ваши приложения и процессы отчетности. Узнайте больше о переходе и использовании нового API отчетов Search Ads 360 .

После настройки клиентского приложения, как описано в разделе «Мое первое приложение» , вы можете использовать API Search Ads 360 для запроса и скачивания отчетов. Вы можете сделать любой из следующих типов запросов:

синхронный

Требуется всего один запрос и возвращает отчет в виде ответа в формате JSON. Синхронные запросы:

Если вы запрашиваете крупные отчеты по рекламодателям или системным аккаунтам, мы рекомендуем асинхронный подход.

Асинхронный

Требуется отправить первоначальный запрос, в котором указаны данные, которые вы хотите включить в отчет. Затем вы отправляете дополнительные запросы на опрос Search Ads 360. Когда Search Ads 360 завершает создание отчета, вы отправляете запросы на загрузку отчета в виде одного или нескольких файлов. Асинхронные запросы:

  • Может возвращать любой тип отчета
  • Разбивает очень большие отчеты на несколько файлов.
  • Форматирует отчеты как CSV или TSV.

Модель данных: строки и столбцы

Search Ads 360 упорядочивает данные в отчете по строкам и столбцам. Тип запрашиваемого отчета определяет возвращаемые строки . Например, если вы запросите отчет по ключевым словам, каждая строка будет содержать данные об одном ключевом слове. Список всех типов отчетов см. в справочнике по типам отчетов. Вы указываете, какие столбцы вы хотите видеть в отчете, называя каждый столбец в запросе отчета. Список столбцов, которые могут быть возвращены для каждого типа отчета, см. в справочнике по типам отчетов .

Поведение столбца

Поведение столбца зависит от типа данных, содержащихся в столбце (ссылка «Типы отчетов» отображает поведение каждого столбца):

  • Столбцы атрибутов . Столбец атрибутов содержит данные, которые настраивают или идентифицируют объект в кампании, например название кампании или ставку ключевого слова. API Search Ads 360 всегда возвращает текущее значение столбца атрибута независимо от даты или диапазона дат, указанных в запросе. Например, если вчера вы изменили ставку ключевого слова с 2,00 на 1,50, а затем запросили отчет по данным за прошлый месяц, отчет вернет значение 1,50 для ставки ключевого слова.

  • Метрические столбцы . Столбец показателей содержит данные об эффективности вашей кампании, например количество кликов по объявлению, количество посещений, зафиксированное тегом Floodlight, или доход. Если вы не укажете диапазон времени в один день, API вернет совокупное значение для столбцов показателей. Например, если вы запросите отчет по данным за прошлый месяц, API вернет общее количество кликов за последний месяц.

  • Сегментировать столбцы . Столбец сегмента разбивает данные на отдельные строки. Например, date — это столбец сегмента, который можно указать для многих типов отчетов. Если вы укажете столбец date в отчете по ключевым словам с диапазоном дат с 1 января 2013 г. по 07 января 2013 г., API вернет семь строк для каждого ключевого слова, каждая из которых соответствует одному дню и отображает показатели для этого дня. См. Сегментированные отчеты .

Валюты

В запросе отчета необходимо указать валюту денежных данных (как атрибутов, таких как dailyBudget , так и таких показателей, как cost ). Вы можете указать одно из следующих:

  • Валюта агентства, если область действия отчета ограничена агентством, рекламодателем или учетной записью системы.
  • Валюта рекламодателя, если область действия отчета ограничена учетной записью рекламодателя или системы.
  • Валюта системного аккаунта, если область действия отчета ограничена системным аккаунтом.
  • доллар США

Используйте свойство запроса Reports.request.statisticsCurrency , чтобы указать валюту.

В самом отчете валюта будет указана в свойстве Reports.statisticsCurrencyCode .

Часовой пояс

Показатели Search Ads 360 хранятся в датах без часовых поясов. Эти даты соответствуют часовому поясу системного аккаунта для показателей системы (таких как клики, показы и посещения) и часовому поясу сети Менеджера кампаний для показателей конверсий (таких как действия, транзакции и доход). Если все показатели в отчете относятся к одному и тому же часовому поясу, этот часовой пояс будет возвращен в запросе. В противном случае часовой пояс не будет возвращен. В ваших запросах можно установить Reports.request.verifySingleTimeZone : true , чтобы отклонить отчеты, в которых представлены показатели из более чем одного часового пояса.

Если все метрики, присутствующие в отчете, относятся к одному часовому поясу, этот часовой пояс возвращается в Reports.statisticsTimeZoneReports .