kpt-grpc-demo/google/ads/googleads/v12/services/keyword_plan_idea_service.proto

// Copyright 2022 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.v12.services;

import "google/ads/googleads/v12/common/keyword_plan_common.proto";
import "google/ads/googleads/v12/enums/keyword_match_type.proto";
import "google/ads/googleads/v12/enums/keyword_plan_keyword_annotation.proto";
import "google/ads/googleads/v12/enums/keyword_plan_network.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";

option csharp_namespace = "Google.Ads.GoogleAds.V12.Services";
option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v12/services;services";
option java_multiple_files = true;
option java_outer_classname = "KeywordPlanIdeaServiceProto";
option java_package = "com.google.ads.googleads.v12.services";
option objc_class_prefix = "GAA";
option php_namespace = "Google\\Ads\\GoogleAds\\V12\\Services";
option ruby_package = "Google::Ads::GoogleAds::V12::Services";

// Proto file describing the keyword plan idea service.

// Service to generate keyword ideas.
service KeywordPlanIdeaService {
  option (google.api.default_host) = "googleads.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/adwords";

  // Returns a list of keyword ideas.
  //
  // List of thrown errors:
  //   [AuthenticationError]()
  //   [AuthorizationError]()
  //   [CollectionSizeError]()
  //   [HeaderError]()
  //   [InternalError]()
  //   [KeywordPlanIdeaError]()
  //   [QuotaError]()
  //   [RequestError]()
  rpc GenerateKeywordIdeas(GenerateKeywordIdeasRequest) returns (GenerateKeywordIdeaResponse) {
    option (google.api.http) = {
      post: "/v12/customers/{customer_id=*}:generateKeywordIdeas"
      body: "*"
    };
  }

  // Returns a list of keyword historical metrics.
  //
  // List of thrown errors:
  //   [AuthenticationError]()
  //   [AuthorizationError]()
  //   [CollectionSizeError]()
  //   [HeaderError]()
  //   [InternalError]()
  //   [QuotaError]()
  //   [RequestError]()
  rpc GenerateKeywordHistoricalMetrics(GenerateKeywordHistoricalMetricsRequest) returns (GenerateKeywordHistoricalMetricsResponse) {
    option (google.api.http) = {
      post: "/v12/customers/{customer_id=*}:generateKeywordHistoricalMetrics"
      body: "*"
    };
  }

  // Returns a list of suggested AdGroups and suggested modifications
  // (text, match type) for the given keywords.
  //
  // List of thrown errors:
  //   [AuthenticationError]()
  //   [AuthorizationError]()
  //   [CollectionSizeError]()
  //   [HeaderError]()
  //   [InternalError]()
  //   [QuotaError]()
  //   [RequestError]()
  rpc GenerateAdGroupThemes(GenerateAdGroupThemesRequest) returns (GenerateAdGroupThemesResponse) {
    option (google.api.http) = {
      post: "/v12/customers/{customer_id=*}:generateAdGroupThemes"
      body: "*"
    };
  }
}

// Request message for [KeywordPlanIdeaService.GenerateKeywordIdeas][google.ads.googleads.v12.services.KeywordPlanIdeaService.GenerateKeywordIdeas].
message GenerateKeywordIdeasRequest {
  // The ID of the customer with the recommendation.
  string customer_id = 1;

  // The resource name of the language to target.
  // Each keyword belongs to some set of languages; a keyword is included if
  // language is one of its languages.
  // If not set, all keywords will be included.
  optional string language = 14;

  // The resource names of the location to target. Maximum is 10.
  // An empty list MAY be used to specify all targeting geos.
  repeated string geo_target_constants = 15;

  // If true, adult keywords will be included in response.
  // The default value is false.
  bool include_adult_keywords = 10;

  // Token of the page to retrieve. If not specified, the first
  // page of results will be returned. To request next page of results use the
  // value obtained from `next_page_token` in the previous response.
  // The request fields must match across pages.
  string page_token = 12;

  // Number of results to retrieve in a single page.
  // A maximum of 10,000 results may be returned, if the page_size
  // exceeds this, it is ignored.
  // If unspecified, at most 10,000 results will be returned.
  // The server may decide to further limit the number of returned resources.
  // If the response contains fewer than 10,000 results it may not be assumed
  // as last page of results.
  int32 page_size = 13;

  // Targeting network.
  // If not set, Google Search And Partners Network will be used.
  google.ads.googleads.v12.enums.KeywordPlanNetworkEnum.KeywordPlanNetwork keyword_plan_network = 9;

  // The keyword annotations to include in response.
  repeated google.ads.googleads.v12.enums.KeywordPlanKeywordAnnotationEnum.KeywordPlanKeywordAnnotation keyword_annotation = 17;

  // The aggregate fields to include in response.
  google.ads.googleads.v12.common.KeywordPlanAggregateMetrics aggregate_metrics = 16;

  // The options for historical metrics data.
  google.ads.googleads.v12.common.HistoricalMetricsOptions historical_metrics_options = 18;

  // The type of seed to generate keyword ideas.
  oneof seed {
    // A Keyword and a specific Url to generate ideas from
    // for example, cars, www.example.com/cars.
    KeywordAndUrlSeed keyword_and_url_seed = 2;

    // A Keyword or phrase to generate ideas from, for example, cars.
    KeywordSeed keyword_seed = 3;

    // A specific url to generate ideas from, for example, www.example.com/cars.
    UrlSeed url_seed = 5;

    // The site to generate ideas from, for example, www.example.com.
    SiteSeed site_seed = 11;
  }
}

// Keyword And Url Seed
message KeywordAndUrlSeed {
  // The URL to crawl in order to generate keyword ideas.
  optional string url = 3;

  // Requires at least one keyword.
  repeated string keywords = 4;
}

// Keyword Seed
message KeywordSeed {
  // Requires at least one keyword.
  repeated string keywords = 2;
}

// Site Seed
message SiteSeed {
  // The domain name of the site. If the customer requesting the ideas doesn't
  // own the site provided only public information is returned.
  optional string site = 2;
}

// Url Seed
message UrlSeed {
  // The URL to crawl in order to generate keyword ideas.
  optional string url = 2;
}

// Response message for [KeywordPlanIdeaService.GenerateKeywordIdeas][google.ads.googleads.v12.services.KeywordPlanIdeaService.GenerateKeywordIdeas].
message GenerateKeywordIdeaResponse {
  // Results of generating keyword ideas.
  repeated GenerateKeywordIdeaResult results = 1;

  // The aggregate metrics for all keyword ideas.
  google.ads.googleads.v12.common.KeywordPlanAggregateMetricResults aggregate_metric_results = 4;

  // Pagination token used to retrieve the next page of results.
  // Pass the content of this string as the `page_token` attribute of
  // the next request.
  // `next_page_token` is not returned for the last page.
  string next_page_token = 2;

  // Total number of results available.
  int64 total_size = 3;
}

// The result of generating keyword ideas.
message GenerateKeywordIdeaResult {
  // Text of the keyword idea.
  // As in Keyword Plan historical metrics, this text may not be an actual
  // keyword, but the canonical form of multiple keywords.
  // See KeywordPlanKeywordHistoricalMetrics message in KeywordPlanService.
  optional string text = 5;

  // The historical metrics for the keyword.
  google.ads.googleads.v12.common.KeywordPlanHistoricalMetrics keyword_idea_metrics = 3;

  // The annotations for the keyword.
  // The annotation data is only provided if requested.
  google.ads.googleads.v12.common.KeywordAnnotations keyword_annotations = 6;

  // The list of close variants from the requested keywords that
  // are combined into this GenerateKeywordIdeaResult. See
  // https://support.google.com/google-ads/answer/9342105 for the
  // definition of "close variants".
  repeated string close_variants = 7;
}

// Request message for
// [KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics][google.ads.googleads.v12.services.KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics].
message GenerateKeywordHistoricalMetricsRequest {
  // The ID of the customer with the recommendation.
  string customer_id = 1;

  // A list of keywords to get historical metrics.
  // Not all inputs will be returned as a result of near-exact deduplication.
  // For example, if stats for "car" and "cars" are requested, only "car" will
  // be returned.
  // A maximum of 10,000 keywords can be used.
  repeated string keywords = 2;

  // The resource name of the language to target.
  // Each keyword belongs to some set of languages; a keyword is included if
  // language is one of its languages.
  // If not set, all keywords will be included.
  optional string language = 4;

  // If true, adult keywords will be included in response.
  // The default value is false.
  bool include_adult_keywords = 5;

  // The resource names of the location to target. Maximum is 10.
  // An empty list MAY be used to specify all targeting geos.
  repeated string geo_target_constants = 6;

  // Targeting network.
  // If not set, Google Search And Partners Network will be used.
  google.ads.googleads.v12.enums.KeywordPlanNetworkEnum.KeywordPlanNetwork keyword_plan_network = 7;

  // The aggregate fields to include in response.
  google.ads.googleads.v12.common.KeywordPlanAggregateMetrics aggregate_metrics = 8;

  // The options for historical metrics data.
  google.ads.googleads.v12.common.HistoricalMetricsOptions historical_metrics_options = 3;
}

// Response message for
// [KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics][google.ads.googleads.v12.services.KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics].
message GenerateKeywordHistoricalMetricsResponse {
  // List of keywords and their historical metrics.
  repeated GenerateKeywordHistoricalMetricsResult results = 1;

  // The aggregate metrics for all keywords.
  google.ads.googleads.v12.common.KeywordPlanAggregateMetricResults aggregate_metric_results = 2;
}

// The result of generating keyword historical metrics.
message GenerateKeywordHistoricalMetricsResult {
  // The text of the query associated with one or more keywords.
  // Note that we de-dupe your keywords list, eliminating close variants
  // before returning the keywords as text. For example, if your request
  // originally contained the keywords "car" and "cars", the returned search
  // query will only contain "cars". The list of de-duped queries will be
  // included in close_variants field.
  optional string text = 1;

  // The list of close variants from the requested keywords whose stats
  // are combined into this GenerateKeywordHistoricalMetricsResult.
  repeated string close_variants = 3;

  // The historical metrics for text and its close variants
  google.ads.googleads.v12.common.KeywordPlanHistoricalMetrics keyword_metrics = 2;
}

// Request message for
// [KeywordPlanIdeaService.GenerateAdGroupThemes][google.ads.googleads.v12.services.KeywordPlanIdeaService.GenerateAdGroupThemes].
message GenerateAdGroupThemesRequest {
  // Required. The ID of the customer.
  string customer_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. A list of keywords to group into the provided AdGroups.
  repeated string keywords = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. A list of resource names of AdGroups to group keywords into.
  //  Resource name format: `customers/{customer_id}/adGroups/{ad_group_id}`
  repeated string ad_groups = 3 [(google.api.field_behavior) = REQUIRED];
}

// Response message for
// [KeywordPlanIdeaService.GenerateAdGroupThemes][google.ads.googleads.v12.services.KeywordPlanIdeaService.GenerateAdGroupThemes].
message GenerateAdGroupThemesResponse {
  // A list of suggested AdGroup/keyword pairings.
  repeated AdGroupKeywordSuggestion ad_group_keyword_suggestions = 1;

  // A list of provided AdGroups that could not be used as suggestions.
  repeated UnusableAdGroup unusable_ad_groups = 2;
}

// The suggested text and AdGroup/Campaign pairing for a given keyword.
message AdGroupKeywordSuggestion {
  // The original keyword text.
  string keyword_text = 1;

  // The normalized version of keyword_text for BROAD/EXACT/PHRASE suggestions.
  string suggested_keyword_text = 2;

  // The suggested keyword match type.
  google.ads.googleads.v12.enums.KeywordMatchTypeEnum.KeywordMatchType suggested_match_type = 3;

  // The suggested AdGroup for the keyword.
  // Resource name format: `customers/{customer_id}/adGroups/{ad_group_id}`
  string suggested_ad_group = 4;

  // The suggested Campaign for the keyword.
  // Resource name format: `customers/{customer_id}/campaigns/{campaign_id}`
  string suggested_campaign = 5;
}

// An AdGroup/Campaign pair that could not be used as a suggestion for keywords.
//
// AdGroups may not be usable if the AdGroup
//
// * belongs to a Campaign that is not ENABLED or PAUSED
// * is itself not ENABLED
message UnusableAdGroup {
  // The AdGroup resource name.
  // Resource name format: `customers/{customer_id}/adGroups/{ad_group_id}`
  string ad_group = 1;

  // The Campaign resource name.
  // Resource name format: `customers/{customer_id}/campaigns/{campaign_id}`
  string campaign = 2;
}