Method: customers.generateReachForecast

Genera una previsione di copertura per un determinato targeting / mix di prodotti.

Elenco degli errori generati: AuthenticationError AuthorizationError FieldError HeaderError InternalError QuotaError RangeError ReachPlanError RequestError

Richiesta HTTP

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

L'URL utilizza la sintassi di transcodifica gRPC.

Parametri del percorso

Parametri
customerId

string

obbligatorio. L'ID del cliente.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione 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
}
Campi
campaignDuration

object (CampaignDuration)

obbligatorio. Durata della campagna.
cookieFrequencyCapSetting

object (FrequencyCap)

È stata scelta una quota limite dei cookie da applicare a ciascun prodotto pianificato. Equivale alla quota limite mostrata in Google Ads durante la creazione di una campagna, ma rappresenta il numero massimo di volte in cui un annuncio può essere mostrato allo stesso utente in un intervallo di tempo specificato. Se non specificato, viene applicato il valore predefinito 0 (nessun limite).

Questo campo sostituisce il campo cookieFrequencyCap obsoleto.
targeting

object (Targeting)

Il targeting da applicare a tutti i prodotti selezionati nel mix di prodotti.

Si tratta di targeting pianificato: i dettagli dell'esecuzione potrebbero variare in base al prodotto pubblicitario; consulta un esperto di implementazione.

Consulta metriche specifiche per informazioni dettagliate su come il targeting influisce su di essi.
plannedProducts[]

object (PlannedProduct)

obbligatorio. I prodotti da prevedere. Il numero massimo di prodotti pianificati consentiti è 15.
forecastMetricOptions

object (ForecastMetricOptions)

Controlla le metriche di previsione restituite nella risposta.
currencyCode

string

Il codice valuta. Codice valuta ISO 4217 a tre caratteri.
cookieFrequencyCap

integer

È stata scelta una quota limite dei cookie da applicare a ciascun prodotto pianificato. Equivale alla quota limite mostrata in Google Ads durante la creazione di una campagna, ma rappresenta il numero massimo di volte in cui un annuncio può essere mostrato allo stesso utente. Se non specificato, non viene applicato alcun limite.

Questo campo è obsoleto nella versione 4 e verrà rimosso. Usa invece cookieFrequencyCapSetting.
minEffectiveFrequency

integer

È stata scelta la frequenza minima effettiva (il numero di volte in cui una persona è stata esposta all'annuncio) per le metriche di copertura segnalate [1-10]. Ciò non influirà sul targeting, ma solo sui report. Se non specificato, viene applicato il valore predefinito 1.

Questo campo non può essere combinato con il campoeffectiveFrequencyLimit.
effectiveFrequencyLimit

object (EffectiveFrequencyLimit)

Il valore della frequenza minima effettiva più alta (il numero di volte in cui una persona è stata esposta all'annuncio) [1-10] da includere in Forecast.effective_frequency_breakdowns. Se non specificato, Forecast.effective_frequency_breakdowns non verrà fornito.

Il valore della frequenza effettiva qui fornito verrà utilizzato anche come frequenza effettiva minima per le metriche di copertura dei report.

Questo campo non può essere combinato con il campo minEffectiveFrequency.
customerReachGroup

string

Il nome del cliente per il quale stai eseguendo la pianificazione. Questo è un valore definito dall'utente.

Corpo della risposta

Messaggio di risposta contenente la curva di copertura generata.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "onTargetAudienceMetrics": {
    object (OnTargetAudienceMetrics)
  },
  "reachCurve": {
    object (ReachCurve)
  }
}
Campi
onTargetAudienceMetrics

object (OnTargetAudienceMetrics)

Riferimento sui segmenti di pubblico di destinazione per questa curva.
reachCurve

object (ReachCurve)

La curva di copertura generata per il mix di prodotti pianificato.

Ambiti di autorizzazione

Richiede il seguente ambito OAuth:

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

Per ulteriori informazioni, consulta la pagina Panoramica di OAuth 2.0.

CampaignDuration

La durata di una campagna pianificata.

Rappresentazione JSON 
{
  "dateRange": {
    object (DateRange)
  },
  "durationInDays": integer
}
Campi
dateRange

object (DateRange)

Intervallo di date della campagna. Le date sono nel formato aaaa-mm-gg e incluse. La data di fine deve essere successiva a un anno e l'intervallo di date non deve superare i 92 giorni.

Questo campo non può essere combinato con il campoDurationInDays.
durationInDays

integer

Il valore della durata in giorni.

Questo campo non può essere combinato con il campo dateRange.

FrequencyCap

Una regola che specifica il numero massimo di volte in cui un annuncio può essere mostrato a un utente in un determinato periodo di tempo.

Rappresentazione JSON 
{
  "impressions": integer,
  "timeUnit": enum (FrequencyCapTimeUnit)
}
Campi
impressions

integer

obbligatorio. Il numero di impressioni incluse.
timeUnit

enum (FrequencyCapTimeUnit)

obbligatorio. Il tipo di unità di tempo.

EffectiveFrequencyLimit

Limite di frequenza effettivo.

Rappresentazione JSON 
{
  "effectiveFrequencyBreakdownLimit": integer
}
Campi
effectiveFrequencyBreakdownLimit

integer

Il valore della frequenza effettiva più alto da includere in Forecast.effective_frequency_breakdowns. Questo campo supporta le frequenze da 1 a 10 incluse.

Targeting

Il targeting per cui verranno riportate le metriche di traffico.

Rappresentazione JSON 
{
  "plannableLocationIds": [
    string
  ],
  "ageRange": enum (ReachPlanAgeRange),
  "genders": [
    {
      object (GenderInfo)
    }
  ],
  "devices": [
    {
      object (DeviceInfo)
    }
  ],
  "network": enum (ReachPlanNetwork),
  "audienceTargeting": {
    object (AudienceTargeting)
  },
  "plannableLocationId": string
}
Campi
plannableLocationIds[]

string

L'elenco di ID località programmabili da scegliere come target con questa previsione.

Se viene fornito più di un ID, tutti gli ID devono avere lo stesso parentCountryId. La pianificazione per più di parent_county non è supportata. Gli ID località pianificate e i relativi parentCountryId possono essere ottenuti da ReachPlanService.ListPlannableLocations.

Le richieste devono impostare questo campo o plannableLocationId.
ageRange

enum (ReachPlanAgeRange)

Fascia d'età target. Un valore non impostato equivale al targeting di tutte le età.
genders[]

object (GenderInfo)

Generi scelti come target. Un valore non impostato equivale al targeting di MALE e FEMALE.
devices[]

object (DeviceInfo)

Dispositivi target. Se non specificato, sceglie come target tutti i dispositivi applicabili. I dispositivi applicabili variano in base al prodotto e alla regione e possono essere acquistati a partire da ReachPlanService.ListPlannableProducts.
network

enum (ReachPlanNetwork)

Rete utilizzabile come target per il prodotto pubblicitario. Se non specificato, sceglie come target tutte le reti applicabili. Le reti applicabili variano in base al prodotto e alla regione e possono essere ottenute da ReachPlanService.ListPlannableProducts.
audienceTargeting

object (AudienceTargeting)

Segmenti di pubblico target. Se non specificato, non sceglie come target alcun segmento di pubblico specifico.
plannableLocationId

string

L'ID della località selezionata. Gli ID località pianificate possono essere ottenuti da ReachPlanService.ListPlannableLocations.

Le richieste devono impostare questo campo o plannableLocationIds.

Questo campo è obsoleto a partire dalla versione 12 e verrà rimosso in una release futura. Usa invece il criterio plannableLocationIds.

AudienceTargeting

Targeting per pubblico per la previsione di copertura.

Rappresentazione JSON 
{
  "userInterest": [
    {
      object (UserInterestInfo)
    }
  ]
}
Campi
userInterest[]

object (UserInterestInfo)

Elenco di segmenti di pubblico in base agli interessi degli utenti da scegliere come target.

PlannedProduct

Un prodotto pianificato per la copertura.

Rappresentazione JSON 
{
  "advancedProductTargeting": {
    object (AdvancedProductTargeting)
  },
  "plannableProductCode": string,
  "budgetMicros": string
}
Campi
advancedProductTargeting

object (AdvancedProductTargeting)

Impostazioni di targeting per il prodotto selezionato. Per elencare il targeting disponibile per ciascun prodotto, utilizza ReachPlanService.ListPlannableProducts.
plannableProductCode

string

obbligatorio. Prodotto selezionato per la pianificazione. Il codice associato al prodotto pubblicitario (ad esempio: TrueView, Bumper). Per elencare i codici di prodotto pianificabili disponibili, utilizza ReachPlanService.ListPlannableProducts.
budgetMicros

string (int64 format)

obbligatorio. Allocazione massima del budget in micro per il prodotto selezionato. Il valore viene specificato nel valore currencyCode di pianificazione selezionato. Ad esempio: 1 000 000$ = 1 000 000 000 000 micro.

AdvancedProductTargeting

Impostazioni di targeting avanzate per i prodotti.

Rappresentazione 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.
}
Campi
Campo di unione advanced_targeting. Opzioni di targeting per questo prodotto. advanced_targeting può essere solo uno dei seguenti:
youtubeSelectSettings

object (YouTubeSelectSettings)

Impostazioni per il targeting di YouTube Select.

YouTubeSelectSettings

Richiesta delle impostazioni per le selezioni YouTube Select

Rappresentazione JSON 
{
  "lineupId": string
}
Campi
lineupId

string (int64 format)

Selezioni per il targeting di YouTube Select.

ForecastMetricOptions

Consente di controllare le metriche di previsione da restituire.

Rappresentazione JSON 
{
  "includeCoview": boolean
}
Campi
includeCoview

boolean

Indica se includere le metriche di visualizzazione condivisa nella previsione delle risposte.

OnTargetAudienceMetrics

Metriche sul pubblico per i prodotti pianificati. Queste metriche prendono in considerazione le seguenti dimensioni di targeting:

  • Località
  • PlannableAgeRange
  • Genere
  • Targeting per pubblico (solo per youtubeAudienceSize)
Rappresentazione JSON 
{
  "youtubeAudienceSize": string,
  "censusAudienceSize": string
}
Campi
youtubeAudienceSize

string (int64 format)

Dimensione del segmento di pubblico di riferimento corrispondente al targeting considerato per YouTube.
censusAudienceSize

string (int64 format)

Dimensione del segmento di pubblico di riferimento corrispondente al targeting considerato per il censimento.

ReachCurve

La curva di copertura per i prodotti pianificati.

Rappresentazione JSON 
{
  "reachForecasts": [
    {
      object (ReachForecast)
    }
  ]
}
Campi
reachForecasts[]

object (ReachForecast)

Tutti i punti sulla curva di copertura.

ReachForecast

Un punto sulla curva di copertura.

Rappresentazione JSON 
{
  "costMicros": string,
  "forecast": {
    object (Forecast)
  },
  "plannedProductReachForecasts": [
    {
      object (PlannedProductReachForecast)
    }
  ]
}
Campi
costMicros

string (int64 format)

Costo in micro.
forecast

object (Forecast)

Metriche di traffico previste per questo punto.
plannedProductReachForecasts[]

object (PlannedProductReachForecast)

Le metriche relative all'allocazione e al traffico previste per ciascun prodotto pianificato in questo punto della curva di copertura.

Previsione

Metriche di traffico previste per il targeting e i prodotti pianificati.

Rappresentazione JSON 
{
  "effectiveFrequencyBreakdowns": [
    {
      object (EffectiveFrequencyBreakdown)
    }
  ],
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string
}
Campi
effectiveFrequencyBreakdowns[]

object (EffectiveFrequencyBreakdown)

Un elenco di previsioni di frequenza efficaci. L'elenco viene ordinato partendo da 1+ e termina con il valore impostato in GenerateReachPredictionRequest.effective_frequency_limit. Se non è stato impostato effettiveFrequencyLimit, questo elenco sarà vuoto.
onTargetReach

string (int64 format)

Numero di persone uniche raggiunte almeno volte generateReachPredictionRequest.min_effective_frequency o vicino a GenerateReachPredictionRequest.effective_frequency_limit volte che corrisponda esattamente al valore del targeting.

Tieni presente che è necessario raggiungere un numero minimo di utenti unici affinché i dati possano essere inclusi nei report. Se non viene raggiunto il numero minimo, il valore onTargetReach verrà arrotondato a 0.
totalReach

string (int64 format)

Numero totale di utenti unici raggiunti almeno volte generateReachPredictionRequest.min_effective_frequency o metodo GenerateReachRecommendationRequest.effective_frequency_limit. Sono incluse le persone che potrebbero non rientrare nel targeting specificato.

Tieni presente che è necessario raggiungere un numero minimo di utenti unici affinché i dati possano essere inclusi nei report. Se non viene raggiunto il numero minimo, il valore totalReach verrà arrotondato a 0.
onTargetImpressions

string (int64 format)

Numero di impressioni dell'annuncio che corrispondono esattamente al targeting.
totalImpressions

string (int64 format)

Numero totale di impressioni dell'annuncio. Sono incluse le impressioni che potrebbero non rientrare nel targeting specificato a causa di informazioni insufficienti sugli utenti che hanno eseguito l'accesso.
viewableImpressions

string (int64 format)

Numero di volte in cui le impressioni dell'annuncio sono state considerate visibili. Per saperne di più su cosa rende un annuncio visibile e su come viene misurata la visibilità, consulta la pagina https://support.google.com/google-ads/answer/7029393.
onTargetCoviewReach

string (int64 format)

Numero di utenti unici raggiunti che corrisponde esattamente al targeting, inclusi gli utenti con visualizzazione condivisa.
totalCoviewReach

string (int64 format)

Numero di utenti unici raggiunti, inclusi gli utenti con visualizzazione condivisa. Sono incluse le persone che potrebbero non rientrare nel targeting specificato.
onTargetCoviewImpressions

string (int64 format)

Numero di impressioni dell'annuncio che corrispondono esattamente al targeting, inclusi gli utenti con visualizzazione condivisa.
totalCoviewImpressions

string (int64 format)

Numero totale di impressioni dell'annuncio, inclusi gli utenti con visualizzazione condivisa. Sono incluse le impressioni che potrebbero non rientrare nel targeting specificato a causa di informazioni insufficienti sugli utenti che hanno eseguito l'accesso.

EffectiveFrequencyBreakdown

Un'analisi dettagliata del numero di utenti unici raggiunti a una determinata frequenza effettiva.

Rappresentazione JSON 
{
  "effectiveFrequency": integer,
  "onTargetReach": string,
  "totalReach": string,
  "effectiveCoviewReach": string,
  "onTargetEffectiveCoviewReach": string
}
Campi
effectiveFrequency

integer

La frequenza effettiva [1-10].
onTargetReach

string (int64 format)

Il numero di utenti unici che hanno raggiunto almeno una frequenza effettiva che corrisponde esattamente al targeting.

Tieni presente che è necessario raggiungere un numero minimo di utenti unici affinché i dati possano essere inclusi nei report. Se non viene raggiunto il numero minimo, il valore onTargetReach verrà arrotondato a 0.
totalReach

string (int64 format)

Numero totale di utenti unici raggiunti almeno volte in termini di effettiva. Sono incluse le persone che potrebbero non rientrare nel targeting specificato.

Tieni presente che è necessario raggiungere un numero minimo di utenti unici affinché i dati possano essere inclusi nei report. Se non viene raggiunto il numero minimo, il valore totalReach verrà arrotondato a 0.
effectiveCoviewReach

string (int64 format)

Il numero di utenti (inclusi gli utenti che utilizzano la visualizzazione condivisa) raggiunti per il valoreeffectiveFrequency associato.
onTargetEffectiveCoviewReach

string (int64 format)

Il numero di utenti (inclusi gli utenti che guardano la condivisione) raggiunti per il valoreeffectiveFrequency associato nel gruppo demografico del piano specificato.

PlannedProductReachForecast

Le metriche relative all'allocazione e al traffico previste per un prodotto specifico in un punto della curva di copertura.

Rappresentazione JSON 
{
  "plannableProductCode": string,
  "costMicros": string,
  "plannedProductForecast": {
    object (PlannedProductForecast)
  }
}
Campi
plannableProductCode

string

Prodotto selezionato per la pianificazione. I codici di prodotto restituiti sono compresi nell'insieme di quelli restituiti da ListPlannableProducts quando si utilizza lo stesso ID località.
costMicros

string (int64 format)

Costo in micro. Può essere diversa dall'allocazione dell'input del prodotto se uno o più prodotti pianificati non possono soddisfare il budget a causa di un inventario limitato.
plannedProductForecast

object (PlannedProductForecast)

Metriche di traffico previste per questo prodotto.

PlannedProductForecast

Metriche di traffico previste per un prodotto pianificato.

Rappresentazione JSON 
{
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string
}
Campi
onTargetReach

string (int64 format)

Numero di utenti unici raggiunti che corrisponde esattamente al targeting.

Tieni presente che è necessario raggiungere un numero minimo di utenti unici affinché i dati possano essere inclusi nei report. Se non viene raggiunto il numero minimo, il valore onTargetReach verrà arrotondato a 0.
totalReach

string (int64 format)

Numero di utenti unici raggiunti. Sono incluse le persone che potrebbero non rientrare nel targeting specificato.

Tieni presente che è necessario raggiungere un numero minimo di utenti unici affinché i dati possano essere inclusi nei report. Se non viene raggiunto il numero minimo, il valore totalReach verrà arrotondato a 0.
onTargetImpressions

string (int64 format)

Numero di impressioni dell'annuncio che corrispondono esattamente al targeting.
totalImpressions

string (int64 format)

Numero totale di impressioni dell'annuncio. Sono incluse le impressioni che potrebbero non rientrare nel targeting specificato a causa di informazioni insufficienti sugli utenti che hanno eseguito l'accesso.
viewableImpressions

string (int64 format)

Numero di volte in cui le impressioni dell'annuncio sono state considerate visibili. Per saperne di più su cosa rende un annuncio visibile e su come viene misurata la visibilità, consulta la pagina https://support.google.com/google-ads/answer/7029393.
onTargetCoviewReach

string (int64 format)

Numero di utenti unici raggiunti che corrisponde esattamente al targeting, inclusi gli utenti con visualizzazione condivisa.
totalCoviewReach

string (int64 format)

Numero di utenti unici raggiunti, inclusi gli utenti con visualizzazione condivisa. Sono incluse le persone che potrebbero non rientrare nel targeting specificato.
onTargetCoviewImpressions

string (int64 format)

Numero di impressioni dell'annuncio che corrispondono esattamente al targeting, inclusi gli utenti con visualizzazione condivisa.
totalCoviewImpressions

string (int64 format)

Numero totale di impressioni dell'annuncio, inclusi gli utenti con visualizzazione condivisa. Sono incluse le impressioni che potrebbero non rientrare nel targeting specificato a causa di informazioni insufficienti sugli utenti che hanno eseguito l'accesso.