// 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/forecast_minute.proto";
import "google/maps/weather/v1/history_hour.proto";
import "google/maps/weather/v1/map_types.proto";
import "google/maps/weather/v1/precipitation.proto";
import "google/maps/weather/v1/public_alerts.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/interval.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"
    };
  }

  // Returns minute-level precipitation nowcast events for up to 6 hours.
  rpc LookupForecastMinutes(LookupForecastMinutesRequest)
      returns (LookupForecastMinutesResponse) {
    option (google.api.http) = {
      get: "/v1/forecast/minutes: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.
message LookupPublicAlertsRequest {
  // Required. The location to get public weather alerts for. The service will
  // return alerts whose affected area intersects with this location.
  google.type.LatLng location = 1 [(google.api.field_behavior) = REQUIRED];

  // 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 = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The maximum number of public weather alert records to return per
  // page.
  int32 page_size = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token received from a previous
  // `LookupPublicAlerts` call. Provide this to retrieve the subsequent
  // page. When paginating, all other parameters provided to
  // `LookupPublicAlerts` must match the call that provided the page
  // token.
  string page_token = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Response for the LookupPublicAlerts RPC.
message LookupPublicAlertsResponse {
  // The public weather alert records, according to the number of alerts and
  // page size specified in the request.
  repeated PublicAlerts weather_alerts = 1;

  // The ISO_3166-1 alpha-2 code of the region corresponding to the
  // location provided in the request. The region is stated using
  // ISO_3166-1_alpha-2.
  string region_code = 2;

  // A token that can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 3;
}

// Request for the LookupForecastMinutes RPC.
message LookupForecastMinutesRequest {
  // The location to get the minutely forecast 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];

  reserved 3;
  reserved "language_code";

  // Optional. The maximum number of forecast records to return per page.
  int32 page_size = 4 [(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 = 5 [(google.api.field_behavior) = OPTIONAL];
}

// Response for the LookupForecastMinutes RPC.
message LookupForecastMinutesResponse {
  reserved 1;
  reserved "events";

  // The overall timeframe for the predictions.
  google.type.Interval overall_prediction_timeframe = 2;

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

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

  // The minute-level prediction segments.
  repeated PrecipitationSegment segments = 5;
}

// (-- Request for the LookupMapTile RPC. --)
message LookupMapTileRequest {
  reserved 1;

  // The type of the weather map. Defines the weather event that the
  // map will graphically represent.
  //
  //    Allowed values:
  //    - US_PRECIPITATION_CURRENT - US precipitation current map.
  //    - EU_PRECIPITATION_CURRENT - EU precipitation current map.
  MapType map_type = 2 [(google.api.field_behavior) = REQUIRED];

  // The map's zoom level. Defines how large or small the contents
  // of a map appear in a map view.
  //
  // Zoom level 0 is the entire world in a single tile.
  // Zoom level 1 is the entire world in 4 tiles.
  // Zoom level 2 is the entire world in 16 tiles.
  // Zoom level 16 is the entire world in 65,536 tiles.
  //
  // Allowed values: 0-16
  // (-- api-linter: core::0203::required-and-optional=disabled
  //     aip.dev/not-precedent: this field needs to keep presence. --)
  int32 zoom = 3 [(google.api.field_behavior) = REQUIRED];

  // Defines the east-west point in the requested tile.
  // (-- api-linter: core::0203::required-and-optional=disabled
  //     aip.dev/not-precedent: this field needs to keep presence. --)
  int32 x = 4 [(google.api.field_behavior) = REQUIRED];

  // Defines the north-south point in the requested tile.
  // (-- api-linter: core::0203::required-and-optional=disabled
  //     aip.dev/not-precedent: this field needs to keep presence. --)
  int32 y = 5 [(google.api.field_behavior) = REQUIRED];
}