Method: customers.generateReachForecast

Génère une prévision de couverture pour un ciblage / combinaison de produits donné.

Liste des erreurs générées: AuthenticationError AuthorizationError FieldError HeaderError InternalError QuotaError RangeError ReachPlanError RequestError

Requête HTTP

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

L'URL utilise la syntaxe de transcodage gRPC.

Paramètres de chemin d'accès

Paramètres
customerId

string

Obligatoire. ID du client.

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Représentation 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
}
Champs
campaignDuration

object (CampaignDuration)

Obligatoire. Durée de la campagne.
cookieFrequencyCapSetting

object (FrequencyCap)

Choisissez une limite de la fréquence d'exposition des cookies à appliquer à chaque produit planifié. Elle correspond à la limite de la fréquence d'exposition visible dans Google Ads lorsque vous créez une campagne. Elle représente le nombre maximal de fois qu'une annonce peut être diffusée auprès d'un même utilisateur sur un intervalle de temps spécifié. Si aucune valeur n'est spécifiée, la valeur par défaut 0 (sans limite) est appliquée.

Ce champ remplace le champ obsolète cookieFrequencyCap.
targeting

object (Targeting)

Ciblage à appliquer à tous les produits sélectionnés dans le mix produits.

Il s'agit d'un ciblage planifié: les détails de l'exécution peuvent varier selon le produit publicitaire. Consultez un spécialiste de l'implémentation.

Consultez les métriques spécifiques pour en savoir plus sur l'impact du ciblage sur elles.
plannedProducts[]

object (PlannedProduct)

Obligatoire. Produits à prévoir. Le nombre maximal de produits planifiés autorisés est de 15.
forecastMetricOptions

object (ForecastMetricOptions)

Contrôle les métriques de prévision renvoyées dans la réponse.
currencyCode

string

Code de la devise. Code de devise ISO 4217 à trois caractères.
cookieFrequencyCap

integer

Choisissez une limite de la fréquence d'exposition des cookies à appliquer à chaque produit planifié. Cette valeur correspond à la limite de la fréquence d'exposition visible dans Google Ads lorsque vous créez une campagne. Elle représente le nombre maximal de fois qu'une annonce peut être diffusée auprès d'un même utilisateur. Si aucune valeur n'est spécifiée, aucune limite n'est appliquée.

Ce champ est obsolète dans la version 4 et sera à terme supprimé. Utilisez plutôt cookieFrequencyCapSetting.
minEffectiveFrequency

integer

Fréquence effective minimale choisie (nombre de fois où une personne a été exposée à l'annonce) pour les métriques de couverture enregistrées [1-10]. Cette opération n'a pas d'incidence sur le ciblage, mais uniquement sur les rapports. Si aucune valeur n'est spécifiée, la valeur par défaut 1 est appliquée.

Ce champ ne peut pas être combiné au champ efficaceFrequencyLimit.
effectiveFrequencyLimit

object (EffectiveFrequencyLimit)

La valeur de fréquence effective minimale la plus élevée (nombre de fois où une personne a été exposée à l'annonce) à inclure dans Forecast.effective_frequency_breakdowns est [1-10]. Si aucune valeur n'est spécifiée, Forecast.effective_frequency_breakdowns ne sera pas fourni.

La valeur de fréquence effective fournie ici sera également utilisée comme fréquence effective minimale pour les métriques de couverture enregistrées.

Ce champ ne peut pas être combiné au champ minEffectiveFrequency.
customerReachGroup

string

Nom du client pour lequel la planification est effectuée. Il s'agit d'une valeur définie par l'utilisateur.

Corps de la réponse

Message de réponse contenant la courbe de couverture générée.

Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :

Représentation JSON 
{
  "onTargetAudienceMetrics": {
    object (OnTargetAudienceMetrics)
  },
  "reachCurve": {
    object (ReachCurve)
  }
}
Champs
onTargetAudienceMetrics

object (OnTargetAudienceMetrics)

Référence sur les audiences cibles pour cette courbe.
reachCurve

object (ReachCurve)

Courbe de couverture générée pour le mix produits planifié.

Champs d'application des autorisations

Requiert le niveau d'accès OAuth suivant :

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

Pour en savoir plus, consultez la présentation d'OAuth 2.0.

CampaignDuration

Durée d'une campagne planifiée.

Représentation JSON 
{
  "dateRange": {
    object (DateRange)
  },
  "durationInDays": integer
}
Champs
dateRange

object (DateRange)

Plage de dates de la campagne. Les dates sont au format aaaa-mm-jj (inclus). La date de fin doit être postérieure d'un an maximum à la date du jour et la plage de dates ne doit pas durer plus de 92 jours.

Ce champ ne peut pas être associé au champ durationInDays.
durationInDays

integer

Valeur de durée en jours.

Ce champ ne peut pas être associé au champ dateRange.

FrequencyCap

Règle spécifiant le nombre maximal de fois qu'une annonce peut être diffusée auprès d'un utilisateur au cours d'une période donnée.

Représentation JSON 
{
  "impressions": integer,
  "timeUnit": enum (FrequencyCapTimeUnit)
}
Champs
impressions

integer

Obligatoire. Nombre d'impressions (inclus).
timeUnit

enum (FrequencyCapTimeUnit)

Obligatoire. Type d'unité de temps.

EffectiveFrequencyLimit

Limite de fréquence effective

Représentation JSON 
{
  "effectiveFrequencyBreakdownLimit": integer
}
Champs
effectiveFrequencyBreakdownLimit

integer

Valeur de fréquence effective la plus élevée à inclure dans Forecast.effective_frequency_breakdowns. Ce champ prend en charge les fréquences comprises entre 1 et 10.

Ciblage

Ciblage pour lequel les métriques sur le trafic seront prises en compte.

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

string

Liste des ID de zones géographiques pouvant être planifiés à cibler avec cette prévision.

Si plusieurs ID sont fournis, ils doivent tous avoir le même parentCountryId. La planification ne peut pas s'appliquer à plus de parent_county. Les ID de zone géographique planifiables et leur parentCountryId peuvent être obtenus à partir de ReachPlanService.ListPlannableLocations.

Les requêtes doivent définir ce champ ou plannableLocationId.
ageRange

enum (ReachPlanAgeRange)

Tranche d'âge ciblée. Une valeur non définie équivaut à cibler toutes les tranches d'âge.
genders[]

object (GenderInfo)

Critères de sexe ciblés. Une valeur non définie équivaut à cibler les hommes et les femmes.
devices[]

object (DeviceInfo)

Appareils ciblés. Si aucune valeur n'est spécifiée, cible tous les appareils applicables. Les appareils applicables varient selon le produit et la région. Vous pouvez vous les procurer auprès de ReachPlanService.ListPlannableProducts.
network

enum (ReachPlanNetwork)

Réseau disponible pour le ciblage pour le produit publicitaire. Si aucune valeur n'est spécifiée, cible tous les réseaux applicables. Les réseaux applicables varient selon le produit et la région. Vous pouvez les obtenir auprès de ReachPlanService.ListPlannableProducts.
audienceTargeting

object (AudienceTargeting)

Audiences ciblées. Si aucune valeur n'est spécifiée, ne cible aucune audience spécifique.
plannableLocationId

string

ID de l'établissement sélectionné. Vous pouvez obtenir les ID de zone géographique planifiables à partir de ReachPlanService.ListPlannableLocations.

Les requêtes doivent définir ce champ ou plannableLocationIds.

Ce champ est obsolète depuis la version 12 et sera supprimé dans une prochaine version. Utilisez plannableLocationIds à la place.

AudienceTargeting

Ciblage d'audience pour la prévision de couverture.

Représentation JSON 
{
  "userInterest": [
    {
      object (UserInterestInfo)
    }
  ]
}
Champs
userInterest[]

object (UserInterestInfo)

Liste des audiences à cibler en fonction des centres d'intérêt des utilisateurs.

PlannedProduct

Produit que vous prévoyez d'atteindre.

Représentation JSON 
{
  "advancedProductTargeting": {
    object (AdvancedProductTargeting)
  },
  "plannableProductCode": string,
  "budgetMicros": string
}
Champs
advancedProductTargeting

object (AdvancedProductTargeting)

Paramètres de ciblage du produit sélectionné. Afin de lister le ciblage disponible pour chaque produit, utilisez ReachPlanService.ListPlannableProducts.
plannableProductCode

string

Obligatoire. Produit sélectionné pour la planification. Code associé au produit publicitaire (par exemple, TrueView ou bumper). Pour lister les codes des produits planifiables disponibles, utilisez ReachPlanService.ListPlannableProducts.
budgetMicros

string (int64 format)

Obligatoire. Budget maximal alloué pour le produit sélectionné, en micros. La valeur est spécifiée dans le currencyCode de planification sélectionné. Exemple: 1 000 000$ = 1 000 000 000 000 micros.

AdvancedProductTargeting

Paramètres de ciblage avancés des produits.

Représentation 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.
}
Champs
Champ d'union advanced_targeting. Options de ciblage pour ce produit. advanced_targeting ne peut être qu'un des éléments suivants :
youtubeSelectSettings

object (YouTubeSelectSettings)

Paramètres de ciblage YouTube Select.

YouTubeSelectSettings

Paramètres de demande pour les lineups YouTube Select

Représentation JSON 
{
  "lineupId": string
}
Champs
lineupId

string (int64 format)

Lineup pour le ciblage YouTube Select.

ForecastMetricOptions

Contrôle les métriques de prévision à afficher.

Représentation JSON 
{
  "includeCoview": boolean
}
Champs
includeCoview

boolean

Indique si les métriques de covisionnage doivent être incluses dans la prévision de réponse.

OnTargetAudienceMetrics

Métriques d'audience pour les produits prévus. Ces métriques prennent en compte les dimensions de ciblage suivantes:

  • Emplacement
  • PlannableAgeRange
  • Gender
  • Ciblage par type d'audience (uniquement pour youtubeAudienceSize)
Représentation JSON 
{
  "youtubeAudienceSize": string,
  "censusAudienceSize": string
}
Champs
youtubeAudienceSize

string (int64 format)

Taille de l'audience de référence correspondant au ciblage envisagé pour YouTube.
censusAudienceSize

string (int64 format)

Taille de l'audience de référence correspondant au ciblage envisagé pour le recensement.

ReachCurve

Courbe de couverture des produits prévus.

Représentation JSON 
{
  "reachForecasts": [
    {
      object (ReachForecast)
    }
  ]
}
Champs
reachForecasts[]

object (ReachForecast)

Tous les points de la courbe de couverture.

ReachForecast

Point sur la courbe de couverture.

Représentation JSON 
{
  "costMicros": string,
  "forecast": {
    object (Forecast)
  },
  "plannedProductReachForecasts": [
    {
      object (PlannedProductReachForecast)
    }
  ]
}
Champs
costMicros

string (int64 format)

Coût en micro-unités.
forecast

object (Forecast)

Métriques de trafic prévues pour ce point.
plannedProductReachForecasts[]

object (PlannedProductReachForecast)

La répartition prévue et les métriques sur le trafic pour chaque produit planifié à ce stade de la courbe de couverture.

Prévisions

Métriques de trafic prévues pour les produits et le ciblage prévus.

Représentation JSON 
{
  "effectiveFrequencyBreakdowns": [
    {
      object (EffectiveFrequencyBreakdown)
    }
  ],
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string
}
Champs
effectiveFrequencyBreakdowns[]

object (EffectiveFrequencyBreakdown)

Liste des prévisions de fréquence effective. La liste est triée en commençant par 1+ et en se terminant par la valeur définie dans GenerateReachForecastRequest.effective_frequency_limit. Si aucune valeur effectiveFrequencyLimit n'a été définie, cette liste sera vide.
onTargetReach

string (int64 format)

Nombre d'utilisateurs uniques touchés au moins par GenerateReachForecastRequest.min_effective_frequency ou GenerateReachForecastRequest.effective_frequency_limit et correspondant exactement au ciblage.

Notez qu'un nombre minimal d'utilisateurs uniques doit être touché pour que les données soient enregistrées. Si le nombre minimal n'est pas atteint, la valeur onTargetReach est arrondie à 0.
totalReach

string (int64 format)

Nombre total d'utilisateurs uniques touchés au moins par GenerateReachForecastRequest.min_effective_frequency ou GenerateReachForecastRequest.effective_frequency_limit. Cela inclut les utilisateurs susceptibles d'être en dehors du ciblage spécifié.

Notez qu'un nombre minimal d'utilisateurs uniques doit être touché pour que les données soient enregistrées. Si le nombre minimal n'est pas atteint, la valeur de couverture totale est arrondie à 0.
onTargetImpressions

string (int64 format)

Nombre d'impressions d'annonces qui correspond exactement au ciblage.
totalImpressions

string (int64 format)

Nombre total d'impressions d'annonces. Cela inclut les impressions qui peuvent ne pas correspondre au ciblage spécifié, en raison d'informations insuffisantes sur les utilisateurs connectés.
viewableImpressions

string (int64 format)

Nombre de fois où les impressions de l'annonce ont été considérées comme visibles. Consultez la page https://support.google.com/google-ads/answer/7029393 pour en savoir plus sur ce qui rend une annonce visible et sur la façon dont la visibilité est mesurée.
onTargetCoviewReach

string (int64 format)

Nombre d'utilisateurs uniques touchés correspondant exactement au ciblage, y compris les co-spectateurs.
totalCoviewReach

string (int64 format)

Nombre d'utilisateurs uniques touchés, y compris les co-spectateurs. Cela inclut les utilisateurs susceptibles d'être en dehors du ciblage spécifié.
onTargetCoviewImpressions

string (int64 format)

Nombre d'impressions d'annonces correspondant exactement au ciblage, y compris les co-spectateurs.
totalCoviewImpressions

string (int64 format)

Nombre total d'impressions d'annonces, y compris les co-spectateurs. Cela inclut les impressions qui peuvent ne pas correspondre au ciblage spécifié, en raison d'informations insuffisantes sur les utilisateurs connectés.

EffectiveFrequencyBreakdown

Répartition du nombre d'utilisateurs uniques touchés à une fréquence effective donnée.

Représentation JSON 
{
  "effectiveFrequency": integer,
  "onTargetReach": string,
  "totalReach": string,
  "effectiveCoviewReach": string,
  "onTargetEffectiveCoviewReach": string
}
Champs
effectiveFrequency

integer

Fréquence effective [1-10].
onTargetReach

string (int64 format)

Nombre d'utilisateurs uniques touchés au moins à une date efficace correspondant exactement au ciblage.

Notez qu'un nombre minimal d'utilisateurs uniques doit être touché pour que les données soient enregistrées. Si le nombre minimal n'est pas atteint, la valeur onTargetReach est arrondie à 0.
totalReach

string (int64 format)

Nombre total d'utilisateurs uniques touchés au moins efficacement à la fréquence effective. Cela inclut les utilisateurs susceptibles d'être en dehors du ciblage spécifié.

Notez qu'un nombre minimal d'utilisateurs uniques doit être touché pour que les données soient enregistrées. Si le nombre minimal n'est pas atteint, la valeur de couverture totale est arrondie à 0.
effectiveCoviewReach

string (int64 format)

Nombre d'utilisateurs (y compris les utilisateurs qui covisionnage) touchés pour la valeur effectiveFrequency associée.
onTargetEffectiveCoviewReach

string (int64 format)

Nombre d'utilisateurs (y compris ceux du covisionnage) touchés pour la valeur effectiveFrequency associée dans la catégorie démographique du plan spécifiée.

PlannedProductReachForecast

Les métriques sur l'allocation et le trafic prévues pour un produit spécifique à un point de la courbe de couverture.

Représentation JSON 
{
  "plannableProductCode": string,
  "costMicros": string,
  "plannedProductForecast": {
    object (PlannedProductForecast)
  }
}
Champs
plannableProductCode

string

Produit sélectionné pour la planification. Les codes produit affichés font partie de ceux renvoyés par ListPlannableProducts avec le même identifiant de zone géographique.
costMicros

string (int64 format)

Coût en micro-unités. Cette valeur peut différer de la répartition des entrées du produit si un ou plusieurs produits planifiés ne peuvent pas respecter le budget en raison d'un inventaire limité.
plannedProductForecast

object (PlannedProductForecast)

Métriques de trafic prévues pour ce produit.

PlannedProductForecast

Métriques de trafic prévues pour un produit planifié.

Représentation JSON 
{
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string
}
Champs
onTargetReach

string (int64 format)

Nombre d'utilisateurs uniques touchés correspondant exactement au ciblage.

Notez qu'un nombre minimal d'utilisateurs uniques doit être touché pour que les données soient enregistrées. Si le nombre minimal n'est pas atteint, la valeur onTargetReach est arrondie à 0.
totalReach

string (int64 format)

Nombre d'utilisateurs uniques touchés. Cela inclut les utilisateurs susceptibles d'être en dehors du ciblage spécifié.

Notez qu'un nombre minimal d'utilisateurs uniques doit être touché pour que les données soient enregistrées. Si le nombre minimal n'est pas atteint, la valeur de couverture totale est arrondie à 0.
onTargetImpressions

string (int64 format)

Nombre d'impressions d'annonces qui correspond exactement au ciblage.
totalImpressions

string (int64 format)

Nombre total d'impressions d'annonces. Cela inclut les impressions qui peuvent ne pas correspondre au ciblage spécifié, en raison d'informations insuffisantes sur les utilisateurs connectés.
viewableImpressions

string (int64 format)

Nombre de fois où les impressions de l'annonce ont été considérées comme visibles. Consultez la page https://support.google.com/google-ads/answer/7029393 pour en savoir plus sur ce qui rend une annonce visible et sur la façon dont la visibilité est mesurée.
onTargetCoviewReach

string (int64 format)

Nombre d'utilisateurs uniques touchés correspondant exactement au ciblage, y compris les co-spectateurs.
totalCoviewReach

string (int64 format)

Nombre d'utilisateurs uniques touchés, y compris les co-spectateurs. Cela inclut les utilisateurs susceptibles d'être en dehors du ciblage spécifié.
onTargetCoviewImpressions

string (int64 format)

Nombre d'impressions d'annonces correspondant exactement au ciblage, y compris les co-spectateurs.
totalCoviewImpressions

string (int64 format)

Nombre total d'impressions d'annonces, y compris les co-spectateurs. Cela inclut les impressions qui peuvent ne pas correspondre au ciblage spécifié, en raison d'informations insuffisantes sur les utilisateurs connectés.