- HTTP-запрос
- Параметры пути
- Тело запроса
- Тело ответа
- Области авторизации
- Продолжительность кампании
- Частота ограничения
- Ограничение эффективной частоты
- Таргетинг
- Таргетинг на аудиторию
- Планируемый продукт
- Расширенный таргетинг на продукт
- Настройки целевой частоты
- YouTubeВыберитеНастройки
- Прогнозметрические параметры
- OnTargetAudienceMetrics
- кривая охвата
- Прогноз охвата
- Прогноз
- Разбивка по эффективной частоте
- ПланируемыйПродуктОхватПрогноз
- ПланируемыйПрогнозПродукта
- Попробуйте!
Создает прогноз охвата для заданного таргетинга/ассортимента продуктов.
Список выброшенных ошибок: AuthenticationError AuthorizationError FieldError HeaderError InternalError QuotaError RangeError ReachPlanError RequestError
HTTP-запрос
POST https://googleads.googleapis.com/v17/customers/{customerId}:generateReachForecast
URL-адрес использует синтаксис транскодирования gRPC .
Параметры пути
Параметры | |
---|---|
customerId | Необходимый. Идентификатор клиента. |
Тело запроса
Тело запроса содержит данные следующей структуры:
JSON-представление |
---|
{ "campaignDuration": { object ( |
Поля | |
---|---|
campaignDuration | Необходимый. Продолжительность кампании. |
cookieFrequencyCapSetting | Выбранное ограничение частоты использования файлов cookie для каждого запланированного продукта. Это эквивалентно ограничению частоты показов в Google Рекламе при создании кампании. Оно представляет собой максимальное количество раз, которое реклама может быть показана одному и тому же пользователю в течение определенного интервала времени. Если не указано, применяется значение по умолчанию 0 (без ограничения). Это поле заменяет устаревшее поле cookieFrequencyCap. |
targeting | Таргетинг будет применен ко всем продуктам, выбранным в ассортименте. Это плановый таргетинг: детали реализации могут различаться в зависимости от рекламного продукта, проконсультируйтесь со специалистом по внедрению. Подробную информацию о том, как на них влияет таргетинг, смотрите в конкретных показателях. |
plannedProducts[] | Необходимый. Продукты, которые будут прогнозироваться. Максимальное количество разрешенных плановых продуктов — 15. |
forecastMetricOptions | Управляет метриками прогноза, возвращаемыми в ответе. |
currencyCode | Код валюты. Трехзначный код валюты ISO 4217. |
cookieFrequencyCap | Выбранное ограничение частоты использования файлов cookie для каждого запланированного продукта. Это эквивалентно ограничению частоты показов в Google Рекламе при создании кампании. Оно представляет собой максимальное количество раз, когда реклама может быть показана одному и тому же пользователю. Если не указано, ограничение не применяется. Это поле устарело в версии 4 и в конечном итоге будет удалено. Вместо этого используйте cookieFrequencyCapSetting. |
minEffectiveFrequency | Выбрана минимальная эффективная частота (количество раз, когда человек видел рекламу) для сообщаемых показателей охвата [1–10]. Это не повлияет на таргетинг, а только на отчетность. Если не указано, применяется значение по умолчанию 1. Это поле нельзя объединить с полем effectFrequencyLimit. |
effectiveFrequencyLimit | Наивысшее минимальное значение эффективной частоты (количество раз, когда человек видел рекламу) [1–10], которое нужно включить в Forecast.efficient_ Frequency_breakdowns. Если не указано, Forecast.efficiency_breakdowns предоставляться не будет. Указанное здесь значение эффективной частоты также будет использоваться в качестве минимальной эффективной частоты для сообщаемых показателей охвата. Это поле нельзя объединить с полем minEffectiveFrequency. |
customerReachGroup | Имя планируемого клиента. Это определяемое пользователем значение. |
Тело ответа
Ответное сообщение, содержащее сгенерированную кривую охвата.
В случае успеха тело ответа содержит данные следующей структуры:
JSON-представление |
---|
{ "onTargetAudienceMetrics": { object ( |
Поля | |
---|---|
onTargetAudienceMetrics | Ссылка на целевую аудиторию для этой кривой. |
reachCurve | Сгенерированная кривая охвата для запланированного ассортимента продукции. |
Области авторизации
Требуется следующая область действия OAuth:
-
https://www.googleapis.com/auth/adwords
Дополнительную информацию см. в обзоре OAuth 2.0 .
Продолжительность кампании
Продолжительность запланированной кампании.
JSON-представление |
---|
{
"dateRange": {
object ( |
Поля | |
---|---|
dateRange | Диапазон дат кампании. Даты указываются в формате гггг-мм-дд включительно. Дата окончания должна быть <1 года в будущем, а длина диапазона дат должна быть <= 92 дня. Это поле нельзя объединить с полем periodInDays. |
durationInDays | Значение продолжительности в днях. Это поле нельзя объединить с полем dateRange. |
Частота ограничения
Правило, определяющее максимальное количество раз, которое объявление может быть показано пользователю за определенный период времени.
JSON-представление |
---|
{
"impressions": integer,
"timeUnit": enum ( |
Поля | |
---|---|
impressions | Необходимый. Количество показов включительно. |
timeUnit | Необходимый. Тип единицы времени. |
Ограничение эффективной частоты
Эффективный предел частоты.
JSON-представление |
---|
{ "effectiveFrequencyBreakdownLimit": integer } |
Поля | |
---|---|
effectiveFrequencyBreakdownLimit | Максимальное значение эффективной частоты, которое нужно включить в Forecast.efficient_ Frequency_breakdowns. Данное поле поддерживает частоты 1-10 включительно. |
Таргетинг
Таргетинг, для которого будут сообщаться показатели трафика.
JSON-представление |
---|
{ "plannableLocationIds": [ string ], "ageRange": enum ( |
Поля | |
---|---|
plannableLocationIds[] | Список планируемых идентификаторов местоположений для таргетинга с помощью этого прогноза. Если указано более одного идентификатора, все идентификаторы должны иметь один и тот же Запросы должны устанавливать либо это поле, либо |
ageRange | Целевой возрастной диапазон. Неустановленное значение эквивалентно таргетингу на все возрасты. |
genders[] | Целевые гендеры. Неустановленное значение эквивалентно таргетингу на МУЖЧИН и ЖЕНЩИН. |
devices[] | Целевые устройства. Если не указано, нацелено на все применимые устройства. Применимые устройства различаются в зависимости от продукта и региона. Их можно получить из |
network | Целевая сеть для рекламного продукта. Если не указано, нацелены на все применимые сети. Применимые сети различаются в зависимости от продукта и региона, их можно получить из |
audienceTargeting | Целевая аудитория. Если не указано, не ориентировано на какую-либо конкретную аудиторию. |
plannableLocationId | Идентификатор выбранного местоположения. Идентификаторы планируемых местоположений можно получить из Запросы должны устанавливать либо это поле, либо Это поле устарело начиная с версии 12 и будет удалено в будущем выпуске. Вместо этого используйте |
Таргетинг на аудиторию
Таргетинг на аудиторию для прогноза охвата.
JSON-представление |
---|
{
"userInterest": [
{
object ( |
Поля | |
---|---|
userInterest[] | Список целевых аудиторий на основе интересов пользователей. |
Планируемый продукт
Продукт, который планируется достичь.
JSON-представление |
---|
{
"advancedProductTargeting": {
object ( |
Поля | |
---|---|
advancedProductTargeting | Настройки таргетинга для выбранного продукта. Чтобы просмотреть доступный таргетинг для каждого продукта, используйте |
plannableProductCode | Необходимый. Выбранный продукт для планирования. Код, связанный с рекламным продуктом (например: Trueview, Bumper). Чтобы просмотреть доступные планируемые коды продуктов, используйте |
budgetMicros | Необходимый. Максимальное выделение бюджета в микронах для выбранного продукта. Значение указывается в выбранном коде валюты планирования. Например: 1 000 000$ = 1 000 000 000 000 микрон. |
Расширенный таргетинг на продукт
Расширенные настройки таргетинга для товаров.
JSON-представление |
---|
{ "surfaceTargetingSettings": { object ( |
Поля | |
---|---|
surfaceTargetingSettings | Настройки таргетинга на поверхность для этого продукта. |
targetFrequencySettings | Настройки кампании с целевой частотой. Должен быть установлен при выборе продукта TARGET_FREQUENCY. Дополнительную информацию о кампаниях с целевой частотой см. на странице https://support.google.com/google-ads/answer/12400225 . |
Поле объединения advanced_targeting . Параметры таргетинга для этого продукта. advanced_targeting может быть только одним из следующих: | |
youtubeSelectSettings | Настройки таргетинга YouTube Select. |
Настройки целевой частоты
Настройки целевой частоты для поддерживаемого продукта.
JSON-представление |
---|
{
"timeUnit": enum ( |
Поля | |
---|---|
timeUnit | Необходимый. Единица времени, используемая для описания временного интервала targetFrequency. |
targetFrequency | Необходимый. Целевая частота показов в выбранную единицу времени. |
YouTubeВыберитеНастройки
Запрос настроек для избранных подборок YouTube
JSON-представление |
---|
{ "lineupId": string } |
Поля | |
---|---|
lineupId | Подборка для YouTube Select Targeting. |
Прогнозметрические параметры
Управляет возвращаемыми показателями прогноза.
JSON-представление |
---|
{ "includeCoview": boolean } |
Поля | |
---|---|
includeCoview | Указывает, включать ли показатели совместного просмотра в прогноз ответа. |
OnTargetAudienceMetrics
Показатели аудитории для планируемых продуктов. Эти показатели учитывают следующие параметры таргетинга:
- Расположение
- Планируемыйвозрастдиапазон
- Пол
- AudienceTargeting (только для youtubeAudienceSize)
JSON-представление |
---|
{ "youtubeAudienceSize": string, "censusAudienceSize": string } |
Поля | |
---|---|
youtubeAudienceSize | Размер эталонной аудитории соответствует рассматриваемому таргетингу на YouTube. |
censusAudienceSize | Размер эталонной аудитории соответствует предполагаемому таргетингу переписи населения. |
кривая охвата
Кривая охвата запланированных продуктов.
JSON-представление |
---|
{
"reachForecasts": [
{
object ( |
Поля | |
---|---|
reachForecasts[] | Все точки на кривой досягаемости. |
Прогноз охвата
Точка на кривой досягаемости.
JSON-представление |
---|
{ "costMicros": string, "forecast": { object ( |
Поля | |
---|---|
costMicros | Стоимость в микрон. |
forecast | Прогнозируемые показатели трафика для этой точки. |
plannedProductReachForecasts[] | Прогнозируемые показатели распределения и трафика для каждого запланированного продукта в данной точке кривой охвата. |
Прогноз
Прогнозируемые показатели трафика по планируемым продуктам и таргетингу.
JSON-представление |
---|
{
"effectiveFrequencyBreakdowns": [
{
object ( |
Поля | |
---|---|
effectiveFrequencyBreakdowns[] | Список эффективных прогнозов частоты. Список упорядочивается, начиная с 1+ и заканчивая значением, установленным в GenerateReachForecastRequest.efficient_ Frequency_limit. Если не было установлено effectFrequencyLimit, этот список будет пустым. |
onTargetReach | Количество уникальных людей, достигших как минимум GenerateReachForecastRequest.min_efficient_ Frequency или GenerateReachForecastRequest.efficient_ Frequency_limit раз, что точно соответствует таргетингу. Обратите внимание, что для предоставления данных необходимо охватить минимальное количество уникальных людей. Если минимальное число не достигнуто, значение onTargetReach будет округлено до 0. |
totalReach | Общее количество уникальных людей достигло как минимум GenerateReachForecastRequest.min_efficient_ Frequency или GenerateReachForecastRequest.efficient_ Frequency_limit раз. Сюда входят люди, которые могут выходить за рамки указанного таргетинга. Обратите внимание, что для предоставления данных необходимо охватить минимальное количество уникальных людей. Если минимальное число не достигнуто, значение totalReach будет округлено до 0. |
onTargetImpressions | Количество показов объявления, точно соответствующее таргетингу. |
totalImpressions | Общее количество показов рекламы. Сюда входят показы, которые могут выйти за рамки указанного таргетинга из-за недостаточной информации о вошедших в систему пользователях. |
viewableImpressions | Сколько раз показы объявления считались видимыми. См. https://support.google.com/google-ads/answer/7029393 для получения дополнительной информации о том, что делает объявление видимым и как измеряется видимость. |
onTargetCoviewReach | Количество охваченных уникальных людей, точно соответствующих таргетингу, включая со-просмотрщиков. |
totalCoviewReach | Количество охваченных уникальных людей, включая со-просмотрщиков. Сюда входят люди, которые могут выходить за рамки указанного таргетинга. |
onTargetCoviewImpressions | Количество показов рекламы, точно соответствующих таргетингу, включая со-просмотрщиков. |
totalCoviewImpressions | Общее количество показов рекламы, включая со-просмотрщиков. Сюда входят показы, которые могут выйти за рамки указанного таргетинга из-за недостаточной информации о вошедших в систему пользователях. |
views | Прогнозируемое количество просмотров рекламы для указанного продукта и таргетинга. Просмотр засчитывается, когда зритель просматривает большую часть или всю рекламу, помимо показа. Дополнительную информацию о просмотрах см. на странице https://support.google.com/google-ads/answer/2375431 . |
Разбивка по эффективной частоте
Разбивка количества уникальных людей, охваченных с заданной эффективной частотой.
JSON-представление |
---|
{ "effectiveFrequency": integer, "onTargetReach": string, "totalReach": string, "effectiveCoviewReach": string, "onTargetEffectiveCoviewReach": string } |
Поля | |
---|---|
effectiveFrequency | Эффективная частота [1-10]. |
onTargetReach | Количество уникальных людей, достигших как минимум эффективной частоты, точно соответствующей таргетингу. Обратите внимание, что для предоставления данных необходимо охватить минимальное количество уникальных людей. Если минимальное число не достигнуто, значение onTargetReach будет округлено до 0. |
totalReach | Общее количество уникальных людей достигло как минимум эффективной частоты раз. Сюда входят люди, которые могут выходить за рамки указанного таргетинга. Обратите внимание, что для предоставления данных необходимо охватить минимальное количество уникальных людей. Если минимальное число не достигнуто, значение totalReach будет округлено до 0. |
effectiveCoviewReach | Число пользователей (включая пользователей совместного просмотра), достигнутое для связанного значения effectFrequency. |
onTargetEffectiveCoviewReach | Число пользователей (включая пользователей совместного просмотра), достигших соответствующего значения effectFrequency в пределах указанной демографической группы плана. |
ПланируемыйПродуктОхватПрогноз
Прогнозируемые показатели распределения и трафика для конкретного продукта в точке кривой охвата.
JSON-представление |
---|
{
"plannableProductCode": string,
"costMicros": string,
"plannedProductForecast": {
object ( |
Поля | |
---|---|
plannableProductCode | Выбранный продукт для планирования. Возвращенные коды продуктов входят в набор кодов, возвращаемых ListPlannableProducts при использовании того же идентификатора местоположения. |
costMicros | Стоимость в микрон. Это может отличаться от распределения ресурсов по продуктам, если один или несколько запланированных продуктов не могут выполнить бюджет из-за ограниченных запасов. |
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 | Количество охваченных уникальных людей, точно соответствующее таргетингу. Обратите внимание, что для предоставления данных необходимо охватить минимальное количество уникальных людей. Если минимальное число не достигнуто, значение onTargetReach будет округлено до 0. |
totalReach | Количество охваченных уникальных людей. Сюда входят люди, которые могут выходить за рамки указанного таргетинга. Обратите внимание, что для предоставления данных необходимо охватить минимальное количество уникальных людей. Если минимальное число не достигнуто, значение totalReach будет округлено до 0. |
onTargetImpressions | Количество показов объявления, точно соответствующее Таргетингу. |
totalImpressions | Общее количество показов рекламы. Сюда входят показы, которые могут выйти за рамки указанного таргетинга из-за недостаточной информации о вошедших в систему пользователях. |
viewableImpressions | Сколько раз показы объявления считались видимыми. См. https://support.google.com/google-ads/answer/7029393 для получения дополнительной информации о том, что делает объявление видимым и как измеряется видимость. |
onTargetCoviewReach | Количество охваченных уникальных людей, точно соответствующих таргетингу, включая со-просмотрщиков. |
totalCoviewReach | Количество охваченных уникальных людей, включая со-просмотрщиков. Сюда входят люди, которые могут выходить за рамки указанного таргетинга. |
onTargetCoviewImpressions | Количество показов рекламы, точно соответствующих таргетингу, включая со-просмотрщиков. |
totalCoviewImpressions | Общее количество показов рекламы, включая со-просмотрщиков. Сюда входят показы, которые могут выйти за рамки указанного таргетинга из-за недостаточной информации о вошедших в систему пользователях. |
averageFrequency | Количество раз за выбранную единицу времени, которое пользователь увидит рекламу, усредненное по количеству единиц времени в прогнозируемой продолжительности. Это поле будет заполнено только для кампании с целевой частотой. Дополнительную информацию о кампаниях с целевой частотой см. на странице https://support.google.com/google-ads/answer/12400225 . |
views | Прогнозируемое количество просмотров рекламы для указанного продукта и таргетинга. Просмотр засчитывается, когда зритель просматривает большую часть или всю рекламу, помимо показа. Дополнительную информацию о просмотрах см. на странице https://support.google.com/google-ads/answer/2375431 . |