// Copyright 2026 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.places.v1;

import "google/api/resource.proto";
import "google/type/localized_text.proto";

option csharp_namespace = "Google.Maps.Places.V1";
option go_package = "cloud.google.com/go/maps/places/apiv1/placespb;placespb";
option java_multiple_files = true;
option java_outer_classname = "AddressDescriptorProto";
option java_package = "com.google.maps.places.v1";
option objc_class_prefix = "GMPSV1";
option php_namespace = "Google\\Maps\\Places\\V1";

// A relational description of a location. Includes a ranked set of nearby
// landmarks and precise containing areas and their relationship to the target
// location.
message AddressDescriptor {
  // Basic landmark information and the landmark's relationship with the
  // target location.
  //
  // Landmarks are prominent places that can be used to describe a location.
  message Landmark {
    // Defines the spatial relationship between the target location and the
    // landmark.
    enum SpatialRelationship {
      // This is the default relationship when nothing more specific below
      // applies.
      NEAR = 0;

      // The landmark has a spatial geometry and the target is within its
      // bounds.
      WITHIN = 1;

      // The target is directly adjacent to the landmark.
      BESIDE = 2;

      // The target is directly opposite the landmark on the other side of the
      // road.
      ACROSS_THE_ROAD = 3;

      // On the same route as the landmark but not besides or across.
      DOWN_THE_ROAD = 4;

      // Not on the same route as the landmark but a single turn away.
      AROUND_THE_CORNER = 5;

      // Close to the landmark's structure but further away from its street
      // entrances.
      BEHIND = 6;
    }

    // The landmark's resource name.
    string name = 1 [
      (google.api.resource_reference) = { type: "places.googleapis.com/Place" }
    ];

    // The landmark's place id.
    string place_id = 2;

    // The landmark's display name.
    google.type.LocalizedText display_name = 3;

    // A set of type tags for this landmark. For a complete list of possible
    // values, see
    // https://developers.google.com/maps/documentation/places/web-service/place-types.
    repeated string types = 4;

    // Defines the spatial relationship between the target location and the
    // landmark.
    SpatialRelationship spatial_relationship = 5;

    // The straight line distance, in meters, between the center point of the
    // target and the center point of the landmark. In some situations, this
    // value can be longer than `travel_distance_meters`.
    float straight_line_distance_meters = 6;

    // The travel distance, in meters, along the road network from the target to
    // the landmark, if known. This value does not take into account the mode of
    // transportation, such as walking, driving, or biking.
    optional float travel_distance_meters = 7;
  }

  // Area information and the area's relationship with the target location.
  //
  // Areas includes precise sublocality, neighborhoods, and large compounds that
  // are useful for describing a location.
  message Area {
    // Defines the spatial relationship between the target location and the
    // area.
    enum Containment {
      // The containment is unspecified.
      CONTAINMENT_UNSPECIFIED = 0;

      // The target location is within the area region, close to the
      // center.
      WITHIN = 1;

      // The target location is within the area region, close to the edge.
      OUTSKIRTS = 2;

      // The target location is outside the area region, but close by.
      NEAR = 3;
    }

    // The area's resource name.
    string name = 1 [
      (google.api.resource_reference) = { type: "places.googleapis.com/Place" }
    ];

    // The area's place id.
    string place_id = 2;

    // The area's display name.
    google.type.LocalizedText display_name = 3;

    // Defines the spatial relationship between the target location and the
    // area.
    Containment containment = 4;
  }

  // A ranked list of nearby landmarks. The most recognizable and nearby
  // landmarks are ranked first.
  repeated Landmark landmarks = 1;

  // A ranked list of containing or adjacent areas. The most recognizable and
  // precise areas are ranked first.
  repeated Area areas = 2;
}