Routing

You can use the MapKit SDK to build optimal routes through waypoints. Routes work around parameters and your vehicle's features.

Request route buildingRequest route building

1. Create an instance of the DrivingRouter class.

   val drivingRouter = DirectionsFactory.getInstance().createDrivingRouter()
   

2. Set route-building parameters using the DrivingOptions class.

   Example of creating route parameters to request three routes.

   val drivingOptions = DrivingOptions().apply {
       routesCount = 3
   }
   

3. Use the VehicleOptions class to define vehicle parameters.

   val vehicleOptions = VehicleOptions()
   

4. Create a new route-building session using the DrivingRouter.requestRoutes method.

   Example of a request to build a route between two points.

   val points = buildList {
       add(RequestPoint(Point(25.196141, 55.278543), RequestPointType.WAYPOINT, null))
       add(RequestPoint(Point(25.171148, 55.238034), RequestPointType.WAYPOINT, null))
   }
   
   val drivingSession = drivingRouter.requestRoutes(
       points,
       drivingOptions,
       vehicleOptions,
       drivingRouteListener
   )
   

5. Use the following mechanism to get the to get the route building results.

   Create an instance of DrivingRouteListener interface:

   val drivingRouteListener = object : DrivingRouteListener {
       override fun onDrivingRoutes(drivingRoutes: MutableList<DrivingRoute>) {
           // Handle request routes success ...
       }
   
       override fun onDrivingRoutesError(error: Error) {
           // Handle request routes error ...
       }
   }
   

   Pass an implementation of this interface as an argument whenever you call a method for creating a route-building session.

Route building parametersRoute building parameters

You can set the following route-building parameters using the DrivingOptions class:

• initialAzimuth: Sets the direction of travel at the route starting point to determine whether the user needs to make a U-turn and whether the vehicle is on the with-flow or oncoming lane.
• routesCount: The number of alternative routes.
• avoidTolls: Instructs the router to avoid toll roads.
• avoidPoorConditions: Instructs the router to avoid bad roads where possible.
• avoidUnpaved: Instructs the router to avoid unpaved roads where possible.
• departureTime: Departure time.

Vehicle parametersVehicle parameters

Using the VehicleOptions class, you can set the user's type of vehicle. The supported VehicleType vehicle types are:

• Standard (passenger car).
• Truck.
• Motorcycle.

The route is built based on the selected vehicle's features. Routes may be different for different vehicles. For example, routes for trucks will be adjusted to comply with their restrictions.

Truck restrictions include:

• Dimensions: height, length, and width.
• Mass: total mass, suspension weight, maximal allowed weight limit, and so on.
• Whether the vehicle has a trailer, the vehicle's eco class.

Route-building sessionRoute-building session

Use the DrivingRouter.requestRoutes method to create a new route-building session. Routes are built based on the list of points passed as the first argument.

There are two types of route points:

1. WAYPOINT - used for start and destination points. These include the departure, destination, and intermediate stops.
2. VIAPOINT - used to correct the route. The route must pass through all the via points.

A route request session will be created as a result of calling the DrivingRouter.requestRoutes method. The route-building session is represented by the DrivingSession class. Using it, you can manage the status of the route request process via the following methods:

• retry - relaunch the route-building request.
• cancel - cancel the current request.

Route resultsRoute results

Use a subscription to the DrivingRouteListener interface to receive the results of route-building requests. Pass an implementation of this interface when calling the DrivingRouter.requestRoutes method to create a route-building session.

Two handler method types are supported:

1. onDrivingRoutes - routes built, provides the list of resulting routes of type DrivingRoute.

2. onDrivingRoutesError - notifies that routes couldn't be built.

Requests information about routes without geometryRequests information about routes without geometry

In addition to the route-building functionality, the DrivingRouter class is also used to retrieve information about routes. This request is a simplified version of the route-building request. As a result, data on route geometry, which consumes the most resources when transmitted over the internet, is not passed. It is used in scenarios where you need to build a route that does not have to be displayed on a map. For example, that might be identifying potential route distances or travel times.

You can get the following information about routes using the DrivingRouter.requestRoutesrequestRoutesSummary method:

• Distance.
• Route duration including and excluding traffic jams.
• The list of Flags that describe the route, including whether there are toll roads, ferry crossings, or parking lots.

You can get the results for route summary requests using the DrivingSummaryListener. It's passed as an argument when calling the DrivingRouter.requestRoutesrequestRoutesSummary method.

Source codeSource code

You can see more examples of how to use the API in the map-routing demo app, which is found in our GitHub repository.