Method: customers.generateReachForecast

Génère une prévision de couverture pour un ciblage / un mix 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/v17/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)

Limite de la fréquence d'exposition des cookies choisie à appliquer à chaque produit planifié. Équivaut à la limite de la fréquence d'exposition indiquée dans Google Ads lors de la création d'une campagne. Elle représente le nombre maximal de fois qu'une annonce peut être diffusée auprès du même utilisateur au cours d'un intervalle de temps spécifié. Si aucune valeur n'est spécifiée, la valeur par défaut 0 (aucun plafond) est appliquée.

Ce champ remplace le champ cookieFrequencyCap, qui est obsolète.
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 en fonction du produit publicitaire. Consultez un spécialiste de la mise en œuvre.

Consultez des métriques spécifiques pour en savoir plus sur la manière dont le ciblage les affecte.
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

Limite de la fréquence d'exposition des cookies choisie à appliquer à chaque produit planifié. Équivaut à la limite de la fréquence d'exposition indiquée dans Google Ads lors de la création d'une campagne. Elle correspond au nombre maximal de fois qu'une annonce peut être diffusée auprès d'un même utilisateur. S'il n'est pas spécifié, aucune limite n'est appliquée.

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

integer

Fréquence effective minimale choisie (nombre de fois qu'une personne a été exposée à l'annonce) pour les métriques de couverture enregistrées [1-10]. Cela n'aura aucune 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 associé au champ effectiveFrequencyLimit.
effectiveFrequencyLimit

object (EffectiveFrequencyLimit)

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

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

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

string

Nom du client prévu. 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)

Période de la campagne. Les dates sont au format "aaaa-mm-jj" et sont incluses. La date de fin doit être < Un an dans le futur, et la période doit être inférieure ou égale à 92 jours.

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

integer

Valeur de la 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 accepte les fréquences comprises entre 1 et 10 inclus.

Ciblage

Ciblage pour lequel les métriques de trafic seront enregistrées.

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 ciblées à cibler avec cette prévision.

Si plusieurs ID sont fournis, ils doivent tous avoir le même parentCountryId. Vous ne pouvez pas planifier plus de parent_county plans. Vous pouvez obtenir l'ID des zones géographiques planifiables et leur parentCountryId auprès de ReachPlanService.ListPlannableLocations.

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

enum (ReachPlanAgeRange)

Tranche d'âge ciblée. Si cette valeur n'est pas définie, cela équivaut à cibler toutes les tranches d'âge.
genders[]

object (GenderInfo)

Genres ciblés. Si cette valeur n'est pas définie, cela équivaut à cibler "MALE" et "FEMALE".
devices[]

object (DeviceInfo)

Appareils ciblés. S'il n'est pas spécifié, cible tous les appareils concernés. Les appareils concernés varient selon les produits et les régions. Vous pouvez vous les procurer auprès de ReachPlanService.ListPlannableProducts.
network

enum (ReachPlanNetwork)

Réseau pouvant être ciblé pour le produit publicitaire. S'il n'est pas spécifié, 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. S'il n'est pas spécifié, il ne cible aucune audience spécifique.
plannableLocationId

string

ID de la zone géographique sélectionnée. Les ID d'emplacement planifiable peuvent être obtenus auprès 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 d'audiences à cibler en fonction des centres d'intérêt des utilisateurs.

PlannedProduct

Un produit dont la couverture est prévue.

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 les critères de ciblage disponibles pour chaque produit, utilisez ReachPlanService.ListPlannableProducts.
plannableProductCode

string

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

string (int64 format)

Obligatoire. Répartition du budget maximale en micro-unités pour le produit sélectionné. La valeur est spécifiée dans le code de planification (currencyCode) sélectionné. Exemple: 1 000 000$ = 1 000 000 000 000 micros.

AdvancedProductTargeting

Paramètres de ciblage avancés des produits.

Représentation JSON 
{
  "surfaceTargetingSettings": {
    object (SurfaceTargeting)
  },
  "targetFrequencySettings": {
    object (TargetFrequencySettings)
  },

  // 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
surfaceTargetingSettings

object (SurfaceTargeting)

Paramètres de ciblage de la surface pour ce produit.
targetFrequencySettings

object (TargetFrequencySettings)

Paramètres d'une campagne avec fréquence cible. Doit être défini lors de la sélection du produit TARGET_FREQUENCY.

Pour en savoir plus sur les campagnes avec fréquence cible, consultez la page https://support.google.com/google-ads/answer/12400225.
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.

TargetFrequencySettings

Paramètres de fréquence cible pour un produit compatible.

Représentation JSON 
{
  "timeUnit": enum (TargetFrequencyTimeUnit),
  "targetFrequency": integer
}
Champs
timeUnit

enum (TargetFrequencyTimeUnit)

Obligatoire. Unité de temps utilisée pour décrire la période de targetFrequency.
targetFrequency

integer

Obligatoire. Objectif de fréquence cible par unité de temps sélectionnée.

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 s'il faut inclure les métriques de covisionnage dans la prévision de réponse.

OnTargetAudienceMetrics

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

  • Lieu
  • PlannableAgeRange
  • Sexe
  • AudienceCiblage (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 pris en compte pour YouTube.
censusAudienceSize

string (int64 format)

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

ReachCurve

Courbe de couverture des produits planifiés.

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

object (ReachForecast)

Tous les points sur la courbe de couverture.

ReachForecast

Point sur la courbe d'audience.

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

string (int64 format)

Coût en micros.
forecast

object (Forecast)

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

object (PlannedProductReachForecast)

Répartition prévue et métriques de trafic pour chaque produit planifié à ce stade de la courbe de couverture.

Prévision

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

Représentation JSON 
{
  "effectiveFrequencyBreakdowns": [
    {
      object (EffectiveFrequencyBreakdown)
    }
  ],
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string,
  "views": 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 par GenerateReachPredictRequest.effective_frequency_limit fois, ceux-ci correspondent exactement au ciblage.

Notez qu'un nombre minimal de personnes uniques doit être atteint pour que les données soient incluses dans les rapports. 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 par GenerateReachForecastRequest.effective_frequency_limit fois. Cela inclut les personnes qui ne correspondent peut-être pas au ciblage spécifié.

Notez qu'un nombre minimal de personnes uniques doit être atteint pour que les données soient incluses dans les rapports. Si le nombre minimal n'est pas atteint, la valeur "totalReach" est arrondie à 0.
onTargetImpressions

string (int64 format)

Nombre d'impressions d'annonces correspondant exactement au ciblage.
totalImpressions

string (int64 format)

Nombre total d'impressions d'annonces. Cela inclut les impressions qui ne correspondent peut-être pas 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. Pour en savoir plus sur la visibilité d'une annonce et sur la façon dont la visibilité est mesurée, consultez la page https://support.google.com/google-ads/answer/7029393.
onTargetCoviewReach

string (int64 format)

Nombre d'utilisateurs uniques touchés qui correspondent 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 personnes qui ne correspondent peut-être pas au 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 ne correspondent peut-être pas au ciblage spécifié, en raison d'informations insuffisantes sur les utilisateurs connectés.
views

string (int64 format)

Nombre de visionnages d'annonces prévus pour le produit et le ciblage spécifiés. Une vue est comptabilisée lorsqu'un internaute visionne la majeure partie ou l'intégralité de l'annonce au-delà de l'impression.

Pour en savoir plus sur les vues, consultez la page https://support.google.com/google-ads/answer/2375431.

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 de personnes uniques touchées au moins à une fréquence qui correspond exactement au ciblage.

Notez qu'un nombre minimal de personnes uniques doit être atteint pour que les données soient incluses dans les rapports. 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 souvent. Cela inclut les personnes qui ne correspondent peut-être pas au ciblage spécifié.

Notez qu'un nombre minimal de personnes uniques doit être atteint pour que les données soient incluses dans les rapports. Si le nombre minimal n'est pas atteint, la valeur "totalReach" est arrondie à 0.
effectiveCoviewReach

string (int64 format)

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

string (int64 format)

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

PlannedProductReachForecast

Les métriques de trafic et de répartition prévues pour un produit spécifique à un point donné de la courbe de couverture.

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

string

Produit sélectionné pour la planification. Lorsque vous utilisez le même identifiant de zone géographique, les codes produit renvoyés font partie de l'ensemble de codes renvoyés par ListPlannableProducts.
costMicros

string (int64 format)

Coût en micros. Cette répartition peut différer de l'allocation d'entrée du produit si un ou plusieurs produits planifiés ne peuvent pas utiliser 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,
  "averageFrequency": number,
  "views": string
}
Champs
onTargetReach

string (int64 format)

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

Notez qu'un nombre minimal de personnes uniques doit être atteint pour que les données soient incluses dans les rapports. 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 personnes qui ne correspondent peut-être pas au ciblage spécifié.

Notez qu'un nombre minimal de personnes uniques doit être atteint pour que les données soient incluses dans les rapports. Si le nombre minimal n'est pas atteint, la valeur "totalReach" est arrondie à 0.
onTargetImpressions

string (int64 format)

Nombre d'impressions d'annonces correspondant exactement au ciblage.
totalImpressions

string (int64 format)

Nombre total d'impressions d'annonces. Cela inclut les impressions qui ne correspondent peut-être pas 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. Pour en savoir plus sur la visibilité d'une annonce et sur la façon dont la visibilité est mesurée, consultez la page https://support.google.com/google-ads/answer/7029393.
onTargetCoviewReach

string (int64 format)

Nombre d'utilisateurs uniques touchés qui correspondent 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 personnes qui ne correspondent peut-être pas au 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 ne correspondent peut-être pas au ciblage spécifié, en raison d'informations insuffisantes sur les utilisateurs connectés.
averageFrequency

number

Nombre de fois qu'un utilisateur verra une annonce par unité de temps sélectionnée, moyenne calculée en fonction du nombre d'unités de temps pour la durée prévue. Ce champ ne sera renseigné que pour une campagne avec fréquence cible.

Pour en savoir plus sur les campagnes avec fréquence cible, consultez la page https://support.google.com/google-ads/answer/12400225.
views

string (int64 format)

Nombre de visionnages d'annonces prévus pour le produit et le ciblage spécifiés. Une vue est comptabilisée lorsqu'un internaute visionne la majeure partie ou l'intégralité de l'annonce au-delà de l'impression.

Pour en savoir plus sur les vues, consultez la page https://support.google.com/google-ads/answer/2375431.