From 275eb1955ca5af1a0942f4e91d47409ad0e4f806 Mon Sep 17 00:00:00 2001
From: Google APIs <noreply@google.com>
Date: Thu, 25 Jun 2020 12:00:50 -0700
Subject: [PATCH] Updated documentation of route modifiers. Introduction of the
 documentation of speed reading intervals.

PiperOrigin-RevId: 318318689
---
 .../routes/v1/compute_routes_request.proto    | 19 +++++---
 google/maps/routes/v1/route.proto             | 45 +++++++++++++++++++
 2 files changed, 57 insertions(+), 7 deletions(-)

diff --git a/google/maps/routes/v1/compute_routes_request.proto b/google/maps/routes/v1/compute_routes_request.proto
index 05859908..88be1bf7 100644
--- a/google/maps/routes/v1/compute_routes_request.proto
+++ b/google/maps/routes/v1/compute_routes_request.proto
@@ -40,7 +40,8 @@ message ComputeRoutesRequest {
   Waypoint destination = 2;
 
   // Optional. A set of waypoints along the route (excluding terminal points),
-  // for either stopping at or passing by.
+  // for either stopping at or passing by. Up to 25 intermediate waypoints are
+  // supported.
   repeated Waypoint intermediates = 3;
 
   // Optional. Specifies the mode of transportation.
@@ -130,20 +131,24 @@ enum RoutingPreference {
 // Encapsulates a set of optional conditions to satisfy when calculating the
 // routes.
 message RouteModifiers {
-  // Specifies whether to avoid toll roads. Applies only to the `DRIVE` and
+  // Specifies whether to avoid toll roads where reasonable. Preference will be
+  // given to routes not containing toll roads. Applies only to the `DRIVE` and
   // `TWO_WHEELER` travel modes.
   bool avoid_tolls = 1;
 
-  // Specifies whether to avoid highways. Applies only to the `DRIVE` and
+  // Specifies whether to avoid highways where reasonable. Preference will be
+  // given to routes not containing highways. Applies only to the `DRIVE` and
   // `TWO_WHEELER` travel modes.
   bool avoid_highways = 2;
 
-  // Specifies whether to avoid ferries. Applies only to the `DRIVE` and
-  // `TWO_WHEELER` travel modes.
+  // Specifies whether to avoid ferries where reasonable. Preference will be
+  // given to routes not containing travel by ferries.
+  // Applies only to the `DRIVE` and`TWO_WHEELER` travel modes.
   bool avoid_ferries = 3;
 
-  // Specifies whether to avoid navigating indoors. Applies only to the `WALK`
-  // travel mode.
+  // Specifies whether to avoid navigating indoors where reasonable. Preference
+  // will be given to routes not containing indoor navigation.
+  // Applies only to the `WALK` travel mode.
   bool avoid_indoor = 4;
 
   // Optional. Specifies the vehicle information.
diff --git a/google/maps/routes/v1/route.proto b/google/maps/routes/v1/route.proto
index 119853ad..5b3e3884 100644
--- a/google/maps/routes/v1/route.proto
+++ b/google/maps/routes/v1/route.proto
@@ -88,6 +88,16 @@ message RouteTravelAdvisory {
   // we expect that road contains tolls but we do not know an estimated price.
   // If this field is not set, then we expect there is no toll on the Route.
   TollInfo toll_info = 2;
+
+  // Speed reading intervals detailing traffic density. Applicable in case of
+  // TRAFFIC_AWARE and TRAFFIC_AWARE_OPTIMAL routing preferences.
+  // The intervals cover the entire polyline of the route without overlaps, i.e.
+  // the start point of a given interval coincides with the end point of the
+  // preceding interval.
+  // Example:
+  //   polyline: A ---- B ---- C ---- D ---- E ---- F ---- G
+  //   speed_reading_intervals: [A,C),  [C,D), [D,G).
+  repeated SpeedReadingInterval speed_reading_intervals = 3;
 }
 
 // Encapsulates the additional information that the user should be informed
@@ -261,3 +271,38 @@ enum Maneuver {
   // Turn right at the roundabout.
   ROUNDABOUT_RIGHT = 18;
 }
+
+// Traffic density indicator on a contiguous segment of a polyline.
+// Given a polyline with polyline points P_0, P_1, ... , P_N
+// (the indexing is zero-based), the SpeedReadingInterval defines an
+// interval (including the start, exclusing the end point) and describes the
+// traffic density on the respective interval using the below style categories.
+message SpeedReadingInterval {
+  // The classification of polyline speed based on traffic data.
+  enum Speed {
+    // Default value. This value is unused.
+    SPEED_UNSPECIFIED = 0;
+
+    // Normal speed, no slowdown is detected.
+    NORMAL = 1;
+
+    // Slowdown detected, but no traffic jam formed.
+    SLOW = 2;
+
+    // Traffic jam detected.
+    TRAFFIC_JAM = 3;
+  }
+
+  // The index of the starting polyline point of the interval
+  // in the ordered list of polyline points.
+  // In JSON, when the index is 0, the field will appear to be unpopulated.
+  int32 start_polyline_point_index = 1;
+
+  // The index of the ending polyline point of the interval
+  // (with off-by-one ending) in the ordered list of polyline points.
+  // In JSON, when the index is 0, the field will appear to be unpopulated.
+  int32 end_polyline_point_index = 2;
+
+  // Traffic information speed at the interval.
+  Speed speed = 3;
+}