Build a route accounting for fuel or battery charge

In the demo app, you can create a route with automatically added charging and gas stations to ensure that a vehicle has enough fuel or battery charge to travel the entire route. To plot such a route, the app takes into account:

• The distance that the vehicle can travel with the current level of fuel or battery charge.
• Maximum range with a full tank or battery.
• Minimum fuel or charge level that should always remain available.
• The type of connector that the vehicle supports, or the type of fuel.

Description of the algorithmDescription of the algorithm

You can find detailed descriptions of the classes and their implementation in the demo app.
The ability to create a route that takes into account the fuel or battery charge levels is not implemented within the NaviKit SDK, but is provided as an option for using the NaviKit SDK. You're free to copy and modify the algorithm to implement your business logic.

Input parametersInput parameters

SmartRouteOptions structure description.

data class SmartRouteOptions(
    val chargingType: ChargingType,
    val fuelConnectorTypes: Set<FuelConnectorType>,
    val maxTravelDistanceInMeters: Double,
    val currentRangeLvlInMeters: Double,
    val thresholdDistanceInMeters: Double,
    val drivingOptions: DrivingOptions,
    val vehicleOptions: VehicleOptions,
)

• chargingType — ELECTRO or GASOLINE engine type.
• fuelConnectorTypes — Types of connectors. You can find the complete list of supported fuel types and connectors in the FuelConnectorType.kt file of the demo app.
• maxTravelDistanceInMeters — The maximum number of meters that the vehicle can travel with a full tank or battery charge.
• currentRangeLvlInMeters — The maximum number of meters that the vehicle can travel with the current tank of gas or battery charge.
• thresholdDistanceInMeters — The threshold value of the number of meters below which the fuel tank or battery charge should not drop.
• drivingOptions — DrivingOptions object for taking into account toll, unpaved, bad, and other road types.
• vehicleOptions — VehicleOptions for taking into account vehicle parameters.

Output parametersOutput parameters

SmartRouteResult structure description.

sealed class SmartRouteResult {
    data class Success(
        val points: List<SmartRoutePoint>,
        val finishRangeLvlInMeters: Double
    ) : SmartRouteResult()

    data class Error(
        val reason: String,
        val error: Exception? = null
    ) : SmartRouteResult()
}

sealed class SmartRoutePoint {
    abstract val point: RequestPoint
    data class ChargingPoint(override val point: RequestPoint, val geoObject: GeoObject) : SmartRoutePoint()
    data class RegularPoint(override val point: RequestPoint) : SmartRoutePoint()
}

When a route is successfully created, you'll receive the code SmartRouteResult.Success along with the following data:

• points — List of SmartRoutePoint objects with one of two types:
  • Gas or charging stations SmartRoutePoint.ChargingPoint. It contains a GeoObject with information about gas and charging stations.
  • Custom intermediate points that were passed to the algorithm as an input to SmartRoutePoint.RegularPoint.
• finishRangeLvlInMeters — The number of meters the vehicle will be able to travel after arriving at the destination.

If the route couldn't be created, you'll receive the code SmartRouteResult.Error.

Route plotting algorithmRoute plotting algorithm

When creating a route with automatically added gas and charging stations, the following sequence applies:

1. The SmartRouteOptions and SmartRoutePlanningFactory objects are created.
2. SmartRoutePlanningFactory.requestRoutes is called with the relevant list of intermediate points.
3. The response from the algorithm is processed. The response will contain a list of custom intermediate points, as well as gas and charging stations.
4. The route is created using Navigation.requestRoutes based on the points from the algorithm's response.

val smartRouteOptions = SmartRouteOptions(...) 
val smartRoutePlannigFactory = SmartRoutePlanningFactoryImpl(...)
val result = smartRoutePlannigFactory.requestRoutes(
    points,
    smartRouteOptions
)
// Handle result

Algorithm for finding intermediate points for the routeAlgorithm for finding intermediate points for the route

1. A route is built using DrivingRouter, specifying the start, destination, and intermediate points.
2. Given the input parameters (current range, maximum range, and so on), the farthest segment of the route reachable by the vehicle is calculated.
3. SearchManager is used to search for a gas or charging station that's closest to the end of the calculated segment.
4. The found station is saved. The algorithm sets the vehicle's location as the projection of the charging station onto the polyline of the route.
5. The algorithm starts over from step 2 and stops when there's enough fuel or battery charge to travel the entire route.