Method: customers.generateReachForecast

Создает прогноз охвата для заданного таргетинга/ассортимента продуктов.

Список выброшенных ошибок: AuthenticationError AuthorizationError FieldError HeaderError InternalError QuotaError RangeError ReachPlanError RequestError

HTTP-запрос

POST https://googleads.googleapis.com/v15/customers/{customerId}:generateReachForecast

URL-адрес использует синтаксис транскодирования gRPC .

Параметры пути

Параметры
customerId

string

Необходимый. Идентификатор клиента.

Тело запроса

Тело запроса содержит данные следующей структуры:

JSON-представление
{
  "campaignDuration": {
    object (CampaignDuration)
  },
  "cookieFrequencyCapSetting": {
    object (FrequencyCap)
  },
  "targeting": {
    object (Targeting)
  },
  "plannedProducts": [
    {
      object (PlannedProduct)
    }
  ],
  "forecastMetricOptions": {
    object (ForecastMetricOptions)
  },
  "currencyCode": string,
  "cookieFrequencyCap": integer,
  "minEffectiveFrequency": integer,
  "effectiveFrequencyLimit": {
    object (EffectiveFrequencyLimit)
  },
  "customerReachGroup": string
}
Поля
campaignDuration

object ( CampaignDuration )

Необходимый. Продолжительность кампании.

cookieFrequencyCapSetting

object ( FrequencyCap )

Выбранное ограничение частоты использования файлов cookie для каждого запланированного продукта. Это эквивалентно ограничению частоты показов в Google Рекламе при создании кампании. Оно представляет собой максимальное количество раз, которое реклама может быть показана одному и тому же пользователю в течение определенного интервала времени. Если не указано, применяется значение по умолчанию 0 (без ограничения).

Это поле заменяет устаревшее поле cookieFrequencyCap.

targeting

object ( Targeting )

Таргетинг будет применен ко всем продуктам, выбранным в ассортименте.

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

Подробную информацию о том, как на них влияет таргетинг, смотрите в конкретных показателях.

plannedProducts[]

object ( PlannedProduct )

Необходимый. Продукты, которые будут прогнозироваться. Максимальное количество разрешенных плановых продуктов — 15.

forecastMetricOptions

object ( ForecastMetricOptions )

Управляет метриками прогноза, возвращаемыми в ответе.

currencyCode

string

Код валюты. Трехзначный код валюты ISO 4217.

cookieFrequencyCap

integer

Выбранное ограничение частоты использования файлов cookie для каждого запланированного продукта. Это эквивалентно ограничению частоты показов, которое отображается в Google Рекламе при создании кампании. Оно представляет собой максимальное количество раз, когда реклама может быть показана одному и тому же пользователю. Если не указано, ограничение не применяется.

Это поле устарело в версии 4 и в конечном итоге будет удалено. Вместо этого используйте cookieFrequencyCapSetting.

minEffectiveFrequency

integer

Выбрана минимальная эффективная частота (количество раз, когда человек видел рекламу) для сообщаемых показателей охвата [1–10]. Это не повлияет на таргетинг, а только на отчетность. Если не указано, применяется значение по умолчанию 1.

Это поле нельзя объединить с полем effectFrequencyLimit.

effectiveFrequencyLimit

object ( EffectiveFrequencyLimit )

Наивысшее значение минимальной эффективной частоты (количество раз, когда человек видел рекламу) [1–10], которое нужно включить в Forecast.efficient_ Frequency_breakdowns. Если не указано, Forecast.efficiency_breakdowns предоставляться не будет.

Указанное здесь значение эффективной частоты также будет использоваться в качестве минимальной эффективной частоты для сообщаемых показателей охвата.

Это поле нельзя объединить с полем minEffectiveFrequency.

customerReachGroup

string

Имя планируемого клиента. Это определяемое пользователем значение.

Тело ответа

Ответное сообщение, содержащее сгенерированную кривую охвата.

В случае успеха тело ответа содержит данные следующей структуры:

JSON-представление
{
  "onTargetAudienceMetrics": {
    object (OnTargetAudienceMetrics)
  },
  "reachCurve": {
    object (ReachCurve)
  }
}
Поля
onTargetAudienceMetrics

object ( OnTargetAudienceMetrics )

Ссылка на целевую аудиторию для этой кривой.

reachCurve

object ( ReachCurve )

Сгенерированная кривая охвата для запланированного ассортимента продукции.

Области авторизации

Требуется следующая область действия OAuth:

  • https://www.googleapis.com/auth/adwords

Дополнительную информацию см. в обзоре OAuth 2.0 .

Продолжительность кампании

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

JSON-представление
{
  "dateRange": {
    object (DateRange)
  },
  "durationInDays": integer
}
Поля
dateRange

object ( DateRange )

Диапазон дат кампании. Даты указываются в формате гггг-мм-дд включительно. Дата окончания должна быть <1 года в будущем, а длина диапазона дат должна быть <= 92 дня.

Это поле нельзя объединить с полем periodInDays.

durationInDays

integer

Значение продолжительности в днях.

Это поле нельзя объединить с полем dateRange.

Частота ограничения

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

JSON-представление
{
  "impressions": integer,
  "timeUnit": enum (FrequencyCapTimeUnit)
}
Поля
impressions

integer

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

timeUnit

enum ( FrequencyCapTimeUnit )

Необходимый. Тип единицы времени.

Ограничение эффективной частоты

Эффективный предел частоты.

JSON-представление
{
  "effectiveFrequencyBreakdownLimit": integer
}
Поля
effectiveFrequencyBreakdownLimit

integer

Максимальное значение эффективной частоты, которое нужно включить в Forecast.efficient_ Frequency_breakdowns. Данное поле поддерживает частоты 1-10 включительно.

Таргетинг

Таргетинг, для которого будут сообщаться показатели трафика.

JSON-представление
{
  "plannableLocationIds": [
    string
  ],
  "ageRange": enum (ReachPlanAgeRange),
  "genders": [
    {
      object (GenderInfo)
    }
  ],
  "devices": [
    {
      object (DeviceInfo)
    }
  ],
  "network": enum (ReachPlanNetwork),
  "audienceTargeting": {
    object (AudienceTargeting)
  },
  "plannableLocationId": string
}
Поля
plannableLocationIds[]

string

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

Если указано более одного идентификатора, все идентификаторы должны иметь один и тот же parentCountryId . Планирование более чем parent_county не поддерживается. Идентификаторы планируемых местоположений и их parentCountryId можно получить из ReachPlanService.ListPlannableLocations .

Запросы должны устанавливать либо это поле, либо plannableLocationId .

ageRange

enum ( ReachPlanAgeRange )

Целевой возрастной диапазон. Неустановленное значение эквивалентно таргетингу на все возрасты.

genders[]

object ( GenderInfo )

Целевые гендеры. Неустановленное значение эквивалентно таргетингу на МУЖЧИН и ЖЕНЩИН.

devices[]

object ( DeviceInfo )

Целевые устройства. Если не указано, нацелено на все применимые устройства. Применимые устройства различаются в зависимости от продукта и региона, и их можно получить из ReachPlanService.ListPlannableProducts .

network

enum ( ReachPlanNetwork )

Целевая сеть для рекламного продукта. Если не указано, нацелены на все применимые сети. Применимые сети различаются в зависимости от продукта и региона, их можно получить из ReachPlanService.ListPlannableProducts .

audienceTargeting

object ( AudienceTargeting )

Целевая аудитория. Если не указано, не ориентировано на какую-либо конкретную аудиторию.

plannableLocationId

string

Идентификатор выбранного местоположения. Идентификаторы планируемых местоположений можно получить из ReachPlanService.ListPlannableLocations .

Запросы должны устанавливать либо это поле, либо plannableLocationIds .

Это поле устарело начиная с версии 12 и будет удалено в будущем выпуске. Вместо этого используйте plannableLocationIds .

Таргетинг на аудиторию

Таргетинг на аудиторию для прогноза охвата.

JSON-представление
{
  "userInterest": [
    {
      object (UserInterestInfo)
    }
  ]
}
Поля
userInterest[]

object ( UserInterestInfo )

Список целевых аудиторий на основе интересов пользователей.

Планируемый продукт

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

JSON-представление
{
  "advancedProductTargeting": {
    object (AdvancedProductTargeting)
  },
  "plannableProductCode": string,
  "budgetMicros": string
}
Поля
advancedProductTargeting

object ( AdvancedProductTargeting )

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

plannableProductCode

string

Необходимый. Выбранный продукт для планирования. Код, связанный с рекламным продуктом (например: Trueview, Bumper). Чтобы просмотреть доступные планируемые коды продуктов, используйте ReachPlanService.ListPlannableProducts .

budgetMicros

string ( int64 format)

Необходимый. Максимальное выделение бюджета в микронах для выбранного продукта. Значение указывается в выбранном коде валюты планирования. Например: 1 000 000$ = 1 000 000 000 000 микрон.

Расширенный таргетинг на продукт

Расширенные настройки таргетинга для товаров.

JSON-представление
{
  "surfaceTargetingSettings": {
    object (SurfaceTargeting)
  },
  "targetFrequencySettings": {
    object (TargetFrequencySettings)
  },

  // Union field advanced_targeting can be only one of the following:
  "youtubeSelectSettings": {
    object (YouTubeSelectSettings)
  }
  // End of list of possible types for union field advanced_targeting.
}
Поля
surfaceTargetingSettings

object ( SurfaceTargeting )

Настройки таргетинга на поверхность для этого продукта.

targetFrequencySettings

object ( TargetFrequencySettings )

Настройки кампании с целевой частотой. Должен быть установлен при выборе продукта TARGET_FREQUENCY.

Дополнительную информацию о кампаниях с целевой частотой см. на странице https://support.google.com/google-ads/answer/12400225 .

Поле объединения advanced_targeting . Параметры таргетинга для этого продукта. advanced_targeting может быть только одним из следующих:
youtubeSelectSettings

object ( YouTubeSelectSettings )

Настройки таргетинга YouTube Select.

Настройки целевой частоты

Настройки целевой частоты для поддерживаемого продукта.

JSON-представление
{
  "timeUnit": enum (TargetFrequencyTimeUnit),
  "targetFrequency": integer
}
Поля
timeUnit

enum ( TargetFrequencyTimeUnit )

Необходимый. Единица времени, используемая для описания временного интервала targetFrequency.

targetFrequency

integer

Необходимый. Целевая частота показов в выбранную единицу времени.

YouTubeВыберитеНастройки

Запрос настроек для избранных подборок YouTube

JSON-представление
{
  "lineupId": string
}
Поля
lineupId

string ( int64 format)

Подборка для YouTube Select Targeting.

Прогнозметрические параметры

Управляет возвращаемыми показателями прогноза.

JSON-представление
{
  "includeCoview": boolean
}
Поля
includeCoview

boolean

Указывает, включать ли показатели совместного просмотра в прогноз ответа.

OnTargetAudienceMetrics

Показатели аудитории для планируемых продуктов. Эти показатели учитывают следующие параметры таргетинга:

  • Расположение
  • Планируемыйвозрастдиапазон
  • Пол
  • AudienceTargeting (только для youtubeAudienceSize)
JSON-представление
{
  "youtubeAudienceSize": string,
  "censusAudienceSize": string
}
Поля
youtubeAudienceSize

string ( int64 format)

Размер эталонной аудитории соответствует рассматриваемому таргетингу на YouTube.

censusAudienceSize

string ( int64 format)

Размер эталонной аудитории соответствует предполагаемому таргетингу переписи населения.

кривая охвата

Кривая охвата запланированных продуктов.

JSON-представление
{
  "reachForecasts": [
    {
      object (ReachForecast)
    }
  ]
}
Поля
reachForecasts[]

object ( ReachForecast )

Все точки на кривой досягаемости.

Прогноз охвата

Точка на кривой досягаемости.

JSON-представление
{
  "costMicros": string,
  "forecast": {
    object (Forecast)
  },
  "plannedProductReachForecasts": [
    {
      object (PlannedProductReachForecast)
    }
  ]
}
Поля
costMicros

string ( int64 format)

Стоимость в микрон.

forecast

object ( Forecast )

Прогнозируемые показатели трафика для этой точки.

plannedProductReachForecasts[]

object ( PlannedProductReachForecast )

Прогнозируемые показатели распределения и трафика для каждого запланированного продукта в данной точке кривой охвата.

Прогноз

Прогнозируемые показатели трафика по планируемым продуктам и таргетингу.

JSON-представление
{
  "effectiveFrequencyBreakdowns": [
    {
      object (EffectiveFrequencyBreakdown)
    }
  ],
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string,
  "views": string
}
Поля
effectiveFrequencyBreakdowns[]

object ( EffectiveFrequencyBreakdown )

Список эффективных прогнозов частоты. Список упорядочивается, начиная с 1+ и заканчивая значением, установленным в GenerateReachForecastRequest.efficient_ Frequency_limit. Если не было установлено effectFrequencyLimit, этот список будет пустым.

onTargetReach

string ( int64 format)

Количество уникальных людей, достигших как минимум GenerateReachForecastRequest.min_efficient_ Frequency или GenerateReachForecastRequest.efficient_ Frequency_limit раз, что точно соответствует таргетингу.

Обратите внимание, что для предоставления данных необходимо охватить минимальное количество уникальных людей. Если минимальное число не достигнуто, значение onTargetReach будет округлено до 0.

totalReach

string ( int64 format)

Общее количество уникальных людей достигло как минимум GenerateReachForecastRequest.min_efficient_ Frequency или GenerateReachForecastRequest.efficient_ Frequency_limit раз. Сюда входят люди, которые могут выходить за рамки указанного таргетинга.

Обратите внимание, что для предоставления данных необходимо охватить минимальное количество уникальных людей. Если минимальное число не достигнуто, значение totalReach будет округлено до 0.

onTargetImpressions

string ( int64 format)

Количество показов объявления, точно соответствующее таргетингу.

totalImpressions

string ( int64 format)

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

viewableImpressions

string ( int64 format)

Сколько раз показы объявления считались видимыми. См. https://support.google.com/google-ads/answer/7029393 для получения дополнительной информации о том, что делает объявление видимым и как измеряется видимость.

onTargetCoviewReach

string ( int64 format)

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

totalCoviewReach

string ( int64 format)

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

onTargetCoviewImpressions

string ( int64 format)

Количество показов рекламы, точно соответствующих таргетингу, включая со-просмотрщиков.

totalCoviewImpressions

string ( int64 format)

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

views

string ( int64 format)

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

Дополнительную информацию о просмотрах см. на странице https://support.google.com/google-ads/answer/2375431 .

Разбивка по эффективной частоте

Разбивка количества уникальных людей, охваченных с заданной эффективной частотой.

JSON-представление
{
  "effectiveFrequency": integer,
  "onTargetReach": string,
  "totalReach": string,
  "effectiveCoviewReach": string,
  "onTargetEffectiveCoviewReach": string
}
Поля
effectiveFrequency

integer

Эффективная частота [1-10].

onTargetReach

string ( int64 format)

Количество уникальных людей, достигших как минимум эффективной частоты, точно соответствующей таргетингу.

Обратите внимание, что для предоставления данных необходимо охватить минимальное количество уникальных людей. Если минимальное число не достигнуто, значение onTargetReach будет округлено до 0.

totalReach

string ( int64 format)

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

Обратите внимание, что для предоставления данных необходимо охватить минимальное количество уникальных людей. Если минимальное число не достигнуто, значение totalReach будет округлено до 0.

effectiveCoviewReach

string ( int64 format)

Число пользователей (включая пользователей совместного просмотра), достигнутое для связанного значения effectFrequency.

onTargetEffectiveCoviewReach

string ( int64 format)

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

ПланируемыйПродуктОхватПрогноз

Прогнозируемые показатели распределения и трафика для конкретного продукта в точке кривой охвата.

JSON-представление
{
  "plannableProductCode": string,
  "costMicros": string,
  "plannedProductForecast": {
    object (PlannedProductForecast)
  }
}
Поля
plannableProductCode

string

Выбранный продукт для планирования. Возвращенные коды продуктов входят в набор кодов, возвращаемых ListPlannableProducts при использовании того же идентификатора местоположения.

costMicros

string ( int64 format)

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

plannedProductForecast

object ( PlannedProductForecast )

Прогнозируемые показатели трафика для этого продукта.

ПланируемыйПродуктПрогноз

Прогнозируемые показатели трафика для планируемого продукта.

JSON-представление
{
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string,
  "averageFrequency": number,
  "views": string
}
Поля
onTargetReach

string ( int64 format)

Количество охваченных уникальных людей, точно соответствующее таргетингу.

Обратите внимание, что для предоставления данных необходимо охватить минимальное количество уникальных людей. Если минимальное число не достигнуто, значение onTargetReach будет округлено до 0.

totalReach

string ( int64 format)

Количество охваченных уникальных людей. Сюда входят люди, которые могут выходить за рамки указанного таргетинга.

Обратите внимание, что для предоставления данных необходимо охватить минимальное количество уникальных людей. Если минимальное число не достигнуто, значение totalReach будет округлено до 0.

onTargetImpressions

string ( int64 format)

Количество показов объявления, точно соответствующее таргетингу.

totalImpressions

string ( int64 format)

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

viewableImpressions

string ( int64 format)

Сколько раз показы объявления считались видимыми. См. https://support.google.com/google-ads/answer/7029393 для получения дополнительной информации о том, что делает объявление видимым и как измеряется видимость.

onTargetCoviewReach

string ( int64 format)

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

totalCoviewReach

string ( int64 format)

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

onTargetCoviewImpressions

string ( int64 format)

Количество показов рекламы, точно соответствующих таргетингу, включая со-просмотрщиков.

totalCoviewImpressions

string ( int64 format)

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

averageFrequency

number

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

Дополнительную информацию о кампаниях с целевой частотой см. на странице https://support.google.com/google-ads/answer/12400225 .

views

string ( int64 format)

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

Дополнительную информацию о просмотрах см. на странице https://support.google.com/google-ads/answer/2375431 .