--- v13/services/keyword_plan_idea_service.proto 2023-06-07 19:38:57.000000000 +0000
+++ v14/services/keyword_plan_idea_service.proto 2023-06-07 19:39:02.000000000 +0000
@@ -91,7 +93,26 @@
rpc GenerateAdGroupThemes(GenerateAdGroupThemesRequest)
returns (GenerateAdGroupThemesResponse) {
option (google.api.http) = {
- post: "/v13/customers/{customer_id=*}:generateAdGroupThemes"
+ post: "/v14/customers/{customer_id=*}:generateAdGroupThemes"
+ body: "*"
+ };
+ }
+
+ // 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]()
+ rpc GenerateKeywordForecastMetrics(GenerateKeywordForecastMetricsRequest)
+ returns (GenerateKeywordForecastMetricsResponse) {
+ option (google.api.http) = {
+ post: "/v14/customers/{customer_id=*}:generateKeywordForecastMetrics"
body: "*"
};
}
@@ -368,3 +389,178 @@
// Resource name format: `customers/{customer_id}/campaigns/{campaign_id}`
string campaign = 2;
}
+
+// Request message for [KeywordPlanIdeaService.GenerateKeywordForecastMetrics].
+message GenerateKeywordForecastMetricsRequest {
+ // The ID of the customer.
+ string customer_id = 1;
+
+ // 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.
+ optional string currency_code = 2;
+
+ // 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.
+ google.ads.googleads.v14.common.DateRange forecast_period = 3;
+
+ // Required. The campaign used in the forecast.
+ CampaignToForecast campaign = 4 [(google.api.field_behavior) = REQUIRED];
+}
+
+// A campaign to do a keyword campaign forecast.
+message CampaignToForecast {
+ // Supported bidding strategies for new campaign forecasts.
+ message CampaignBiddingStrategy {
+ // Bidding strategies.
+ oneof bidding_strategy {
+ // Use manual CPC bidding strategy for forecasting.
+ ManualCpcBiddingStrategy manual_cpc_bidding_strategy = 1;
+
+ // Use maximize clicks bidding strategy for forecasting.
+ MaximizeClicksBiddingStrategy maximize_clicks_bidding_strategy = 2;
+
+ // Use maximize conversions bidding strategy for forecasting.
+ MaximizeConversionsBiddingStrategy maximize_conversions_bidding_strategy =
+ 3;
+ }
+ }
+
+ // The list of resource names of languages to be targeted. The resource name
+ // is of the format "languageConstants/{criterion_id}". See
+ // https://developers.google.com/google-ads/api/data/codes-formats#languages
+ // for the list of language criterion codes.
+ repeated string language_constants = 1;
+
+ // Locations to be targeted. Locations must be unique.
+ repeated CriterionBidModifier geo_modifiers = 2;
+
+ // Required. The network used for targeting.
+ google.ads.googleads.v14.enums.KeywordPlanNetworkEnum.KeywordPlanNetwork
+ keyword_plan_network = 3 [(google.api.field_behavior) = REQUIRED];
+
+ // The list of negative keywords to be used in the campaign when doing the
+ // forecast.
+ repeated google.ads.googleads.v14.common.KeywordInfo negative_keywords = 4;
+
+ // Required. The bidding strategy for the campaign.
+ CampaignBiddingStrategy bidding_strategy = 5
+ [(google.api.field_behavior) = REQUIRED];
+
+ // 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.
+ optional double conversion_rate = 6;
+
+ // The ad groups in the new campaign to forecast.
+ repeated ForecastAdGroup ad_groups = 7;
+}
+
+// An ad group that is part of a campaign to be forecasted.
+message ForecastAdGroup {
+ // 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.
+ optional int64 max_cpc_bid_micros = 1;
+
+ // Required. The list of biddable keywords to be used in the ad group when
+ // doing the forecast. Requires at least one keyword.
+ repeated BiddableKeyword biddable_keywords = 2
+ [(google.api.field_behavior) = REQUIRED];
+
+ // The details of the keyword. You should specify both the keyword text and
+ // match type.
+ repeated google.ads.googleads.v14.common.KeywordInfo negative_keywords = 3;
+}
+
+// A biddable keyword part of an ad group.
+message BiddableKeyword {
+ // Required. Keyword. Must have text and match type.
+ google.ads.googleads.v14.common.KeywordInfo keyword = 1
+ [(google.api.field_behavior) = REQUIRED];
+
+ // 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.
+ optional int64 max_cpc_bid_micros = 2;
+}
+
+// Location Criterion bid modifier.
+message CriterionBidModifier {
+ // The resource name of the geo location to target. The resource name is of
+ // the format "geoTargetConstants/{criterion_id}".
+ string geo_target_constant = 1;
+
+ // The associated multiplier for the criterion_id. If set, this value cannot
+ // be 0.
+ optional double bid_modifier = 2;
+}
+
+// Manual CPC Bidding Strategy.
+message ManualCpcBiddingStrategy {
+ // 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.
+ optional int64 daily_budget_micros = 1;
+
+ // Required. A bid in micros to be applied to ad groups within the campaign
+ // for a manual CPC bidding strategy.
+ int64 max_cpc_bid_micros = 2 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Maximize Clicks Bidding Strategy.
+message MaximizeClicksBiddingStrategy {
+ // 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.
+ int64 daily_target_spend_micros = 1 [(google.api.field_behavior) = REQUIRED];
+
+ // Ceiling on max CPC bids in micros.
+ optional int64 max_cpc_bid_ceiling_micros = 2;
+}
+
+// Maximize Conversions Bidding Strategy.
+message MaximizeConversionsBiddingStrategy {
+ // Required. The daily target spend in micros to be used for estimation. This
+ // value must be greater than zero.
+ int64 daily_target_spend_micros = 1 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Response message for [KeywordPlanIdeaService.GenerateKeywordForecastMetrics].
+message GenerateKeywordForecastMetricsResponse {
+ // Results of the campaign forecast.
+ optional KeywordForecastMetrics campaign_forecast_metrics = 1;
+}
+
+// The forecast metrics for the planless keyword campaign.
+message KeywordForecastMetrics {
+ // The total number of impressions.
+ optional double impressions = 1;
+
+ // The average click through rate. Available only if impressions > 0.
+ optional double click_through_rate = 2;
+
+ // The average cpc. Available only if clicks > 0.
+ optional int64 average_cpc_micros = 3;
+
+ // The total number of clicks.
+ optional double clicks = 4;
+
+ // The total cost.
+ optional int64 cost_micros = 5;
+
+ // Forecasted number of conversions: clicks * conversion_rate.
+ optional double conversions = 6;
+
+ // Forecasted conversion rate.
+ optional double conversion_rate = 7;
+
+ // Average cost per acquisition calculated as cost_micros / conversions.
+ optional int64 average_cpa_micros = 8;
+}
