// Copyright 2023 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
//
//     https://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.type;

option go_package = "google.golang.org/genproto/googleapis/type/latlng;latlng";
option java_package = "com.google.type";
option java_outer_classname = "LatLngProto";
option java_multiple_files = true;
option objc_class_prefix = "GTP";
option cc_enable_arenas = true;

// An object that represents a latitude/longitude pair. This is expressed as a
// pair of doubles to represent degrees latitude and degrees longitude. Unless
// specified otherwise, this object must conform to the
// <a href="https://en.wikipedia.org/wiki/World_Geodetic_System#1984_version">
// WGS84 standard</a>. Values must be within normalized ranges.
// (-- An API may allow wider ranges in which case it must convert them to
//  normalized values.
//
// Example of normalization code in Python:
//
//     def normalize_longitude(longitude):
//       """Wraps decimal degrees longitude to [-180.0, 180.0]."""
//       q, r = divmod(longitude, 360.0)
//       if r > 180.0 or (r == 180.0 and q <= -1.0):
//         return r - 360.0
//       return r
//
//     def normalize_lat_lng(latitude, longitude):
//       """Wraps decimal degrees latitude and longitude to
//       [-90.0, 90.0] and [-180.0, 180.0], respectively.
//       """
//       r = latitude % 360.0
//       if r <= 90.0:
//         return r, normalize_longitude(longitude)
//       elif r >= 270.0:
//         return r - 360, normalize_longitude(longitude)
//       else:
//         return 180 - r, normalize_longitude(longitude + 180.0)
//
//     assert 180.0 == normalize_longitude(180.0)
//     assert -180.0 == normalize_longitude(-180.0)
//     assert -179.0 == normalize_longitude(181.0)
//     assert (0.0, 0.0) == normalize_lat_lng(360.0, 0.0)
//     assert (0.0, 0.0) == normalize_lat_lng(-360.0, 0.0)
//     assert (85.0, 180.0) == normalize_lat_lng(95.0, 0.0)
//     assert (-85.0, -170.0) == normalize_lat_lng(-95.0, 10.0)
//     assert (90.0, 10.0) == normalize_lat_lng(90.0, 10.0)
//     assert (-90.0, -10.0) == normalize_lat_lng(-90.0, -10.0)
//     assert (0.0, -170.0) == normalize_lat_lng(-180.0, 10.0)
//     assert (0.0, -170.0) == normalize_lat_lng(180.0, 10.0)
//     assert (-90.0, 10.0) == normalize_lat_lng(270.0, 10.0)
//     assert (90.0, 10.0) == normalize_lat_lng(-270.0, 10.0) --)
//
// (-- The code in logs/storage/validator/logs_validator_traits.cc treats this
// type as if it were annotated as ST_LOCATION. --)
message LatLng {
  // The latitude in degrees. It must be in the range [-90.0, +90.0].
  // (-- An API may allow a wider range and must convert them to normalized
  //  values. --)
  double latitude = 1;

  // The longitude in degrees. It must be in the range [-180.0, +180.0].
  // (-- An API may allow a wider range and must convert them to normalized
  //  values. --)
  double longitude = 2;
}