Method: customers.generateKeywordForecastMetrics

Returns metrics (such as impressions, clicks, total cost) of a keyword forecast for the given campaign.

List of thrown errors: AuthenticationError AuthorizationError CollectionSizeError HeaderError InternalError QuotaError RequestError

HTTP request

POST https://googleads.googleapis.com/v16/customers/{customerId}:generateKeywordForecastMetrics

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
customerId

string

The ID of the customer.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "forecastPeriod": {
    object (DateRange)
  },
  "campaign": {
    object (CampaignToForecast)
  },
  "currencyCode": string
}
Fields
forecastPeriod

object (DateRange)

The date range for the forecast. The start date must be in the future and end date must be within 1 year from today. The reference timezone used is the one of the Google Ads account belonging to the customer. If not set, a default date range from next Sunday to the following Saturday will be used.
campaign

object (CampaignToForecast)

Required. The campaign used in the forecast.
currencyCode

string

The currency used for exchange rate conversion. By default, the account currency of the customer is used. Set this field only if the currency is different from the account currency. The list of valid currency codes can be found at https://developers.google.com/google-ads/api/data/codes-formats#currency-codes.

Response body

Response message for [KeywordPlanIdeaService.GenerateKeywordForecastMetrics].

If successful, the response body contains data with the following structure:

JSON representation 
{
  "campaignForecastMetrics": {
    object (KeywordForecastMetrics)
  }
}
Fields
campaignForecastMetrics

object (KeywordForecastMetrics)

Results of the campaign forecast.

Authorization scopes

Requires the following OAuth scope:

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

For more information, see the OAuth 2.0 Overview.

CampaignToForecast

A campaign to do a keyword campaign forecast.

JSON representation 
{
  "languageConstants": [
    string
  ],
  "geoModifiers": [
    {
      object (CriterionBidModifier)
    }
  ],
  "keywordPlanNetwork": enum (KeywordPlanNetwork),
  "negativeKeywords": [
    {
      object (KeywordInfo)
    }
  ],
  "biddingStrategy": {
    object (CampaignBiddingStrategy)
  },
  "adGroups": [
    {
      object (ForecastAdGroup)
    }
  ],
  "conversionRate": number
}
Fields
languageConstants[]

string

The list of resource names of languages to be targeted. The resource name is of the format "languageConstants/{criterionId}". See https://developers.google.com/google-ads/api/data/codes-formats#languages for the list of language criterion codes.
geoModifiers[]

object (CriterionBidModifier)

Locations to be targeted. Locations must be unique.
keywordPlanNetwork

enum (KeywordPlanNetwork)

Required. The network used for targeting.
negativeKeywords[]

object (KeywordInfo)

The list of negative keywords to be used in the campaign when doing the forecast.
biddingStrategy

object (CampaignBiddingStrategy)

Required. The bidding strategy for the campaign.
adGroups[]

object (ForecastAdGroup)

The ad groups in the new campaign to forecast.
conversionRate

number

The expected conversion rate (number of conversions divided by number of total clicks) as defined by the user. This value is expressed as a decimal value, so an expected conversion rate of 2% should be entered as 0.02. If left empty, an estimated conversion rate will be used.

CriterionBidModifier

Location Criterion bid modifier.

JSON representation 
{
  "geoTargetConstant": string,
  "bidModifier": number
}
Fields
geoTargetConstant

string

The resource name of the geo location to target. The resource name is of the format "geoTargetConstants/{criterionId}".
bidModifier

number

The associated multiplier for the criterionId. If set, this value cannot be 0.

CampaignBiddingStrategy

Supported bidding strategies for new campaign forecasts.

JSON representation 
{

  // Union field bidding_strategy can be only one of the following:
  "manualCpcBiddingStrategy": {
    object (ManualCpcBiddingStrategy)
  },
  "maximizeClicksBiddingStrategy": {
    object (MaximizeClicksBiddingStrategy)
  },
  "maximizeConversionsBiddingStrategy": {
    object (MaximizeConversionsBiddingStrategy)
  }
  // End of list of possible types for union field bidding_strategy.
}
Fields
Union field bidding_strategy. Bidding strategies. bidding_strategy can be only one of the following:
manualCpcBiddingStrategy

object (ManualCpcBiddingStrategy)

Use manual CPC bidding strategy for forecasting.
maximizeClicksBiddingStrategy

object (MaximizeClicksBiddingStrategy)

Use maximize clicks bidding strategy for forecasting.
maximizeConversionsBiddingStrategy

object (MaximizeConversionsBiddingStrategy)

Use maximize conversions bidding strategy for forecasting.

ManualCpcBiddingStrategy

Manual CPC Bidding Strategy.

JSON representation 
{
  "maxCpcBidMicros": string,
  "dailyBudgetMicros": string
}
Fields
maxCpcBidMicros

string (int64 format)

Required. A bid in micros to be applied to ad groups within the campaign for a manual CPC bidding strategy.
dailyBudgetMicros

string (int64 format)

Campaign level budget in micros. If set, a minimum value is enforced for the local currency used in the campaign. An error will occur showing the minimum value if this field is set too low.

MaximizeClicksBiddingStrategy

Maximize Clicks Bidding Strategy.

JSON representation 
{
  "dailyTargetSpendMicros": string,
  "maxCpcBidCeilingMicros": string
}
Fields
dailyTargetSpendMicros

string (int64 format)

Required. The daily target spend in micros to be used for estimation. A minimum value is enforced for the local currency used in the campaign. An error will occur showing the minimum value if this field is set too low.
maxCpcBidCeilingMicros

string (int64 format)

Ceiling on max CPC bids in micros.

MaximizeConversionsBiddingStrategy

Maximize Conversions Bidding Strategy.

JSON representation 
{
  "dailyTargetSpendMicros": string
}
Fields
dailyTargetSpendMicros

string (int64 format)

Required. The daily target spend in micros to be used for estimation. This value must be greater than zero.

ForecastAdGroup

An ad group that is part of a campaign to be forecasted.

JSON representation 
{
  "biddableKeywords": [
    {
      object (BiddableKeyword)
    }
  ],
  "negativeKeywords": [
    {
      object (KeywordInfo)
    }
  ],
  "maxCpcBidMicros": string
}
Fields
biddableKeywords[]

object (BiddableKeyword)

Required. The list of biddable keywords to be used in the ad group when doing the forecast. Requires at least one keyword.
negativeKeywords[]

object (KeywordInfo)

The details of the keyword. You should specify both the keyword text and match type.
maxCpcBidMicros

string (int64 format)

The max cpc to use for the ad group when generating forecasted traffic. This value will override the max cpc value set in the bidding strategy. Only specify this field for bidding strategies that max cpc values.

BiddableKeyword

A biddable keyword part of an ad group.

JSON representation 
{
  "keyword": {
    object (KeywordInfo)
  },
  "maxCpcBidMicros": string
}
Fields
keyword

object (KeywordInfo)

Required. Keyword. Must have text and match type.
maxCpcBidMicros

string (int64 format)

A max cpc bid in micros that overrides the ad group level max cpc bid in forecast simulation. This value will override the max cpc value set in the bidding strategy and ad group. Only specify this field for bidding strategies that support max cpc values.

KeywordForecastMetrics

The forecast metrics for the planless keyword campaign.

JSON representation 
{
  "impressions": number,
  "clickThroughRate": number,
  "averageCpcMicros": string,
  "clicks": number,
  "costMicros": string,
  "conversions": number,
  "conversionRate": number,
  "averageCpaMicros": string
}
Fields
impressions

number

The total number of impressions.
clickThroughRate

number

The average click through rate. Available only if impressions > 0.
averageCpcMicros

string (int64 format)

The average cpc. Available only if clicks > 0.
clicks

number

The total number of clicks.
costMicros

string (int64 format)

The total cost.
conversions

number

Forecasted number of conversions: clicks * conversionRate.
conversionRate

number

Forecasted conversion rate.
averageCpaMicros

string (int64 format)

Average cost per acquisition calculated as costMicros / conversions.