Route alternatives (aka FasterRoute v2)

[kmadsen]

Description

Addressing feedback on Faster Route and making a more flexible interface and feature called Route Alternatives. Resolves #4233.

Surfaces the ability to continuously monitor route alternatives, migrates the options interface to be consistent with other features, and showcases an integration test. More details in this comment

• Migrate to the route alternatives interface
• Migrate to the options pattern
• Surface native function to compare routes
• Build an integration test
• Comments and cleanup

Changelog

<changelog>Add ability to periodically observe route alternatives. Deleted `FasterRouteObserver` in favor of `RouteAlternativesObserver` and `RouteAlternativesOptions`.</changelog>

Screenshots or Gifs

Pictures of the routes on the instrumentation test. The test is initialized with the slower route, the faster alternative will periodically refresh.

Original	Alternative

rendering-alternatives.mp4

[kmadsen]

What's in review

• RouteAlternativeOptions allow you to update a simple interval that the alternatives are requested - this could be done before but there has been confusion of how to do so.
• The route alternatives are surfaced through the RouteAlternativeObserver with the current route filtered
• Expose a isDifferentRoute function that allows you to compare cached routes or create "rejected lists" NOPE: Route alternatives (aka FasterRoute v2) #4375 (comment)
• Created an instrumentation test to showcase how you can test faster route with ci systems

Should we add it now? - explicit call to request alternatives

Right now there is a set interval to request alternatives periodically. But we could expose a function to force it to trigger "out of interval". The function is already available in the RouteAlternativesController, we could surface it through MapboxNavigation. One side effect of this trigger, would be that the current intervaled request would be canceled - causing potentially wasted requests and more frequent cancels.

Out of scope - road aware alternative requests

Similar to explicitly requesting explicitly. Considering how we could use the road information to determine when to request route alternatives (approaching intersections, enter highway, exit highway, ...). This sounds good but considering it out of scope because I'd like to scope it with nav native.

Also we want to consider that, once the road tiles have been downloaded for things like EHorizon, the directions api request is not even needed. The onboard router is able to fulfill the request for alternatives - meaning a simple fast interval is also worth considering under these conditions.

Out of scope - alternative route progress

Similar to how the current route has progress. A driver will be making progress on an alternative route. This will impact how a alternative route lines are shown on the map while driving. This is considered out of scope of the current change, because it will not impact the current interface being designed. Continuously showing alternative routes will be addressed after integrating this interface.

[LukasPaczos]

Looking good so far!

Should we add it now? - explicit call to request alternatives

I'm on the fence. Sounds like a great tool to give developers more flexibility and control when the request is triggered to build a UX around it. If we do that, we should add an option to disable the automatic alternative routes requests (RouteAlternativesOptions#enabled) so that developers can fully own this. However, if we do that, we still need to have some kind of a throttling mechanism so that we do not allow for flooding our APIs too easily. cc @jyrigo @AhmerKhan1 for visibility.

Expose a isDifferentRoute function that allows you to compare cached routes or create "rejected lists"

Could you give an example of how to build that rejected list? What would be the criteria? There is one feature that I think we might be missing for this to be possible, like Navigator#isDifferentRoute(route1, route2).

[LukasPaczos]

Isn't that too often? I'm worried about the overhead that developers could even unintentionally cause.

[abhishek1508]

I agree. What about battery power consumption?

[kmadsen]

Our default value is 5 minutes. The minimum allowed is 10 seconds. Customer feedback is typically, asking for lower lower thresholds.

For what it's worth, Lyft requested directions from Google once every 5 seconds in their driver app. Battery was not a concern because drivers are always plugged in.

[LukasPaczos]

I'm thinking more in terms of not flooding Directions API.

@kshehadeh @danpat we're reworking here a feature that periodically requests alternative routes (by making a new route request). What would be your recommendation for a minimal interval between those requests?

[danpat]

@LukasPaczos Rather than hard-coding a refresh interval, I would do the following:

• Examine the Cache-Control header and look at the max-age value. Set the refresh timer to trigger when max-age runs out.
• If max-age is not set, look for an Expires header - if set, set the fresh timer to trigger when Expires occurs.
• If neither header is set, use 60 seconds.

We do set Cache-Control on all API responses currently, and intend to do so indefinitely. Using these headers will allow us to optimize the experience for all customers without triggering excessive refresh requests at a resolution greater than our traffic/incident data is updating.

[kmadsen]

@danpat just to clarify, because it's not about a route expiring. It's considering active guidance. This is different from a refresh interval. This is, examining the alternatives while in-route. So the origin location is changing.

For example, I just used Google's version of this. I was driving and there was a truck blocking the street. I looked at my phone and saw I had an alternative with a similar ETA by turning right a few meters ahead. Keeping track of these alternatives, is not about the age of the route - they expire when your location changes.

[abhishek1508]

Continuously showing alternative routes when you are driving to a destination will be addressed after integrating this interface.

I think we should cut a ticket for this feature so that we don't forget.

cc @kmadsen

[abhishek1508]

Looking at the code in a first glance, there are 2 questions that come to my mind:

• Route Alternatives: is it same as alternative routes that you receive when you request the route for first time by setting RouteOptions.Builder().alternatives(true).build()
• RouteAlternativeObserver: As a user do I need to register this observer to receive alternative routes the first time when I request a route with the above RouteOptions
• RouteRefresh vs RouteAlternative: Reading the description of RouteAlternative it seems like these are routes that are faster and alternate to the current route you are driving on. If the understanding is correct, what does RouteRefresh do?

I guess my point is that we need to choose the nomenclature carefully as I think this is gonna lead to confusion and misinterpretation not only between customers but internally b/w support teams and TAM's as well.

cc @kmadsen @LukasPaczos

[kmadsen]

Responding to: #4375 (comment) cc: @abhishek1508

Route Alternatives: is it same as alternative routes that you receive when you request the route for first time by setting RouteOptions.Builder().alternatives(true).build()

Good question and not exactly. For example, alternatives(true) causes more than 1 route to be returned. If you have alternatives(false), then the RouteAlternativesObserver.onRouteAlternatives will never respond with more than 1 alternative route.

RouteAlternativeObserver: As a user do I need to register this observer to receive alternative routes the first time when I request a route with the above RouteOptions

Hmm good thought here. If you call MapboxNavigation.requestRoutes(.. alternatives(true) ).. It will not cause the RouteAlternativeObserver to trigger. The RoutesObserver is also capable of returning alternative routes. We could remove RouteAlternativeObserver in favor of only surfacing alternatives through RoutesObserver 🤔 - this is in fact, how we surface route refresh (but developers have asked about separating the callbacks).

RouteRefresh vs RouteAlternative: Reading the description of RouteAlternative it seems like these are routes that are faster and alternate to the current route you are driving on. If the understanding is correct, what does RouteRefresh do?

RouteRefresh only updates the current route's LegAnnotations (aka traffic). RouteAlternatives (FasterRoute) is essentially a MapboxNaivation.requestRoute poller. Which includes more information than traffic. The added logic, is that it accounts for the route progress.

[kmadsen]

Responding to #4375 (review) cc: @LukasPaczos

Should we add it now? - explicit call to request alternatives

I'm on the fence. Sounds like a great tool to give developers more flexibility and control when the request is triggered to build a UX around it. If we do that, we should add an option to disable the automatic alternative routes requests (RouteAlternativesOptions#enabled) so that developers can fully own this. However, if we do that, we still need to have some kind of a throttling mechanism so that we do not allow for flooding our APIs too easily. cc @jyrigo @AhmerKhan1 for visibility.

Good comments and questions. My opinion is that it is not needed for this change. Adding new options and functions will not be a breaking change - so we can continue to discuss and possibly add it in the future. Even as part of a minor version.

Expose a isDifferentRoute function that allows you to compare cached routes or create "rejected lists"

Could you give an example of how to build that rejected list? What would be the criteria? There is one feature that I think we might be missing for this to be possible, like Navigator#isDifferentRoute(route1, route2).

Thanks for the callout here. isDifferentRoute will not help identify previously rejected routes. The code we have to support "rejected lists" could be achieved by revising the RouteComparator.. but here we are deleting it. Worth requesting this from native cc: @SiarheiFedartsou

[kmadsen]

Continuously showing alternative routes when you are driving to a destination will be addressed after integrating this interface.

I think we should cut a ticket for this feature so that we don't forget.

@abhishek1508 https://github.com/mapbox/navigation-sdks/issues/985

[kmadsen]

@LukasPaczos @abhishek1508 An update after the feedback - so this is ready for another round.

• Built a prototype to see how the api could change when adding more functionality from the navigator Prototype route alternatives rendering #4397
• Conclusions: isDifferentRoute doesn't solve external problems so I removed it from this change
• Conclusions: We can consider surfacing alternative route progress through the RouteObserver, but we should think about it more

The changes requested from the native team have a few different approaches. I think this change is still in the direction we want to go in, and we'll be able to follow up with improvements without breaking apis.

What do you think?

[LukasPaczos]

We can consider surfacing alternative route progress through the RouteObserver, but we should think about it more

I'm thinking that we shouldn't. We advertise the RoutesObserver as the source of truth, so developers could receive the RouteAlternativesObserver call and then decide whether they want to accept those alternatives to be displayed, or dismiss them.

When they want to dismiss, they just do nothing.

When they want to display the alternatives, they call MapboxNavigation#setRoutes and swap indices 1 and 2 (if present) for new alternatives. In an ideal setup this change triggers RoutesObserver from which they redraw the route lines using the RouteLineApi.

[stevenm69]

[Stephen Mcclure - Chat @ Spike](https://spikenow.com/r/a/?ref=spike-organic-signature&_ts=11ar0z) [11ar0z] On May 18, 2021 at 17:22 GMT, Kyle Madsen ***@***.***> wrote: @kmadsen commented on this pull request. --------------------------------------------------------------- In [libnavigation-core/src/main/java/com/mapbox/navigation/core/routealternatives/RouteAlternativesController.kt](#4375 (comment)):

+ logger.e( + msg = Message("Route alternatives options are not available"), + tr = routeOptionsResult.error + ) + } + } + } + + private val routesRequestCallback = object : RoutesRequestCallback { + override fun onRoutesReady(routes: List<DirectionsRoute>) { + val routeProgress = tripSession.getRouteProgress() + ?: return + jobControl.scope.launch { + if (tripSession.getState() == TripSessionState.STARTED) { + val alternatives = routes.filter { navigator.isDifferentRoute(it) } + observers.forEach { it.onRouteAlternatives(routeProgress, alternatives) }

As for this fix. https://github.com/mapbox/mapbox-navigation-android/pull/4375/files#diff-9d5de4542e0fc70f55cc5dc3007a2636f073fb9a262f37b906bfcae09b72140eR142 When the routes are set it restarts the interval. Thinking about times when a new route is set and the interval happens to be close to requesting, would cause an inconsistent callback. — You are receiving this because you are subscribed to this thread. Reply to this email directly, [view it on GitHub](#4375 (comment)), or [unsubscribe](https://github.com/notifications/unsubscribe-auth/AR65J23MGGRXWDT2PCYXBBDTOKO33ANCNFSM44RXRWIQ).

[LukasPaczos]

[yunikkk]

Thanks for the callout here. isDifferentRoute will not help identify previously rejected routes.

Our usecase required it specifically to filter current route/routeProgress from the overall list of routes. With new implementation isDifferentRoute seems not necessary with filtered alternatives returned.