- Solicitação HTTP
- Parâmetros de caminho
- Corpo da solicitação
- Corpo da resposta
- Escopos de autorização
- CampaignDuration
- FrequencyCap
- EffectiveFrequencyLimit
- Segmentação
- AudienceTargeting
- PlannedProduct
- AdvancedProductTargeting
- YouTubeSelectSettings
- ForecastMetricOptions
- OnTargetAudienceMetrics
- ReachCurve (link em inglês)
- ReachForecast
- Previsão
- EffectiveFrequencyBreakdown
- PlannedProductReachForecast
- PlannedProductForecast
- Faça um teste
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 |
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 ( |
Campos | |
---|---|
campaignDuration |
Obrigatório. Duração da campanha. |
cookieFrequencyCapSetting |
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 |
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[] |
Obrigatório. Os produtos a serem previstos. O número máximo de produtos planejados permitidos é 15. |
forecastMetricOptions |
Controla as métricas de previsão retornadas na resposta. |
currencyCode |
O código da moeda. Código de moeda ISO 4217 com três caracteres. |
cookieFrequencyCap |
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 |
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 |
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 |
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 ( |
Campos | |
---|---|
onTargetAudienceMetrics |
Referência sobre os públicos-alvo para esta curva. |
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 ( |
Campos | |
---|---|
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 |
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 ( |
Campos | |
---|---|
impressions |
Obrigatório. É o número de impressões, inclusive. |
timeUnit |
Obrigatório. O tipo de unidade de tempo. |
EffectiveFrequencyLimit
Limite de frequência efetiva.
Representação JSON |
---|
{ "effectiveFrequencyBreakdownLimit": integer } |
Campos | |
---|---|
effectiveFrequencyBreakdownLimit |
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 ( |
Campos | |
---|---|
plannableLocationIds[] |
É 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 As solicitações precisam definir esse campo ou |
ageRange |
Faixa etária segmentada. Um valor não definido é equivalente a segmentar todas as idades. |
genders[] |
Sexos segmentados. Um valor não definido é equivalente a segmentar MALE e FEMALE. |
devices[] |
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 |
network |
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 |
audienceTargeting |
Públicos-alvo segmentados. Se não for especificado, não vai segmentar um público-alvo específico. |
plannableLocationId |
O ID do local selecionado. Os IDs de local programáveis podem ser recebidos em As solicitações precisam definir esse campo ou Este campo foi descontinuado na versão 12 e será removido em uma versão futura. Use |
AudienceTargeting
Segmentação por público-alvo para previsão de alcance.
Representação JSON |
---|
{
"userInterest": [
{
object ( |
Campos | |
---|---|
userInterest[] |
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 ( |
Campos | |
---|---|
advancedProductTargeting |
Configurações de segmentação para o produto selecionado. Para listar a segmentação disponível para cada produto, use |
plannableProductCode |
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 |
budgetMicros |
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 |
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 |
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 |
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 |
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 |
Tamanho do público de referência que corresponde à segmentação considerada para o YouTube. |
censusAudienceSize |
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 ( |
Campos | |
---|---|
reachForecasts[] |
Todos os pontos da curva de alcance. |
ReachForecast
Um ponto na curva de alcance.
Representação JSON |
---|
{ "costMicros": string, "forecast": { object ( |
Campos | |
---|---|
costMicros |
O custo em micros. |
forecast |
Métricas de tráfego estimadas para este ponto. |
plannedProductReachForecasts[] |
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 ( |
Campos | |
---|---|
effectiveFrequencyBreakdowns[] |
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 |
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 |
É 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 |
Número de impressões de anúncios que correspondem exatamente à segmentação. |
totalImpressions |
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 |
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 |
Número de pessoas únicas alcançadas que corresponde exatamente à segmentação, incluindo covisualizadores. |
totalCoviewReach |
Número de pessoas únicas alcançadas, incluindo covisualizadores. Isso inclui pessoas que não fazem parte da segmentação especificada. |
onTargetCoviewImpressions |
Número de impressões de anúncios que correspondem exatamente à segmentação, incluindo covisualizadores. |
totalCoviewImpressions |
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 |
A frequência efetiva [1-10]. |
onTargetReach |
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 |
É 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 |
O número de usuários (incluindo usuários de covisualização) alcançados para o valoreffectiveFrequency associado. |
onTargetEffectiveCoviewReach |
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 ( |
Campos | |
---|---|
plannableProductCode |
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 |
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 |
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 |
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 |
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 |
Número de impressões de anúncios que correspondem exatamente à segmentação. |
totalImpressions |
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 |
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 |
Número de pessoas únicas alcançadas que corresponde exatamente à segmentação, incluindo covisualizadores. |
totalCoviewReach |
Número de pessoas únicas alcançadas, incluindo covisualizadores. Isso inclui pessoas que não fazem parte da segmentação especificada. |
onTargetCoviewImpressions |
Número de impressões de anúncios que correspondem exatamente à segmentação, incluindo covisualizadores. |
totalCoviewImpressions |
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. |