// 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/protobuf/timestamp.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 = "CelestialEventsProto";
option java_package = "com.google.maps.weather.v1";
option objc_class_prefix = "GMWV1";
option php_namespace = "Google\\Geo\\Weather\\V1";

// Represents the events related to the sun (e.g. sunrise, sunset).
message SunEvents {
  // The time when the sun rises.
  //
  // NOTE: In some unique cases (e.g. north of the artic circle) there may be no
  // sunrise time for a day. In these cases, this field will be unset.
  google.protobuf.Timestamp sunrise_time = 1;

  // The time when the sun sets.
  //
  // NOTE: In some unique cases (e.g. north of the artic circle) there may be no
  // sunset time for a day. In these cases, this field will be unset.
  google.protobuf.Timestamp sunset_time = 2;
}

// Represents the events related to the moon (e.g. moonrise, moonset).
message MoonEvents {
  // The time when the upper limb of the moon appears above the horizon
  // (see https://en.wikipedia.org/wiki/Moonrise_and_moonset).
  //
  // NOTE: For most cases, there'll be a single moon rise time per day. In other
  // cases, the list might be empty (e.g. when the moon rises after next day
  // midnight).
  // However, in unique cases (e.g. in polar regions), the list may contain
  // more than one value. In these cases, the values are sorted in ascending
  // order.
  repeated google.protobuf.Timestamp moonrise_times = 4;

  // The time when the upper limb of the moon disappears below the
  // horizon (see https://en.wikipedia.org/wiki/Moonrise_and_moonset).
  //
  // NOTE: For most cases, there'll be a single moon set time per day. In other
  // cases, the list might be empty (e.g. when the moon sets after next day
  // midnight).
  // However, in unique cases (e.g. in polar regions), the list may contain
  // more than one value. In these cases, the values are sorted in ascending
  // order.
  repeated google.protobuf.Timestamp moonset_times = 5;

  // The moon phase (a.k.a. lunar phase).
  MoonPhase moon_phase = 3;
}

// Marks the moon phase (a.k.a. lunar phase).
enum MoonPhase {
  // Unspecified moon phase.
  MOON_PHASE_UNSPECIFIED = 0;

  // The moon is not illuminated by the sun.
  NEW_MOON = 1;

  // The moon is lit by 0%-50% on its right side in the northern hemisphere 🌒
  // and on its left side in the southern hemisphere 🌘.
  WAXING_CRESCENT = 2;

  // The moon is lit by 50.1% on its right side in the northern hemisphere 🌓
  // and on its left side in the southern hemisphere 🌗.
  FIRST_QUARTER = 3;

  // The moon is lit by 50%-100% on its right side in the northern hemisphere 🌔
  // and on its left side in the southern hemisphere 🌖.
  WAXING_GIBBOUS = 4;

  // The moon is fully illuminated.
  FULL_MOON = 5;

  // The moon is lit by 50%-100% on its left side in the northern hemisphere 🌖
  // and on its right side in the southern hemisphere 🌔.
  WANING_GIBBOUS = 6;

  // The moon is lit by 50.1% on its left side in the northern hemisphere 🌗
  // and on its right side in the southern hemisphere 🌓.
  LAST_QUARTER = 7;

  // The moon is lit by 0%-50% on its left side in the northern hemisphere 🌘
  // and on its right side in the southern hemisphere 🌒.
  WANING_CRESCENT = 8;
}