--- v13/services/keyword_plan_service.proto 2023-04-26 19:21:31.000000000 +0000
+++ v14/services/keyword_plan_service.proto 2023-06-07 19:32:17.000000000 +0000
@@ -1,440 +1,134 @@
// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto3";
-package google.ads.googleads.v13.services;
+package google.ads.googleads.v14.services;
-import "google/ads/googleads/v13/common/keyword_plan_common.proto";
-import "google/ads/googleads/v13/resources/keyword_plan.proto";
+import "google/ads/googleads/v14/resources/keyword_plan.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/field_mask.proto";
import "google/rpc/status.proto";
-option csharp_namespace = "Google.Ads.GoogleAds.V13.Services";
-option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v13/services;services";
+option csharp_namespace = "Google.Ads.GoogleAds.V14.Services";
+option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v14/services;services";
option java_multiple_files = true;
option java_outer_classname = "KeywordPlanServiceProto";
-option java_package = "com.google.ads.googleads.v13.services";
+option java_package = "com.google.ads.googleads.v14.services";
option objc_class_prefix = "GAA";
-option php_namespace = "Google\\Ads\\GoogleAds\\V13\\Services";
-option ruby_package = "Google::Ads::GoogleAds::V13::Services";
+option php_namespace = "Google\\Ads\\GoogleAds\\V14\\Services";
+option ruby_package = "Google::Ads::GoogleAds::V14::Services";
// Proto file describing the keyword plan service.
// Service to manage keyword plans.
service KeywordPlanService {
option (google.api.default_host) = "googleads.googleapis.com";
option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/adwords";
// Creates, updates, or removes keyword plans. Operation statuses are
// returned.
//
// List of thrown errors:
// [AuthenticationError]()
// [AuthorizationError]()
// [DatabaseError]()
// [FieldError]()
// [HeaderError]()
// [InternalError]()
// [KeywordPlanError]()
// [MutateError]()
// [NewResourceCreationError]()
// [QuotaError]()
// [RequestError]()
// [ResourceCountLimitExceededError]()
// [StringLengthError]()
rpc MutateKeywordPlans(MutateKeywordPlansRequest)
returns (MutateKeywordPlansResponse) {
option (google.api.http) = {
- post: "/v13/customers/{customer_id=*}/keywordPlans:mutate"
+ post: "/v14/customers/{customer_id=*}/keywordPlans:mutate"
body: "*"
};
option (google.api.method_signature) = "customer_id,operations";
}
-
- // Returns the requested Keyword Plan forecast curve.
- // Only the bidding strategy is considered for generating forecast curve.
- // The bidding strategy value specified in the plan is ignored.
- //
- // To generate a forecast at a value specified in the plan, use
- // KeywordPlanService.GenerateForecastMetrics.
- //
- // List of thrown errors:
- // [AuthenticationError]()
- // [AuthorizationError]()
- // [HeaderError]()
- // [InternalError]()
- // [KeywordPlanError]()
- // [QuotaError]()
- // [RequestError]()
- rpc GenerateForecastCurve(GenerateForecastCurveRequest)
- returns (GenerateForecastCurveResponse) {
- option (google.api.http) = {
- post: "/v13/{keyword_plan=customers/*/keywordPlans/*}:generateForecastCurve"
- body: "*"
- };
- option (google.api.method_signature) = "keyword_plan";
- }
-
- // Returns a forecast in the form of a time series for the Keyword Plan over
- // the next 52 weeks.
- // (1) Forecasts closer to the current date are generally more accurate than
- // further out.
- //
- // (2) The forecast reflects seasonal trends using current and
- // prior traffic patterns. The forecast period of the plan is ignored.
- //
- // List of thrown errors:
- // [AuthenticationError]()
- // [AuthorizationError]()
- // [HeaderError]()
- // [InternalError]()
- // [KeywordPlanError]()
- // [QuotaError]()
- // [RequestError]()
- rpc GenerateForecastTimeSeries(GenerateForecastTimeSeriesRequest)
- returns (GenerateForecastTimeSeriesResponse) {
- option (google.api.http) = {
- post: "/v13/{keyword_plan=customers/*/keywordPlans/*}:generateForecastTimeSeries"
- body: "*"
- };
- option (google.api.method_signature) = "keyword_plan";
- }
-
- // Returns the requested Keyword Plan forecasts.
- //
- // List of thrown errors:
- // [AuthenticationError]()
- // [AuthorizationError]()
- // [HeaderError]()
- // [InternalError]()
- // [KeywordPlanError]()
- // [QuotaError]()
- // [RequestError]()
- rpc GenerateForecastMetrics(GenerateForecastMetricsRequest)
- returns (GenerateForecastMetricsResponse) {
- option (google.api.http) = {
- post: "/v13/{keyword_plan=customers/*/keywordPlans/*}:generateForecastMetrics"
- body: "*"
- };
- option (google.api.method_signature) = "keyword_plan";
- }
-
- // Returns the requested Keyword Plan historical metrics.
- //
- // List of thrown errors:
- // [AuthenticationError]()
- // [AuthorizationError]()
- // [HeaderError]()
- // [InternalError]()
- // [KeywordPlanError]()
- // [QuotaError]()
- // [RequestError]()
- rpc GenerateHistoricalMetrics(GenerateHistoricalMetricsRequest)
- returns (GenerateHistoricalMetricsResponse) {
- option (google.api.http) = {
- post: "/v13/{keyword_plan=customers/*/keywordPlans/*}:generateHistoricalMetrics"
- body: "*"
- };
- option (google.api.method_signature) = "keyword_plan";
- }
}
// Request message for
-// [KeywordPlanService.MutateKeywordPlans][google.ads.googleads.v13.services.KeywordPlanService.MutateKeywordPlans].
+// [KeywordPlanService.MutateKeywordPlans][google.ads.googleads.v14.services.KeywordPlanService.MutateKeywordPlans].
message MutateKeywordPlansRequest {
// Required. The ID of the customer whose keyword plans are being modified.
string customer_id = 1 [(google.api.field_behavior) = REQUIRED];
// Required. The list of operations to perform on individual keyword plans.
repeated KeywordPlanOperation operations = 2
[(google.api.field_behavior) = REQUIRED];
// If true, successful operations will be carried out and invalid
// operations will return errors. If false, all operations will be carried
// out in one transaction if and only if they are all valid.
// Default is false.
bool partial_failure = 3;
// If true, the request is validated but not executed. Only errors are
// returned, not results.
bool validate_only = 4;
}
// A single operation (create, update, remove) on a keyword plan.
message KeywordPlanOperation {
// The FieldMask that determines which resource fields are modified in an
// update.
google.protobuf.FieldMask update_mask = 4;
// The mutate operation.
oneof operation {
// Create operation: No resource name is expected for the new keyword plan.
- google.ads.googleads.v13.resources.KeywordPlan create = 1;
+ google.ads.googleads.v14.resources.KeywordPlan create = 1;
// Update operation: The keyword plan is expected to have a valid resource
// name.
- google.ads.googleads.v13.resources.KeywordPlan update = 2;
+ google.ads.googleads.v14.resources.KeywordPlan update = 2;
// Remove operation: A resource name for the removed keyword plan is
// expected in this format:
//
// `customers/{customer_id}/keywordPlans/{keyword_plan_id}`
string remove = 3 [(google.api.resource_reference) = {
type: "googleads.googleapis.com/KeywordPlan"
}];
}
}
// Response message for a keyword plan mutate.
message MutateKeywordPlansResponse {
// Errors that pertain to operation failures in the partial failure mode.
// Returned only when partial_failure = true and all errors occur inside the
// operations. If any errors occur outside the operations (for example, auth
// errors), we return an RPC level error.
google.rpc.Status partial_failure_error = 3;
// All results for the mutate.
repeated MutateKeywordPlansResult results = 2;
}
// The result for the keyword plan mutate.
message MutateKeywordPlansResult {
// Returned for successful operations.
string resource_name = 1 [(google.api.resource_reference) = {
type: "googleads.googleapis.com/KeywordPlan"
}];
}
-
-// Request message for
-// [KeywordPlanService.GenerateForecastCurve][google.ads.googleads.v13.services.KeywordPlanService.GenerateForecastCurve].
-message GenerateForecastCurveRequest {
- // Required. The resource name of the keyword plan to be forecasted.
- string keyword_plan = 1 [
- (google.api.field_behavior) = REQUIRED,
- (google.api.resource_reference) = {
- type: "googleads.googleapis.com/KeywordPlan"
- }
- ];
-}
-
-// Response message for
-// [KeywordPlanService.GenerateForecastCurve][google.ads.googleads.v13.services.KeywordPlanService.GenerateForecastCurve].
-message GenerateForecastCurveResponse {
- // List of forecast curves for the keyword plan campaign.
- // One maximum.
- repeated KeywordPlanCampaignForecastCurve campaign_forecast_curves = 1;
-}
-
-// Request message for
-// [KeywordPlanService.GenerateForecastTimeSeries][google.ads.googleads.v13.services.KeywordPlanService.GenerateForecastTimeSeries].
-message GenerateForecastTimeSeriesRequest {
- // Required. The resource name of the keyword plan to be forecasted.
- string keyword_plan = 1 [
- (google.api.field_behavior) = REQUIRED,
- (google.api.resource_reference) = {
- type: "googleads.googleapis.com/KeywordPlan"
- }
- ];
-}
-
-// Response message for
-// [KeywordPlanService.GenerateForecastTimeSeries][google.ads.googleads.v13.services.KeywordPlanService.GenerateForecastTimeSeries].
-message GenerateForecastTimeSeriesResponse {
- // List of weekly time series forecasts for the keyword plan campaign.
- // One maximum.
- repeated KeywordPlanWeeklyTimeSeriesForecast weekly_time_series_forecasts = 1;
-}
-
-// Request message for
-// [KeywordPlanService.GenerateForecastMetrics][google.ads.googleads.v13.services.KeywordPlanService.GenerateForecastMetrics].
-message GenerateForecastMetricsRequest {
- // Required. The resource name of the keyword plan to be forecasted.
- string keyword_plan = 1 [
- (google.api.field_behavior) = REQUIRED,
- (google.api.resource_reference) = {
- type: "googleads.googleapis.com/KeywordPlan"
- }
- ];
-}
-
-// Response message for
-// [KeywordPlanService.GenerateForecastMetrics][google.ads.googleads.v13.services.KeywordPlanService.GenerateForecastMetrics].
-message GenerateForecastMetricsResponse {
- // List of campaign forecasts.
- // One maximum.
- repeated KeywordPlanCampaignForecast campaign_forecasts = 1;
-
- // List of ad group forecasts.
- repeated KeywordPlanAdGroupForecast ad_group_forecasts = 2;
-
- // List of keyword forecasts.
- repeated KeywordPlanKeywordForecast keyword_forecasts = 3;
-}
-
-// A campaign forecast.
-message KeywordPlanCampaignForecast {
- // The resource name of the Keyword Plan campaign related to the forecast.
- //
- // `customers/{customer_id}/keywordPlanCampaigns/{keyword_plan_campaign_id}`
- optional string keyword_plan_campaign = 3;
-
- // The forecast for the Keyword Plan campaign.
- ForecastMetrics campaign_forecast = 2;
-}
-
-// An ad group forecast.
-message KeywordPlanAdGroupForecast {
- // The resource name of the Keyword Plan ad group related to the forecast.
- //
- // `customers/{customer_id}/keywordPlanAdGroups/{keyword_plan_ad_group_id}`
- optional string keyword_plan_ad_group = 3;
-
- // The forecast for the Keyword Plan ad group.
- ForecastMetrics ad_group_forecast = 2;
-}
-
-// A keyword forecast.
-message KeywordPlanKeywordForecast {
- // The resource name of the Keyword Plan keyword related to the forecast.
- //
- // `customers/{customer_id}/keywordPlanAdGroupKeywords/{keyword_plan_ad_group_keyword_id}`
- optional string keyword_plan_ad_group_keyword = 3;
-
- // The forecast for the Keyword Plan keyword.
- ForecastMetrics keyword_forecast = 2;
-}
-
-// The forecast curve for the campaign.
-message KeywordPlanCampaignForecastCurve {
- // The resource name of the Keyword Plan campaign related to the forecast.
- //
- // `customers/{customer_id}/keywordPlanCampaigns/{keyword_plan_campaign_id}`
- optional string keyword_plan_campaign = 3;
-
- // The max cpc bid forecast curve for the campaign.
- KeywordPlanMaxCpcBidForecastCurve max_cpc_bid_forecast_curve = 2;
-}
-
-// The max cpc bid forecast curve.
-message KeywordPlanMaxCpcBidForecastCurve {
- // The forecasts for the Keyword Plan campaign at different max CPC bids.
- repeated KeywordPlanMaxCpcBidForecast max_cpc_bid_forecasts = 1;
-}
-
-// The forecast of the campaign at a specific bid.
-message KeywordPlanMaxCpcBidForecast {
- // The max cpc bid in micros.
- optional int64 max_cpc_bid_micros = 3;
-
- // The forecast for the Keyword Plan campaign at the specific bid.
- ForecastMetrics max_cpc_bid_forecast = 2;
-}
-
-// The weekly time series forecast for the keyword plan campaign.
-message KeywordPlanWeeklyTimeSeriesForecast {
- // The resource name of the Keyword Plan campaign related to the forecast.
- //
- // `customers/{customer_id}/keywordPlanCampaigns/{keyword_plan_campaign_id}`
- optional string keyword_plan_campaign = 1;
-
- // The forecasts for the Keyword Plan campaign at different max CPC bids.
- repeated KeywordPlanWeeklyForecast weekly_forecasts = 2;
-}
-
-// The forecast of the campaign for the week starting start_date.
-message KeywordPlanWeeklyForecast {
- // The start date, in yyyy-mm-dd format. This date is inclusive.
- optional string start_date = 1;
-
- // The forecast for the Keyword Plan campaign for the week.
- ForecastMetrics forecast = 2;
-}
-
-// Forecast metrics.
-message ForecastMetrics {
- // Impressions
- optional double impressions = 7;
-
- // Ctr
- optional double ctr = 8;
-
- // AVG cpc
- optional int64 average_cpc = 9;
-
- // Clicks
- optional double clicks = 10;
-
- // Cost
- optional int64 cost_micros = 11;
-}
-
-// Request message for
-// [KeywordPlanService.GenerateHistoricalMetrics][google.ads.googleads.v13.services.KeywordPlanService.GenerateHistoricalMetrics].
-message GenerateHistoricalMetricsRequest {
- // Required. The resource name of the keyword plan of which historical metrics
- // are requested.
- string keyword_plan = 1 [
- (google.api.field_behavior) = REQUIRED,
- (google.api.resource_reference) = {
- type: "googleads.googleapis.com/KeywordPlan"
- }
- ];
-
- // The aggregate fields to include in response.
- google.ads.googleads.v13.common.KeywordPlanAggregateMetrics
- aggregate_metrics = 2;
-
- // The options for historical metrics data.
- google.ads.googleads.v13.common.HistoricalMetricsOptions
- historical_metrics_options = 3;
-}
-
-// Response message for
-// [KeywordPlanService.GenerateHistoricalMetrics][google.ads.googleads.v13.services.KeywordPlanService.GenerateHistoricalMetrics].
-message GenerateHistoricalMetricsResponse {
- // List of keyword historical metrics.
- repeated KeywordPlanKeywordHistoricalMetrics metrics = 1;
-
- // The aggregate metrics for all the keywords in the keyword planner plan.
- google.ads.googleads.v13.common.KeywordPlanAggregateMetricResults
- aggregate_metric_results = 2;
-}
-
-// A keyword historical metrics.
-message KeywordPlanKeywordHistoricalMetrics {
- // The text of the query associated with one or more ad_group_keywords in the
- // plan.
- //
- // Note that we de-dupe your keywords list, eliminating close variants before
- // returning the plan's keywords as text. For example, if your plan originally
- // contained the keywords 'car' and 'cars', the returned search query will
- // only contain 'cars'.
- // Starting V5, the list of de-duped queries will be included in
- // close_variants field.
- optional string search_query = 4;
-
- // The list of close variant queries for search_query whose search results
- // are combined into the search_query.
- repeated string close_variants = 3;
-
- // The historical metrics for the query associated with one or more
- // ad_group_keywords in the plan.
- google.ads.googleads.v13.common.KeywordPlanHistoricalMetrics keyword_metrics =
- 2;
-}
