--- 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; +}
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2023-06-07 (حسب التوقيت العالمي المتفَّق عليه)
[]
[]