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 YMKDrivingRouter class.

   let drivingRouter: YMKDrivingRouter = YMKDirections.sharedInstance().createDrivingRouter(withType: .combined)
   

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

   Example of creating route parameters to request three routes.

   let drivingOptions: YMKDrivingOptions = {
       let options = YMKDrivingOptions()
       options.routesCount = 3
       return options
   }()
   

3. Use the YMKDrivingVehicleOptions class to define vehicle parameters.

   let vehicleOptions = YMKDrivingVehicleOptions()
   

4. Create a new route-building session using the YMKDrivingRouter.requestRoutes(with:drivingOptions:vehicleOptions:routeHandler:) method.

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

   let points = [
       YMKRequestPoint(point: YMKPoint(latitude: 25.196141, longitude: 55.278543), type: .waypoint, pointContext: nil, drivingArrivalPointId: nil),
       YMKRequestPoint(point: YMKPoint(latitude: 25.171148, longitude: 55.238034), type: .waypoint, pointContext: nil, drivingArrivalPointId: nil)
   ]
   
   let drivingSession = drivingRouter.requestRoutes(
       with: requestPoints,
       drivingOptions: drivingOptions,
       vehicleOptions: vehicleOptions,
       routeHandler: drivingRouteHandler
   )
   

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

   Create an instance of YMKDrivingSessionRouteHandler:

   func drivingRouteHandler(drivingRoutes: [YMKDrivingRoute]?, error: Error?) {
       if let error {
           // Handle request routes error
           return
       }
   
       guard let drivingRoutes else {
           return
       }
   
       // Handle request routes success
   }
   

   Pass this handler method 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 YMKDrivingOptions 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 YMKDrivingVehicleOptions class, you can set the user's type of vehicle. The supported YMKDrivingVehicleType 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 YMKDrivingRouter.requestRoutes(with:drivingOptions:vehicleOptions:routeHandler:) 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 YMKDrivingRouter.requestRoutes(with:drivingOptions:vehicleOptions:routeHandler:) method. The route-building session is represented by the YMKDrivingSession 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 handler of type YMKDrivingSessionRouteHandler interface to receive the results of route-building requests. Pass this object as a routeHandler parameter when calling the YMKDrivingRouter.requestRoutes(with:drivingOptions:vehicleOptions:routeHandler:) method to create a route-building session.

This handler takes two arguments:

1. drivingRoutes - says that routes were built, contains the list of resulting routes YMKDrivingRoute.

2. error - says 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 YMKDrivingRouter 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 YMKDrivingRouter.requestRoutesSummary(with:drivingOptions:vehicleOptions:summaryHandler:) method:

• Distance.
• Route duration including and excluding traffic jams.
• The list of YMKDrivingFlags 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 YMKDrivingSummarySessionSummaryHandler. It's passed as an argument when calling the YMKDrivingRouter.requestRoutesSummary(with:drivingOptions:vehicleOptions:summaryHandler:) method.

Source codeSource code

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