path: root/google/ads/googleads/v1/resources/recommendation.proto

// Copyright 2020 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.v1.resources;

import "google/ads/googleads/v1/common/criteria.proto";
import "google/ads/googleads/v1/common/extensions.proto";
import "google/ads/googleads/v1/enums/keyword_match_type.proto";
import "google/ads/googleads/v1/enums/recommendation_type.proto";
import "google/ads/googleads/v1/enums/target_cpa_opt_in_recommendation_goal.proto";
import "google/ads/googleads/v1/resources/ad.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/wrappers.proto";
import "google/api/annotations.proto";

option csharp_namespace = "Google.Ads.GoogleAds.V1.Resources";
option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v1/resources;resources";
option java_multiple_files = true;
option java_outer_classname = "RecommendationProto";
option java_package = "com.google.ads.googleads.v1.resources";
option objc_class_prefix = "GAA";
option php_namespace = "Google\\Ads\\GoogleAds\\V1\\Resources";
option ruby_package = "Google::Ads::GoogleAds::V1::Resources";

// Proto file describing the Recommendation resource.

// A recommendation.
message Recommendation {
  option (google.api.resource) = {
    type: "googleads.googleapis.com/Recommendation"
    pattern: "customers/{customer}/recommendations/{recommendation}"
  };

  // The impact of making the change as described in the recommendation.
  // Some types of recommendations may not have impact information.
  message RecommendationImpact {
    // Output only. Base metrics at the time the recommendation was generated.
    RecommendationMetrics base_metrics = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Estimated metrics if the recommendation is applied.
    RecommendationMetrics potential_metrics = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Weekly account performance metrics. For some recommendation types, these
  // are averaged over the past 90-day period and hence can be fractional.
  message RecommendationMetrics {
    // Output only. Number of ad impressions.
    google.protobuf.DoubleValue impressions = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Number of ad clicks.
    google.protobuf.DoubleValue clicks = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Cost (in micros) for advertising, in the local currency for the account.
    google.protobuf.Int64Value cost_micros = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Number of conversions.
    google.protobuf.DoubleValue conversions = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Number of video views for a video ad campaign.
    google.protobuf.DoubleValue video_views = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // The budget recommendation for budget constrained campaigns.
  message CampaignBudgetRecommendation {
    // The impact estimates for a given budget amount.
    message CampaignBudgetRecommendationOption {
      // Output only. The budget amount for this option.
      google.protobuf.Int64Value budget_amount_micros = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

      // Output only. The impact estimate if budget is changed to amount specified in this
      // option.
      RecommendationImpact impact = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
    }

    // Output only. The current budget amount in micros.
    google.protobuf.Int64Value current_budget_amount_micros = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The recommended budget amount in micros.
    google.protobuf.Int64Value recommended_budget_amount_micros = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The budget amounts and associated impact estimates for some values of
    // possible budget amounts.
    repeated CampaignBudgetRecommendationOption budget_options = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // The keyword recommendation.
  message KeywordRecommendation {
    // Output only. The recommended keyword.
    google.ads.googleads.v1.common.KeywordInfo keyword = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The recommended CPC (cost-per-click) bid.
    google.protobuf.Int64Value recommended_cpc_bid_micros = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // The Call extension recommendation.
  message CallExtensionRecommendation {
    // Output only. Call extensions recommended to be added.
    repeated google.ads.googleads.v1.common.CallFeedItem recommended_extensions = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // The text ad recommendation.
  message TextAdRecommendation {
    // Output only. Recommended ad.
    Ad ad = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Creation date of the recommended ad.
    // YYYY-MM-DD format, e.g., 2018-04-17.
    google.protobuf.StringValue creation_date = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Date, if present, is the earliest when the recommendation will be auto
    // applied.
    // YYYY-MM-DD format, e.g., 2018-04-17.
    google.protobuf.StringValue auto_apply_date = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // The Target CPA opt-in recommendation.
  message TargetCpaOptInRecommendation {
    // The Target CPA opt-in option with impact estimate.
    message TargetCpaOptInRecommendationOption {
      // Output only. The goal achieved by this option.
      google.ads.googleads.v1.enums.TargetCpaOptInRecommendationGoalEnum.TargetCpaOptInRecommendationGoal goal = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

      // Output only. Average CPA target.
      google.protobuf.Int64Value target_cpa_micros = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

      // Output only. The minimum campaign budget, in local currency for the account,
      // required to achieve the target CPA.
      // Amount is specified in micros, where one million is equivalent to one
      // currency unit.
      google.protobuf.Int64Value required_campaign_budget_amount_micros = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

      // Output only. The impact estimate if this option is selected.
      RecommendationImpact impact = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
    }

    // Output only. The available goals and corresponding options for Target CPA strategy.
    repeated TargetCpaOptInRecommendationOption options = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The recommended average CPA target. See required budget amount and impact
    // of using this recommendation in options list.
    google.protobuf.Int64Value recommended_target_cpa_micros = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // The Maximize Clicks opt-in recommendation.
  message MaximizeClicksOptInRecommendation {
    // Output only. The recommended new budget amount.
    // Only set if the current budget is too high.
    google.protobuf.Int64Value recommended_budget_amount_micros = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // The Maximize Conversions Opt-In recommendation.
  message MaximizeConversionsOptInRecommendation {
    // Output only. The recommended new budget amount.
    google.protobuf.Int64Value recommended_budget_amount_micros = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // The move unused budget recommendation.
  message MoveUnusedBudgetRecommendation {
    // Output only. The excess budget's resource_name.
    google.protobuf.StringValue excess_campaign_budget = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The recommendation for the constrained budget to increase.
    CampaignBudgetRecommendation budget_recommendation = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // The Enhanced Cost-Per-Click Opt-In recommendation.
  message EnhancedCpcOptInRecommendation {

  }

  // The Search Partners Opt-In recommendation.
  message SearchPartnersOptInRecommendation {

  }

  // The Optimize Ad Rotation recommendation.
  message OptimizeAdRotationRecommendation {

  }

  // The Callout extension recommendation.
  message CalloutExtensionRecommendation {
    // Output only. Callout extensions recommended to be added.
    repeated google.ads.googleads.v1.common.CalloutFeedItem recommended_extensions = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // The keyword match type recommendation.
  message KeywordMatchTypeRecommendation {
    // Output only. The existing keyword where the match type should be more broad.
    google.ads.googleads.v1.common.KeywordInfo keyword = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The recommended new match type.
    google.ads.googleads.v1.enums.KeywordMatchTypeEnum.KeywordMatchType recommended_match_type = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // The Sitelink extension recommendation.
  message SitelinkExtensionRecommendation {
    // Output only. Sitelink extensions recommended to be added.
    repeated google.ads.googleads.v1.common.SitelinkFeedItem recommended_extensions = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Immutable. The resource name of the recommendation.
  //
  // `customers/{customer_id}/recommendations/{recommendation_id}`
  string resource_name = 1 [
    (google.api.field_behavior) = IMMUTABLE,
    (google.api.resource_reference) = {
      type: "googleads.googleapis.com/Recommendation"
    }
  ];

  // Output only. The type of recommendation.
  google.ads.googleads.v1.enums.RecommendationTypeEnum.RecommendationType type = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The impact on account performance as a result of applying the
  // recommendation.
  RecommendationImpact impact = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The budget targeted by this recommendation. This will be set only when
  // the recommendation affects a single campaign budget.
  //
  // This field will be set for the following recommendation types:
  // CAMPAIGN_BUDGET, MOVE_UNUSED_BUDGET
  google.protobuf.StringValue campaign_budget = 5 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = {
      type: "googleads.googleapis.com/CampaignBudget"
    }
  ];

  // Output only. The campaign targeted by this recommendation. This will be set only when
  // the recommendation affects a single campaign.
  //
  // This field will be set for the following recommendation types:
  // CALL_EXTENSION, CALLOUT_EXTENSION, ENHANCED_CPC_OPT_IN, KEYWORD,
  // KEYWORD_MATCH_TYPE, MAXIMIZE_CLICKS_OPT_IN, MAXIMIZE_CONVERSIONS_OPT_IN,
  // OPTIMIZE_AD_ROTATION, SEARCH_PARTNERS_OPT_IN, SITELINK_EXTENSION,
  // TARGET_CPA_OPT_IN, TEXT_AD
  google.protobuf.StringValue campaign = 6 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = {
      type: "googleads.googleapis.com/Campaign"
    }
  ];

  // Output only. The ad group targeted by this recommendation. This will be set only when
  // the recommendation affects a single ad group.
  //
  // This field will be set for the following recommendation types:
  // KEYWORD, OPTIMIZE_AD_ROTATION, TEXT_AD
  google.protobuf.StringValue ad_group = 7 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = {
      type: "googleads.googleapis.com/AdGroup"
    }
  ];

  // Output only. Whether the recommendation is dismissed or not.
  google.protobuf.BoolValue dismissed = 13 [(google.api.field_behavior) = OUTPUT_ONLY];

  // The details of recommendation.
  oneof recommendation {
    // Output only. The campaign budget recommendation.
    CampaignBudgetRecommendation campaign_budget_recommendation = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The keyword recommendation.
    KeywordRecommendation keyword_recommendation = 8 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Add expanded text ad recommendation.
    TextAdRecommendation text_ad_recommendation = 9 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The TargetCPA opt-in recommendation.
    TargetCpaOptInRecommendation target_cpa_opt_in_recommendation = 10 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The MaximizeConversions Opt-In recommendation.
    MaximizeConversionsOptInRecommendation maximize_conversions_opt_in_recommendation = 11 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The Enhanced Cost-Per-Click Opt-In recommendation.
    EnhancedCpcOptInRecommendation enhanced_cpc_opt_in_recommendation = 12 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The Search Partners Opt-In recommendation.
    SearchPartnersOptInRecommendation search_partners_opt_in_recommendation = 14 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The MaximizeClicks Opt-In recommendation.
    MaximizeClicksOptInRecommendation maximize_clicks_opt_in_recommendation = 15 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The Optimize Ad Rotation recommendation.
    OptimizeAdRotationRecommendation optimize_ad_rotation_recommendation = 16 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The Callout extension recommendation.
    CalloutExtensionRecommendation callout_extension_recommendation = 17 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The Sitelink extension recommendation.
    SitelinkExtensionRecommendation sitelink_extension_recommendation = 18 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The Call extension recommendation.
    CallExtensionRecommendation call_extension_recommendation = 19 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The keyword match type recommendation.
    KeywordMatchTypeRecommendation keyword_match_type_recommendation = 20 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The move unused budget recommendation.
    MoveUnusedBudgetRecommendation move_unused_budget_recommendation = 21 [(google.api.field_behavior) = OUTPUT_ONLY];
  }
}