Method: customers.generateReachForecast

Gera uma previsão de alcance para uma determinada segmentação / mix de produtos.

Lista de erros gerados: AuthenticationError AuthorizationError FieldError HeaderError InternalError QuotaError RangeError ReachPlanError RequestError

Solicitação HTTP

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

O URL usa a sintaxe de transcodificação gRPC.

Parâmetros de caminho

Parâmetros
customerId

string

Obrigatório. O ID do cliente.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação 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
}
Campos
campaignDuration

object (CampaignDuration)

Obrigatório. Duração da campanha.
cookieFrequencyCapSetting

object (FrequencyCap)

Escolha o limite de frequência de cookies a ser aplicado a cada produto planejado. Isso equivale ao limite de frequência exposto no Google Ads ao criar uma campanha. Ele representa o número máximo de vezes que um anúncio pode ser exibido para o mesmo usuário durante um período especificado. Se não for especificado, um padrão de 0 (sem limite) será aplicado.

Esse campo substitui o campo cookieFrequencyCap descontinuado.
targeting

object (Targeting)

A segmentação a ser aplicada a todos os produtos selecionados no mix de produtos.

Essa é a segmentação planejada: os detalhes da execução podem variar com base no produto de publicidade. Consulte um especialista em implementação.

Consulte métricas específicas para ver detalhes sobre como elas são afetadas pela segmentação.
plannedProducts[]

object (PlannedProduct)

Obrigatório. Os produtos a serem previstos. O número máximo de produtos planejados permitidos é 15.
forecastMetricOptions

object (ForecastMetricOptions)

Controla as métricas de previsão retornadas na resposta.
currencyCode

string

O código da moeda. Código de moeda ISO 4217 com três caracteres.
cookieFrequencyCap

integer

Escolha o limite de frequência de cookies a ser aplicado a cada produto planejado. Isso equivale ao limite de frequência exposto no Google Ads ao criar uma campanha. Ele representa o número máximo de vezes que um anúncio pode ser exibido para o mesmo usuário. Se não for especificado, nenhum limite será aplicado.

Este campo foi descontinuado na v4 e será removido em algum momento. Use cookieFrequencyCapSetting.
minEffectiveFrequency

integer

A frequência efetiva mínima escolhida (o número de vezes que uma pessoa foi exposta ao anúncio) para as métricas de alcance informado [1-10]. Isso não afeta a segmentação, apenas os relatórios. Se não for especificado, o padrão 1 será aplicado.

Este campo não pode ser combinado com o campo effectiveFrequencyLimit.
effectiveFrequencyLimit

object (EffectiveFrequencyLimit)

O valor [1-10] da maior frequência efetiva mínima (o número de vezes que uma pessoa foi exposta ao anúncio) para incluir em Forecast.effective_frequency_breakdowns. Se não for especificado, Forecast.effective_frequency_breakdowns não serão fornecidos.

O valor de frequência efetiva fornecido aqui também será usado como a frequência efetiva mínima para as métricas de alcance informadas.

Este campo não pode ser combinado com o campo minEffectiveFrequency.
customerReachGroup

string

O nome do cliente para quem está planejado. Esse é um valor definido pelo usuário.

Corpo da resposta

Mensagem de resposta contendo a curva de alcance gerada.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação JSON 
{
  "onTargetAudienceMetrics": {
    object (OnTargetAudienceMetrics)
  },
  "reachCurve": {
    object (ReachCurve)
  }
}
Campos
onTargetAudienceMetrics

object (OnTargetAudienceMetrics)

Referência sobre os públicos-alvo para esta curva.
reachCurve

object (ReachCurve)

A curva de alcance gerada para o mix planejado de produtos.

Escopos de autorização

Requer o seguinte escopo OAuth:

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

Para mais informações, consulte a Visão geral do OAuth 2.0.

CampaignDuration

A duração de uma campanha planejada.

Representação JSON 
{
  "dateRange": {
    object (DateRange)
  },
  "durationInDays": integer
}
Campos
dateRange

object (DateRange)

Período da campanha. As datas estão no formato aaaa-mm-dd e são inclusivas. A data de término deve ser < 1 ano no futuro, e o período deve ser <= 92 dias.

Este campo não pode ser combinado com o campoDurationInDays.
durationInDays

integer

O valor da duração em dias.

Este campo não pode ser combinado com o campo dateRange.

FrequencyCap

Uma regra que especifica o número máximo de vezes que um anúncio pode ser exibido para um usuário em determinado período.

Representação JSON 
{
  "impressions": integer,
  "timeUnit": enum (FrequencyCapTimeUnit)
}
Campos
impressions

integer

Obrigatório. É o número de impressões, inclusive.
timeUnit

enum (FrequencyCapTimeUnit)

Obrigatório. O tipo de unidade de tempo.

EffectiveFrequencyLimit

Limite de frequência efetiva.

Representação JSON 
{
  "effectiveFrequencyBreakdownLimit": integer
}
Campos
effectiveFrequencyBreakdownLimit

integer

O maior valor de frequência efetiva a ser incluído em Forecast.effective_frequency_breakdowns. Este campo suporta frequências de 1 a 10, inclusive.

Segmentação

A segmentação sobre a qual as métricas de tráfego serão informadas.

Representação JSON 
{
  "plannableLocationIds": [
    string
  ],
  "ageRange": enum (ReachPlanAgeRange),
  "genders": [
    {
      object (GenderInfo)
    }
  ],
  "devices": [
    {
      object (DeviceInfo)
    }
  ],
  "network": enum (ReachPlanNetwork),
  "audienceTargeting": {
    object (AudienceTargeting)
  },
  "plannableLocationId": string
}
Campos
plannableLocationIds[]

string

É a lista de códigos de locais programáveis para segmentar com essa previsão.

Se mais de um for fornecido, todos os IDs precisarão ter o mesmo parentCountryId. O planejamento para mais de parent_county não é compatível. Os IDs de local planejados e os respectivos parentCountryId podem ser recebidos em ReachPlanService.ListPlannableLocations.

As solicitações precisam definir esse campo ou plannableLocationId.
ageRange

enum (ReachPlanAgeRange)

Faixa etária segmentada. Um valor não definido é equivalente a segmentar todas as idades.
genders[]

object (GenderInfo)

Sexos segmentados. Um valor não definido é equivalente a segmentar MALE e FEMALE.
devices[]

object (DeviceInfo)

Dispositivos segmentados. Se não for especificado, todos os dispositivos aplicáveis serão segmentados. Os dispositivos aplicáveis variam de acordo com o produto e a região e podem ser obtidos a partir de ReachPlanService.ListPlannableProducts.
network

enum (ReachPlanNetwork)

Rede segmentável para o produto de anúncio. Se não for especificado, segmenta todas as redes aplicáveis. As redes aplicáveis variam de acordo com o produto e a região e podem ser obtidas a partir de ReachPlanService.ListPlannableProducts.
audienceTargeting

object (AudienceTargeting)

Públicos-alvo segmentados. Se não for especificado, não vai segmentar um público-alvo específico.
plannableLocationId

string

O ID do local selecionado. Os IDs de local programáveis podem ser recebidos em ReachPlanService.ListPlannableLocations.

As solicitações precisam definir esse campo ou plannableLocationIds.

Este campo foi descontinuado na versão 12 e será removido em uma versão futura. Use plannableLocationIds

AudienceTargeting

Segmentação por público-alvo para previsão de alcance.

Representação JSON 
{
  "userInterest": [
    {
      object (UserInterestInfo)
    }
  ]
}
Campos
userInterest[]

object (UserInterestInfo)

Lista de públicos-alvo a serem segmentados com base nos interesses dos usuários.

PlannedProduct

Um produto que está sendo planejado para alcance.

Representação JSON 
{
  "advancedProductTargeting": {
    object (AdvancedProductTargeting)
  },
  "plannableProductCode": string,
  "budgetMicros": string
}
Campos
advancedProductTargeting

object (AdvancedProductTargeting)

Configurações de segmentação para o produto selecionado. Para listar a segmentação disponível para cada produto, use ReachPlanService.ListPlannableProducts.
plannableProductCode

string

Obrigatório. Produto selecionado para planejamento. O código associado ao produto do anúncio (por exemplo: TrueView, bumper). Para listar os códigos de produto planificáveis disponíveis, use ReachPlanService.ListPlannableProducts.
budgetMicros

string (int64 format)

Obrigatório. Alocação máxima do orçamento em micros para o produto selecionado. O valor é especificado no currencyCode de planejamento selecionado. Por exemplo: 1 000 000$ = 1.000 000 000 000 micros.

AdvancedProductTargeting

Configurações de segmentação avançada para produtos.

Representação JSON 
{

  // 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.
}
Campos
Campo de união advanced_targeting. Opções de segmentação para este produto. advanced_targeting pode ser apenas de um dos tipos a seguir:
youtubeSelectSettings

object (YouTubeSelectSettings)

Configurações da segmentação do YouTube Select.

YouTubeSelectSettings

Pedir configurações para os Lineups do YouTube Select

Representação JSON 
{
  "lineupId": string
}
Campos
lineupId

string (int64 format)

Lineup para segmentação do YouTube Select.

ForecastMetricOptions

Controla as métricas de previsão a serem retornadas.

Representação JSON 
{
  "includeCoview": boolean
}
Campos
includeCoview

boolean

Indica se as métricas de covisualização precisam ser incluídas na previsão de resposta.

OnTargetAudienceMetrics

Métricas de público-alvo para os produtos planejados. Essas métricas consideram as seguintes dimensões de segmentação:

  • Local
  • PlannableAgeRange
  • Gênero
  • AudienceSegmentação (somente para youtubeAudienceSize)
Representação JSON 
{
  "youtubeAudienceSize": string,
  "censusAudienceSize": string
}
Campos
youtubeAudienceSize

string (int64 format)

Tamanho do público de referência que corresponde à segmentação considerada para o YouTube.
censusAudienceSize

string (int64 format)

Consulte o tamanho do público que corresponde à segmentação considerada para o censo.

ReachCurve

A curva de alcance dos produtos planejados.

Representação JSON 
{
  "reachForecasts": [
    {
      object (ReachForecast)
    }
  ]
}
Campos
reachForecasts[]

object (ReachForecast)

Todos os pontos da curva de alcance.

ReachForecast

Um ponto na curva de alcance.

Representação JSON 
{
  "costMicros": string,
  "forecast": {
    object (Forecast)
  },
  "plannedProductReachForecasts": [
    {
      object (PlannedProductReachForecast)
    }
  ]
}
Campos
costMicros

string (int64 format)

O custo em micros.
forecast

object (Forecast)

Métricas de tráfego estimadas para este ponto.
plannedProductReachForecasts[]

object (PlannedProductReachForecast)

As métricas de alocação e tráfego previstas para cada produto planejado neste ponto da curva de alcance.

Previsão

Métricas de tráfego previsto para os produtos planejados e a segmentação.

Representação JSON 
{
  "effectiveFrequencyBreakdowns": [
    {
      object (EffectiveFrequencyBreakdown)
    }
  ],
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string
}
Campos
effectiveFrequencyBreakdowns[]

object (EffectiveFrequencyBreakdown)

Uma lista de previsões de frequência efetiva. A lista é ordenada a partir de 1+ e terminando com o valor definido em GenerateReachPrevRequest.effective_frequency_limit. Se nenhumEffectiveFrequencyLimit tiver sido definido, essa lista vai estar vazia.
onTargetReach

string (int64 format)

Número de pessoas únicas que foram alcançadas, no mínimo, os tempos GenerateReachPredictRequest.min_effective_frequency ou GenerateReachPrevRequest.effective_frequency_limit que corresponde à segmentação.

É preciso alcançar um número mínimo de pessoas únicas para que os dados sejam incluídos no relatório. Se o número mínimo não for atingido, o valor onTargetReach será arredondado para 0.
totalReach

string (int64 format)

É o número total de pessoas únicas que foram alcançadas, pelo menos, os tempos GenerateReachPredictRequest.min_effective_frequency ou GenerateReachPrevRequest.effective_frequency_limit. Isso inclui pessoas que não fazem parte da segmentação especificada.

É preciso alcançar um número mínimo de pessoas únicas para que os dados sejam incluídos no relatório. Se o número mínimo não for atingido, o valor totalReach será arredondado para 0.
onTargetImpressions

string (int64 format)

Número de impressões de anúncios que correspondem exatamente à segmentação.
totalImpressions

string (int64 format)

Número total de impressões de anúncios. Isso inclui impressões que podem estar fora da segmentação especificada devido à insuficiência de informações sobre os usuários conectados.
viewableImpressions

string (int64 format)

Número de vezes que as impressões do anúncio foram consideradas visíveis. Acesse https://support.google.com/google-ads/answer/7029393 para mais informações sobre o que torna um anúncio visível e como a visibilidade é medida.
onTargetCoviewReach

string (int64 format)

Número de pessoas únicas alcançadas que corresponde exatamente à segmentação, incluindo covisualizadores.
totalCoviewReach

string (int64 format)

Número de pessoas únicas alcançadas, incluindo covisualizadores. Isso inclui pessoas que não fazem parte da segmentação especificada.
onTargetCoviewImpressions

string (int64 format)

Número de impressões de anúncios que correspondem exatamente à segmentação, incluindo covisualizadores.
totalCoviewImpressions

string (int64 format)

Número total de impressões de anúncios, incluindo covisualizadores. Isso inclui impressões que podem estar fora da segmentação especificada devido à insuficiência de informações sobre os usuários conectados.

EffectiveFrequencyBreakdown

Um detalhamento do número de pessoas únicas alcançadas em uma determinada frequência efetiva.

Representação JSON 
{
  "effectiveFrequency": integer,
  "onTargetReach": string,
  "totalReach": string,
  "effectiveCoviewReach": string,
  "onTargetEffectiveCoviewReach": string
}
Campos
effectiveFrequency

integer

A frequência efetiva [1-10].
onTargetReach

string (int64 format)

O número de pessoas únicas que alcançaram pelo menos a frequência efetiva que corresponde exatamente à segmentação.

É preciso alcançar um número mínimo de pessoas únicas para que os dados sejam incluídos no relatório. Se o número mínimo não for atingido, o valor onTargetReach será arredondado para 0.
totalReach

string (int64 format)

É o número total de pessoas únicas que foram alcançadas pelo menos eficazFrequência vezes. Isso inclui pessoas que não fazem parte da segmentação especificada.

É preciso alcançar um número mínimo de pessoas únicas para que os dados sejam incluídos no relatório. Se o número mínimo não for atingido, o valor totalReach será arredondado para 0.
effectiveCoviewReach

string (int64 format)

O número de usuários (incluindo usuários de covisualização) alcançados para o valoreffectiveFrequency associado.
onTargetEffectiveCoviewReach

string (int64 format)

O número de usuários (incluindo usuários de covisualização) alcançados para o valoreffectiveFrequency associado do grupo demográfico especificado do plano.

PlannedProductReachForecast

As métricas de alocação e tráfego previstas para um produto específico em um ponto da curva de alcance.

Representação JSON 
{
  "plannableProductCode": string,
  "costMicros": string,
  "plannedProductForecast": {
    object (PlannedProductForecast)
  }
}
Campos
plannableProductCode

string

Produto selecionado para planejamento. Os códigos de produto retornados estão dentro do conjunto dos códigos retornados por ListPlannableProducts ao usar o mesmo código de local.
costMicros

string (int64 format)

O custo em micros. Ela poderá ser diferente da alocação de entradas do produto se um ou mais produtos planejados não cumprirem o orçamento por causa do inventário limitado.
plannedProductForecast

object (PlannedProductForecast)

Métricas de tráfego estimadas para este produto.

PlannedProductForecast

Métricas de tráfego previsto para um produto planejado.

Representação JSON 
{
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string
}
Campos
onTargetReach

string (int64 format)

Número de pessoas únicas alcançadas que corresponde exatamente à segmentação.

É preciso alcançar um número mínimo de pessoas únicas para que os dados sejam incluídos no relatório. Se o número mínimo não for atingido, o valor onTargetReach será arredondado para 0.
totalReach

string (int64 format)

Número de pessoas únicas alcançadas. Isso inclui pessoas que não fazem parte da segmentação especificada.

É preciso alcançar um número mínimo de pessoas únicas para que os dados sejam incluídos no relatório. Se o número mínimo não for atingido, o valor totalReach será arredondado para 0.
onTargetImpressions

string (int64 format)

Número de impressões de anúncios que correspondem exatamente à segmentação.
totalImpressions

string (int64 format)

Número total de impressões de anúncios. Isso inclui impressões que podem estar fora da segmentação especificada devido à insuficiência de informações sobre os usuários conectados.
viewableImpressions

string (int64 format)

Número de vezes que as impressões do anúncio foram consideradas visíveis. Acesse https://support.google.com/google-ads/answer/7029393 para mais informações sobre o que torna um anúncio visível e como a visibilidade é medida.
onTargetCoviewReach

string (int64 format)

Número de pessoas únicas alcançadas que corresponde exatamente à segmentação, incluindo covisualizadores.
totalCoviewReach

string (int64 format)

Número de pessoas únicas alcançadas, incluindo covisualizadores. Isso inclui pessoas que não fazem parte da segmentação especificada.
onTargetCoviewImpressions

string (int64 format)

Número de impressões de anúncios que correspondem exatamente à segmentação, incluindo covisualizadores.
totalCoviewImpressions

string (int64 format)

Número total de impressões de anúncios, incluindo covisualizadores. Isso inclui impressões que podem estar fora da segmentação especificada devido à insuficiência de informações sobre os usuários conectados.