// Copyright 2026 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.datamanager.v1;

import "google/ads/datamanager/v1/age_range.proto";
import "google/ads/datamanager/v1/gender.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";

option csharp_namespace = "Google.Ads.DataManager.V1";
option go_package = "cloud.google.com/go/datamanager/apiv1/datamanagerpb;datamanagerpb";
option java_multiple_files = true;
option java_outer_classname = "InsightsServiceProto";
option java_package = "com.google.ads.datamanager.v1";
option php_namespace = "Google\\Ads\\DataManager\\V1";
option ruby_package = "Google::Ads::DataManager::V1";

// Service to return insights on marketing data.
//
// This feature is only available to data partners.
service MarketingDataInsightsService {
  option (google.api.default_host) = "datamanager.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/datamanager";

  // Retrieves marketing data insights for a given user list.
  //
  // This feature is only available to data partners.
  //
  // Authorization Headers:
  //
  // This method supports the following optional headers to define how the API
  // authorizes access for the request:
  //
  // * `login-account`: (Optional) The resource name of the account where the
  //   Google Account of the credentials is a user. If not set, defaults to the
  //   account of the request. Format:
  //   `accountTypes/{loginAccountType}/accounts/{loginAccountId}`
  // * `linked-account`: (Optional) The resource name of the account with an
  //    established product link to the `login-account`. Format:
  //    `accountTypes/{linkedAccountType}/accounts/{linkedAccountId}`
  rpc RetrieveInsights(RetrieveInsightsRequest)
      returns (RetrieveInsightsResponse) {
    option (google.api.http) = {
      post: "/v1/{parent=accountTypes/*/accounts/*}/insights:retrieve"
      body: "*"
    };
  }
}

// Request message for DM API MarketingDataInsightsService.RetrieveInsights
message RetrieveInsightsRequest {
  // Required. The parent account that owns the user list.
  // Format: `accountTypes/{account_type}/accounts/{account}`
  string parent = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. Baseline for the insights requested.
  Baseline baseline = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The user list ID for which insights are requested.
  string user_list_id = 3 [(google.api.field_behavior) = REQUIRED];
}

// Baseline criteria against which insights are compared.
message Baseline {
  // The baseline location of the request. Baseline location is on OR-list of
  // ISO 3166-1 alpha-2 region codes of the requested regions.
  message Location {
    // List of ISO 3166-1 alpha-2 region codes.
    repeated string region_codes = 1;
  }

  // Baseline location against which insights are compared.
  oneof baseline {
    // The baseline location of the request. Baseline location is an OR-list
    // of the requested regions.
    Location baseline_location = 1;

    // If set to true, the service will try to automatically detect the
    // baseline location for insights.
    bool location_auto_detection_enabled = 2;
  }
}

// Response message for DM API MarketingDataInsightsService.RetrieveInsights
message RetrieveInsightsResponse {
  // Insights for marketing data.
  //
  // This feature is only available to data partners.
  message MarketingDataInsight {
    // Possible dimensions for use in generating insights.
    enum AudienceInsightsDimension {
      // Not specified.
      AUDIENCE_INSIGHTS_DIMENSION_UNSPECIFIED = 0;

      // The value is unknown in this version.
      AUDIENCE_INSIGHTS_DIMENSION_UNKNOWN = 1;

      // An Affinity UserInterest.
      AFFINITY_USER_INTEREST = 2;

      // An In-Market UserInterest.
      IN_MARKET_USER_INTEREST = 3;

      // An age range.
      AGE_RANGE = 4;

      // A gender.
      GENDER = 5;
    }

    // Insights for a collection of related attributes of the same dimension.
    message MarketingDataInsightsAttribute {
      // The user interest ID.
      optional int64 user_interest_id = 1;

      // Measure of lift that the audience has for the attribute value as
      // compared to the baseline. Range [0-1].
      optional float lift = 2;

      // Age range of the audience for which the lift is provided.
      optional AgeRange age_range = 3;

      // Gender of the audience for which the lift is provided.
      optional Gender gender = 4;
    }

    // The dimension to which the insight belongs.
    AudienceInsightsDimension dimension = 1;

    // Insights for values of a given dimension.
    repeated MarketingDataInsightsAttribute attributes = 2;
  }

  // Contains the insights for the marketing data.
  repeated MarketingDataInsight marketing_data_insights = 1;
}