// Copyright 2024 MOIA GmbH

syntax = "proto3";

package moia.fleet.maps.v1beta1;

option go_package = "./mapv1beta1";
option java_multiple_files = false;
option java_outer_classname = "MapServiceV1Beta1";
option java_package = "io.moia.protos.fleet.maps.v1beta1";

// This service provides methods to query the MOIA map.
service MapService {
  // List all stoppable locations at given coordinates.
  rpc ListStoppableLocations(ListStoppableLocationsRequest) returns (ListStoppableLocationsResponse);
}

// Request to list stoppable locations at given coordinates.
message ListStoppableLocationsRequest {
  // The (customers) location where to pick up or drop off.
  StaticLocation desired_location = 1;
  // Radius in meters from the desired location.
  double radius_meters = 2;
  // The maximum number of locations to return (default 50).
  optional int32 page_size = 3;
  // A page token, received from a previous `ListStoppableLocationsRequest` call.
  // Provide this to retrieve the subsequent page.
  optional string page_token = 4;
  // Identifies the operating area and thus the region to be queried in the context of multi-tenancy.
  // If left empty, the system will try to infer the region based on the desired location.
  string operating_area_id = 5;
}

// Response containing stoppable locations near given coordinates.
message ListStoppableLocationsResponse {
  // All suitable stoppable locations within the specified radius, sorted in ascending order by the distance to the desired
  // location (as the crow flies).
  repeated StoppableLocation stoppable_locations = 1;
  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  optional string next_page_token = 2;
}

// Static location characterized by geographic coordinates and heading.
message StaticLocation {
  // The latitude in degrees.
  // [-90.0, +90.0].
  // Required
  double latitude = 1;
  // The longitude in degrees.
  // [-180.0, +180.0].
  // Required
  double longitude = 2;
  // The horizontal direction of travel in degrees, measured clockwise from north.
  // [0.0-360.0°, 0.0° = facing north, 180.0° = facing south]
  optional double heading = 3;
}

// Stoppable Location represents a location on the road where an AD vehicle can stop to pick up or drop off passengers.
message StoppableLocation {
  // Location of the vehicle on the street suitable for pickup/drop-off.
  StaticLocation vehicle_location = 1;
  // Distance from the desired location (as the crow flies).
  double distance_meters = 2;
  // Point-Of-Interest name or street address, e.g. Chase Center or 3 Warrior Way.
  string name = 3;
  // The road category of the street segment where the stoppable location is located.
  RoadCategory road_category = 4;
  // Whether the street segment where the stoppable location is located is a one-way street.
  bool oneway_street = 5;
}

// RoadCategory divides road segments into four basic groups.
enum RoadCategory {
  // a special value to indicate that a field is not set.
  ROAD_CATEGORY_UNSPECIFIED = 0;
  // a major road with the maximum legal speed limit that runs between larger cities, states or countries.
  ROAD_CATEGORY_HIGHWAY = 1;
  // a major road with a faster speed limit that runs through urban areas or between cities.
  ROAD_CATEGORY_MAIN = 2;
  // a public road that runs through a city or neighborhood, or connects small towns with each other.
  ROAD_CATEGORY_LOCAL_ACCESS = 3;
  // a public road that allows vehicular access to apartment buildings, businesses or public facilities alongside it.
  ROAD_CATEGORY_RESIDENTIAL = 4;
  // a public road that allows vehicular access to apartment buildings, businesses or public facilities alongside it (with lower volume and traffic movement).
  ROAD_CATEGORY_RESIDENTIAL_MINOR = 5;
}