syntax = "proto3";

package google.maps.weather.v1;

import "google/api/field_behavior.proto";
import "google/protobuf/timestamp.proto";

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

// Represents the events related to the sun (e.g. sunrise, sunset).
// (-- Next available tag: 3 --)
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).
// (-- Next available tag: 6 --)
message MoonEvents {
  // Marks the moon phase (a.k.a. lunar phase).
  enum Phase {
    // Unspecified moon phase.
    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;
  }
  // The moon phase (a.k.a. lunar phase).
  // (-- aip.dev/not-precedent: Field type changed to nested enum per atomic
  //     transition strategy. Wire-compatible; external consumers
  //     rely exclusively on HTTP REST/JSON where enum strings remain identical.
  //     --)
  Phase moon_phase = 3 [(google.api.field_behavior) = OPTIONAL];

  // 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;

  // (-- Removed google.protobuf.Timestamp moonrise_time. --)
  // (-- Removed google.protobuf.Timestamp moonset_time. --)
  reserved 1, 2;
}

// Marks the moon phase (a.k.a. lunar phase).
// (-- This is a generic (shared) definition because it maybe used as a
// standalone field for other endpoints/new features in the future and it
// already contains all the possible moon phases. --)
// (-- Next available tag: 9 --)
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;
}