// Copyright 2025 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.maps.weather.v1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/maps/weather/v1/air_pressure.proto";
import "google/maps/weather/v1/forecast_day.proto";
import "google/maps/weather/v1/forecast_hour.proto";
import "google/maps/weather/v1/history_hour.proto";
import "google/maps/weather/v1/precipitation.proto";
import "google/maps/weather/v1/temperature.proto";
import "google/maps/weather/v1/units_system.proto";
import "google/maps/weather/v1/visibility.proto";
import "google/maps/weather/v1/weather_condition.proto";
import "google/maps/weather/v1/wind.proto";
import "google/protobuf/timestamp.proto";
import "google/type/datetime.proto";
import "google/type/latlng.proto";

option csharp_namespace = "Google.Geo.Weather.V1";
option go_package = "cloud.google.com/go/maps/weather/apiv1/weatherpb;weatherpb";
option java_multiple_files = true;
option java_outer_classname = "WeatherServiceProto";
option java_package = "com.google.maps.weather.v1";
option objc_class_prefix = "GMWV1";
option php_namespace = "Google\\Geo\\Weather\\V1";

// Service definition for the Weather API.
service Weather {
  option (google.api.default_host) = "weather.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Returns the current weather conditions at a given location.
  rpc LookupCurrentConditions(LookupCurrentConditionsRequest)
      returns (LookupCurrentConditionsResponse) {
    option (google.api.http) = {
      get: "/v1/currentConditions:lookup"
    };
  }

  // Returns up to 240 hours of hourly forecasts at a given location, starting
  // from the current hour.
  rpc LookupForecastHours(LookupForecastHoursRequest)
      returns (LookupForecastHoursResponse) {
    option (google.api.http) = {
      get: "/v1/forecast/hours:lookup"
    };
  }

  // Returns up to 10 days of daily forecasts at a given location, starting from
  // the current day.
  rpc LookupForecastDays(LookupForecastDaysRequest)
      returns (LookupForecastDaysResponse) {
    option (google.api.http) = {
      get: "/v1/forecast/days:lookup"
    };
  }

  // Returns up to 24 hours of hourly historical weather data at a given
  // location, starting from the last hour.
  rpc LookupHistoryHours(LookupHistoryHoursRequest)
      returns (LookupHistoryHoursResponse) {
    option (google.api.http) = {
      get: "/v1/history/hours:lookup"
    };
  }

  // Returns public weather alerts for a given location.
  rpc LookupPublicAlerts(LookupPublicAlertsRequest)
      returns (LookupPublicAlertsResponse) {
    option (google.api.http) = {
      get: "/v1/publicAlerts:lookup"
    };
  }
}

// Request for the LookupCurrentConditions RPC.
message LookupCurrentConditionsRequest {
  // Required. The location to get the current weather conditions for.
  google.type.LatLng location = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The units system to use for the returned weather conditions. If
  // not provided, the returned weather conditions will be in the metric system
  // (default = METRIC).
  UnitsSystem units_system = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Allows the client to choose the language for the response. If
  // data cannot be provided for that language, the API uses the closest match.
  // Allowed values rely on the IETF BCP-47 standard. The default value is "en".
  optional string language_code = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Response for the LookupCurrentConditions RPC - represents the current weather
// conditions at the requested location.
message LookupCurrentConditionsResponse {
  // Represents a set of changes in the current conditions over the last 24
  // hours.
  message CurrentConditionsHistory {
    // The current temperature minus the temperature 24 hours ago.
    Temperature temperature_change = 1;

    // The maximum (high) temperature in the past 24 hours.
    Temperature max_temperature = 2;

    // The minimum (low) temperature in the past 24 hours.
    Temperature min_temperature = 3;

    // The amount of snow, measured as liquid water equivalent,
    // that has accumulated over the last 24 hours.
    // Note: QPF is an abbreviation for Quantitative Precipitation Forecast
    // (please see the QuantitativePrecipitationForecast definition for more
    // details).
    QuantitativePrecipitationForecast snow_qpf = 5;

    // The amount of rain, measured as liquid water equivalent, that has
    // accumulated over the last 24 hours. Note: QPF is an abbreviation for
    // Quantitative Precipitation Forecast (please see the
    // QuantitativePrecipitationForecast definition for more details).
    QuantitativePrecipitationForecast qpf = 6;
  }

  // Current time (UTC) associated with the returned data.
  google.protobuf.Timestamp current_time = 1;

  // The time zone at the requested location.
  google.type.TimeZone time_zone = 2;

  // True if the current time at the requested location is between the local
  // sunrise (inclusive) and the sunset (exclusive) times. Otherwise, it is
  // nighttime (between the sunset and the next sunrise).
  optional bool is_daytime = 3;

  // The current weather condition.
  WeatherCondition weather_condition = 4;

  // The current temperature.
  Temperature temperature = 5;

  // The measure of how the temperature currently feels like at the requested
  // location.
  Temperature feels_like_temperature = 6;

  // The current dew point temperature.
  Temperature dew_point = 7;

  // The current heat index temperature.
  Temperature heat_index = 8;

  // The current wind chill, air temperature exposed on the skin.
  Temperature wind_chill = 9;

  // The current percent of relative humidity (values from 0 to 100).
  optional int32 relative_humidity = 10;

  // The current ultraviolet (UV) index.
  optional int32 uv_index = 11;

  // The current precipitation probability and amount of precipitation
  // accumulated over the last hour.
  Precipitation precipitation = 12;

  // The current thunderstorm probability (values from 0 to 100).
  optional int32 thunderstorm_probability = 13;

  // The current air pressure conditions.
  AirPressure air_pressure = 14;

  // The current wind conditions.
  Wind wind = 15;

  // The current visibility.
  Visibility visibility = 16;

  // The current percentage of the sky covered by clouds (values from 0 to 100).
  optional int32 cloud_cover = 17;

  // The changes in the current conditions over the last 24 hours.
  CurrentConditionsHistory current_conditions_history = 18;
}

// Request for the LookupForecastHours RPC.
message LookupForecastHoursRequest {
  // Required. The location to get the hourly forecast for.
  google.type.LatLng location = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Limits the amount of total hours to fetch starting from the
  // current hour - a value from 1 to 240 (inclusive). The default is the
  // maximum allowed value of 240.
  optional int32 hours = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The units system to use for the returned weather conditions. If
  // not provided, the returned weather conditions will be in the metric system
  // (default = METRIC).
  UnitsSystem units_system = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Allows the client to choose the language for the response. If
  // data cannot be provided for that language, the API uses the closest match.
  // Allowed values rely on the IETF BCP-47 standard. The default value is "en".
  optional string language_code = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The maximum number of hourly forecast records to return per page
  // - a value from 1 to 24 (inclusive). The default is the maximum allowed
  // value of 24.
  int32 page_size = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token received from a previous request. It is used to
  // retrieve the subsequent page.
  string page_token = 6 [(google.api.field_behavior) = OPTIONAL];
}

// Response for the LookupForecastHours RPC.
message LookupForecastHoursResponse {
  // The hourly forecast records, according to the number of hours and page size
  // specified in the request.
  repeated ForecastHour forecast_hours = 1;

  // The time zone at the requested location.
  google.type.TimeZone time_zone = 2;

  // The token to retrieve the next page.
  string next_page_token = 3;
}

// Request for the LookupForecastDays RPC.
message LookupForecastDaysRequest {
  // Required. The location to get the daily forecast for.
  google.type.LatLng location = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Limits the amount of total days to fetch starting from the
  // current day - a value from 1 to 10 (inclusive). The default value is the
  // maximum allowed value of 10.
  optional int32 days = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The units system to use for the returned weather conditions. If
  // not provided, the returned weather conditions will be in the metric system
  // (default = METRIC).
  UnitsSystem units_system = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Allows the client to choose the language for the response. If
  // data cannot be provided for that language, the API uses the closest match.
  // Allowed values rely on the IETF BCP-47 standard. The default value is "en".
  optional string language_code = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The maximum number of daily forecast records to return per page -
  // a value from 1 to 10 (inclusive). The default value is 5.
  int32 page_size = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token received from a previous request. It is used to
  // retrieve the subsequent page.
  string page_token = 6 [(google.api.field_behavior) = OPTIONAL];
}

// Response for the LookupForecastDays RPC.
message LookupForecastDaysResponse {
  // The daily forecast records, according to the number of days and page size
  // specified in the request.
  repeated ForecastDay forecast_days = 1;

  // The time zone at the requested location.
  google.type.TimeZone time_zone = 2;

  // The token to retrieve the next page.
  string next_page_token = 3;
}

// Request for the LookupHistoryHours RPC.
message LookupHistoryHoursRequest {
  // Required. The location to get the hourly historical data for.
  google.type.LatLng location = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Limits the amount of total hours to fetch starting from the last
  // hour - a from 1 to 24 (inclusive). The default is the maximum allowed value
  // of 24.
  optional int32 hours = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The units system to use for the returned weather conditions. If
  // not provided, the returned weather conditions will be in the metric system
  // (default = METRIC).
  UnitsSystem units_system = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Allows the client to choose the language for the response. If
  // data cannot be provided for that language, the API uses the closest match.
  // Allowed values rely on the IETF BCP-47 standard. The default value is "en".
  optional string language_code = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The maximum number of hourly historical records to return per
  // page - a value from 1 to 24 (inclusive). The default is the maximum allowed
  // value of 24.
  int32 page_size = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token received from a previous request. It is used to
  // retrieve the subsequent page.
  string page_token = 6 [(google.api.field_behavior) = OPTIONAL];
}

// Response for the LookupHistoryHours RPC.
message LookupHistoryHoursResponse {
  // The hourly historical records, according to the number of hours and page
  // size specified in the request.
  repeated HistoryHour history_hours = 1;

  // The time zone at the requested location.
  google.type.TimeZone time_zone = 2;

  // The token to retrieve the next page.
  string next_page_token = 3;
}

// (-- Request for the LookupPublicAlerts RPC. --)
// (-- TODO (418938868): mikesky - Add request fields.
// Reason: We want to parallelize our work and creating a simple proto for
// quick approval could help us do other tasks while the larger proto is
// being approved. --)
message LookupPublicAlertsRequest {}

// (-- Response for the LookupPublicAlerts RPC. --)
// (-- TODO(418938868): mikesky - Add public weather alert records to the
// response. Reason: We want to parallelize our work and creating a simple proto
// for quick approval could help us do other tasks while the larger proto is
// being approved. --)
message LookupPublicAlertsResponse {}