// 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.navconnect.v1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/field_info.proto";
import "google/api/resource.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
import "google/type/latlng.proto";

option go_package = "cloud.google.com/go/maps/navconnect/apiv1/navconnectpb;navconnectpb";
option java_multiple_files = true;
option java_outer_classname = "NavConnectServiceProto";
option java_package = "com.google.maps.navconnect.v1";

// Service for NavConnect clients to create and get trips.
service NavConnectService {
  option (google.api.default_host) = "navigationconnect.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Creates a trip. This must be called before the mobile application can start
  // the trip. The returned trip will have the `auth_token` field set.
  rpc CreateTrip(CreateTripRequest) returns (Trip) {
    option (google.api.http) = {
      post: "/v1/{parent=projects/*}/trips"
      body: "trip"
    };
    option (google.api.method_signature) = "parent,trip,trip_id";
  }

  // Gets a trip.
  rpc GetTrip(GetTripRequest) returns (Trip) {
    option (google.api.http) = {
      get: "/v1/{name=projects/*/trips/*}"
    };
    option (google.api.method_signature) = "name";
  }
}

// A trip.
message Trip {
  option (google.api.resource) = {
    type: "navconnect.googleapis.com/Trip"
    pattern: "projects/{project}/trips/{trip}"
    plural: "trips"
    singular: "trip"
  };

  // All possible trip states.
  enum State {
    // The trip state is unspecified.
    STATE_UNSPECIFIED = 0;

    // The trip was created but has not yet started.
    NEW = 1;

    // The transporter is enroute to the destination.
    ENROUTE = 2;

    // The transporter arrived at the destination.
    ARRIVED = 3;

    // The trip was suspended.
    SUSPENDED = 4;

    // The trip failed to complete successfully.
    FAILED = 5;

    // The trip failed due to a client error.
    CLIENT_ERROR = 6;
  }

  // Output only. Identifier. The resource name of the trip.
  // Format: projects/{project_number}/trips/{trip_id}.
  string name = 1 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.field_behavior) = IDENTIFIER
  ];

  // Immutable. The configuration for the trip.
  TripConfig config = 7 [(google.api.field_behavior) = IMMUTABLE];

  // Input only. Immutable. The Android application ID of the mobile application
  // that will use the trip. At least one of `android_app_id` or `ios_app_id`
  // must be set.
  string android_app_id = 8 [
    (google.api.field_behavior) = INPUT_ONLY,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Input only. Immutable. The iOS bundle ID of the mobile application that
  // will use the trip. At least one of `android_app_id` or `ios_app_id` must be
  // set.
  string ios_app_id = 9 [
    (google.api.field_behavior) = INPUT_ONLY,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Output only. An opaque token that authorizes access to begin a NavConnect
  // trip in Google Maps or Waze and grants these applications access to update
  // the trip. Only returned by `CreateTrip`.
  AuthToken auth_token = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The Trip state.
  State state = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The latest data about the execution of the trip. This may not
  // be set if the trip is in an error state.
  TripExecution execution = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Time according to the server when the trip was created.
  google.protobuf.Timestamp create_time = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Time at which the server received the latest trip update.
  google.protobuf.Timestamp update_time = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Configuration for the trip.
message TripConfig {
  // Optional. Whether to enable high-frequency trip updates.
  //
  // NOTE: Enabling this feature logs the trip under Enterprise Tier usage, and
  // is subject to Enterprise Tier rates.
  bool enable_high_frequency_updates = 1
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Whether to enable pubsub notifications for the trip.
  bool enable_pubsub = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. If set, only the specified subset of the Trip fields will be
  // included in the pubsub notifications.
  //
  // If not set, all Trip fields will be included in the pubsub notifications
  // (default behavior).
  //
  // The following fields are not supported:
  //
  // * `android_app_id`
  // * `ios_app_id`
  // * `auth_token`
  // * `config`
  //
  // NOTE: This field is ignored if `enable_pubsub` is false.
  google.protobuf.FieldMask pubsub_field_mask = 3
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Whether to enable remaining route reporting for the trip.
  //
  // NOTE: Enabling this feature logs the trip under Enterprise Tier usage, and
  // is subject to Enterprise Tier rates.
  bool enable_remaining_route_reporting = 4
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Whether to enable route deviation reporting for the trip.
  //
  // NOTE: Enabling this feature logs the trip under Enterprise Tier usage, and
  // is subject to Enterprise Tier rates.
  bool enable_route_deviation_reporting = 5
      [(google.api.field_behavior) = OPTIONAL];
}

// An authentication token.
message AuthToken {
  // Output only. The authentication token that should be passed to the mobile
  // application.
  string token = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Time at which the authentication token will expire.
  google.protobuf.Timestamp expire_time = 2
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Data about the execution of the trip.
message TripExecution {
  // Output only. Origin of the trip which is generally the transporter's
  // location at start of the NavConnect trip.
  Location origin = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The destination of the trip as reported by the mobile
  // application.
  Stop destination = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The location signal representing the last known location of
  // the transporter. This will be the road snapped location if available.
  Location location = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Provides the polyline for the remaining portion of the route.
  Route remaining_route = 9 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The most recent route deviation event captured during the
  // trip.
  RouteDeviation last_route_deviation = 10
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Time traveled thus far.
  google.protobuf.Duration traveled_duration = 4
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Time left on this trip as estimated by Google.
  google.protobuf.Duration remaining_duration = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Distance traveled from the origin in meters.
  optional int32 traveled_distance_meters = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Distance remaining to the destination in meters.
  optional int32 remaining_distance_meters = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Indicates whether a stop was added along the route.
  optional bool stop_added_in_route = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Route deviation information.
message RouteDeviation {
  // The source that triggered the route deviation.
  enum TriggerSource {
    // The trigger source is unspecified.
    TRIGGER_SOURCE_UNSPECIFIED = 0;

    // The route deviation was triggered by the driver (e.g. wrong turn).
    DRIVER_INITIATED_REROUTE = 1;

    // The route deviation was triggered by the system (e.g. traffic closure).
    SYSTEM_INITIATED_REROUTE = 2;
  }

  // Output only. Location where the deviation occurred.
  Location location = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Source for the deviation trigger.
  TriggerSource source = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// A stop in the trip where some task is to be performed.
message Stop {
  // Required. The location of the stop as a lat/lng.
  google.type.LatLng point = 1 [(google.api.field_behavior) = REQUIRED];
}

// A location as reported by the mobile application.
message Location {
  // Output only. The location lat/lng.
  google.type.LatLng point = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time when the location was sourced as denoted by the
  // client.
  google.protobuf.Timestamp source_time = 2
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time at which the server received this location update.
  google.protobuf.Timestamp server_time = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Represents a polyline using a simple list of points.
message SimplePolyline {
  // Output only. Ordered list of points representing the polyline.
  repeated google.type.LatLng points = 1
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Traffic density indicator on a contiguous segment of a path. Given a path
// with points P_0, P_1, ... , P_N (zero-based index), the SpeedReadingInterval
// defines an interval and describes its traffic using the `Speed` categories.
message SpeedReadingInterval {
  // The classification of polyline speed based on traffic data.
  enum Speed {
    // The speed is unspecified.
    SPEED_UNSPECIFIED = 0;

    // Normal speed, no traffic delays.
    NORMAL = 1;

    // Slowdown detected, light to medium amount of traffic.
    SLOW = 2;

    // Traffic delays, including standstill traffic.
    TRAFFIC_JAM = 3;
  }

  // Output only. The starting index of this interval in the path.
  optional int32 start_polyline_point_index = 1
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The ending index of this interval in the path.
  optional int32 end_polyline_point_index = 2
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Traffic speed in this interval.
  Speed speed = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// A route polyline.
message Route {
  // The route format.
  //
  // The format populated is controlled by the `route_polyline_format`
  // parameter. If not set, it defaults to a simple polyline.
  oneof format {
    // Output only. The route as a simple list of latlngs.
    SimplePolyline simple_polyline = 1
        [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The route as an encoded polyline.
    // See
    // https://developers.google.com/maps/documentation/utilities/polylinealgorithm.
    string encoded_polyline = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The route as an encoded S2Polyline.
    // See https://s2geometry.io/devguide/basic_types.html.
    bytes s2_polyline = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The route as a GeoJSON LineString.
    // See https://tools.ietf.org/html/rfc7946#section-3.1.4.
    google.protobuf.Struct geo_json = 3
        [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Output only. Traffic information on the polyline described as speed reading
  // intervals.
  //
  // NOTES:
  //
  // * The intervals are non-overlapping.
  // * The intervals are contiguous.
  // * The intervals cover the entire polyline.
  // * The intervals are sorted by increasing index.
  // * Speed is specified for each interval.
  repeated SpeedReadingInterval traffic_information = 4
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Request message for NavConnectService.CreateTrip.
message CreateTripRequest {
  // Required. The parent resource under which this trip will be created.
  // Format: projects/{project_number}
  string parent = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The ID to use for the trip, which will become the final component
  // of the trip's resource name.
  //
  // This value must be a valid RFC-4122 UUID.
  string trip_id = 2 [
    (google.api.field_info).format = UUID4,
    (google.api.field_behavior) = REQUIRED
  ];

  // Required. The trip to create.
  Trip trip = 3 [(google.api.field_behavior) = REQUIRED];
}

// Request message for NavConnectService.GetTrip.
message GetTripRequest {
  // Specifies the format of the route polyline.
  enum RoutePolylineFormat {
    // The route polyline format is unspecified.
    ROUTE_POLYLINE_FORMAT_UNSPECIFIED = 0;

    // The route polyline is returned as a simple array of points represented as
    // `google.type.LatLng`.
    SIMPLE = 1;

    // The route polyline is returned as an encoded string.
    // See
    // https://developers.google.com/maps/documentation/utilities/polylinealgorithm.
    ENCODED = 4;

    // The route polyline is encoded as a S2Polyline.
    // See https://s2geometry.io/devguide/basic_types.html.
    S2ENCODED = 2;

    // The route polyline is returned as a GeoJSON LineString.
    // See https://tools.ietf.org/html/rfc7946#section-3.1.4.
    GEO_JSON = 3;
  }

  // Required. The resource name of the trip to get.
  // Format: projects/{project}/trips/{trip_id}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "navconnect.googleapis.com/Trip" }
  ];

  // Optional. The format of the route polyline to return.
  // If not set, `SIMPLE` route polyline will be returned.
  RoutePolylineFormat route_polyline_format = 2
      [(google.api.field_behavior) = OPTIONAL];
}