// 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.admanager.v1;

import "google/ads/admanager/v1/date_range.proto";
import "google/ads/admanager/v1/forecast_messages.proto";
import "google/ads/admanager/v1/targeting.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";

option csharp_namespace = "Google.Ads.AdManager.V1";
option go_package = "google.golang.org/genproto/googleapis/ads/admanager/v1;admanager";
option java_multiple_files = true;
option java_outer_classname = "ForecastServiceProto";
option java_package = "com.google.ads.admanager.v1";
option php_namespace = "Google\\Ads\\AdManager\\V1";
option ruby_package = "Google::Ads::AdManager::V1";

// Provides methods for handling forecasting actions.
service ForecastService {
  option (google.api.default_host) = "admanager.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/admanager,"
      "https://www.googleapis.com/auth/admanager.readonly";

  // Gets the availability forecast for a [ProposalLineItem][] or
  // [LineItem][google.ads.admanager.v1.LineItem]. An availability forecast
  // reports the maximum number of available units that the line item can book,
  // and the total number of units matching the line item's targeting.
  rpc RunAvailabilityForecast(RunAvailabilityForecastRequest)
      returns (RunAvailabilityForecastResponse) {
    option (google.api.http) = {
      post: "/v1/{parent=networks/*}:runAvailabilityForecast"
      body: "*"
    };
    option (google.api.method_signature) = "parent";
  }

  // Runs a delivery simulation forecast for existing or prospective line items.
  // A delivery forecast reports the number of units that will be delivered to
  // each line item given the line item goals. The simulation considers
  // contentions from other line items, including the other prospective line
  // items in the request.
  rpc RunDeliveryForecast(RunDeliveryForecastRequest)
      returns (RunDeliveryForecastResponse) {
    option (google.api.http) = {
      post: "/v1/{parent=networks/*}:runDeliveryForecast"
      body: "*"
    };
    option (google.api.method_signature) = "parent";
  }

  // Gets forecasted and historical traffic data for the segment of
  // traffic specified by the provided request.
  rpc RunTrafficData(RunTrafficDataRequest) returns (RunTrafficDataResponse) {
    option (google.api.http) = {
      post: "/v1/{parent=networks/*}:runTrafficData"
      body: "*"
    };
    option (google.api.method_signature) = "parent";
  }
}

// Request object for [RunAvailabilityForecast][] method.
message RunAvailabilityForecastRequest {
  // The [LineItem][google.ads.admanager.v1.LineItem] to be forecasted. Only one
  // of the following fields can be set.
  oneof line_item_data {
    // Optional. The resource name of the
    // [LineItem][google.ads.admanager.v1.LineItem] to be forecasted. Format:
    // `networks/{network_code}/lineItems/{line_item_id}`
    string existing_line_item = 3 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.resource_reference) = {
        type: "admanager.googleapis.com/LineItem"
      }
    ];
  }

  // Required. Format: `networks/{network_code}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "admanager.googleapis.com/Network"
    }
  ];

  // Required. The availability forecast options.
  AvailabilityForecastOptions availability_forecast_options = 2
      [(google.api.field_behavior) = REQUIRED];
}

// Response object for [RunAvailabilityForecast][] method.
message RunAvailabilityForecastResponse {
  // The availability forecast.
  AvailabilityForecast availability_forecast_result = 1;
}

// Request object for [RunDeliveryForecast][] method.
message RunDeliveryForecastRequest {
  // The line items to be forecasted. Only one of the following fields can be
  // set.
  oneof line_item_data {
    // Optional. The resource names of the
    // [LineItems][google.ads.admanager.v1.LineItem] to be forecasted.
    ExistingLineItemList existing_line_items = 3
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Required. Format: `networks/{network_code}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "admanager.googleapis.com/Network"
    }
  ];

  // Required. The delivery forecast options.
  DeliveryForecastOptions delivery_forecast_options = 2
      [(google.api.field_behavior) = REQUIRED];
}

// Response object for [RunDeliveryForecast][] method.
message RunDeliveryForecastResponse {
  // The delivery forecast result.
  DeliveryForecastResult delivery_forecast_result = 1;
}

// Request object for [RunTrafficData][] method.
message RunTrafficDataRequest {
  // Required. Format: `networks/{network_code}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "admanager.googleapis.com/Network"
    }
  ];

  // Required. The [Targeting][google.ads.admanager.v1.Targeting] resource that
  // defines a segment of traffic.
  Targeting targeting = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The date range for which traffic data are requested. This range
  // may cover historical dates, future dates, or both.
  //
  // The data returned are not guaranteed to cover the entire requested date
  // range. If sufficient data are not available to cover the entire requested
  // date range, a response may be returned with a later start date, earlier end
  // date, or both.
  DateRange requested_date_range = 3 [(google.api.field_behavior) = REQUIRED];
}

// Response object for [RunTrafficData][] method.
message RunTrafficDataResponse {
  // Time series of historical traffic ad opportunity counts.
  //
  // This may be null if the requested date range did not contain any historical
  // dates, or if no historical data are available for the requested traffic
  // segment.
  TimeSeries historical_time_series = 1;

  // Time series of forecasted traffic ad opportunity counts.
  //
  // This may be null if the requested date range did not contain any future
  // dates, or if no forecasted data are available for the requested traffic
  // segment.
  TimeSeries forecasted_time_series = 2;

  // Time series of future traffic volumes forecasted to be sold.
  //
  // This may be null if the requested date range did not contain any future
  // dates, or if no sell-through data are available for the requested traffic
  // segment.
  TimeSeries forecasted_assigned_time_series = 3;

  // The overall date range spanned by the union of all time series in the
  // response.
  //
  // This is a summary field for convenience. The value will be set such that
  // the start date is equal to the earliest start date of all time series
  // included, and the end date is equal to the latest end date of all time
  // series included.
  //
  // If all time series fields are null, this field will also be null.
  DateRange overall_date_range = 4;
}