Build routes

The entry point to the NaviKit SDK API is the YMKNavigation class. It contains the main functions for navigation and route building.

Create NavigationCreate Navigation

To create new navigation, call YMKNavigationFactory.createNavigation(with:).

let navigation = YMKNavigationFactory.createNavigation(with: .combined)

Request routesRequest routes

With YMKNavigation, you can build optimal routes using intermediate route points.

To request routes, use the YMKNavigation.requestRoutes(with:initialAzimuth:) method.

// Coordinates routes are requested for
let requestPoints = [
    YMKRequestPoint(
        point: YMKPoint(latitude: 25.190614, longitude: 55.265616),
        type: .waypoint,
        pointContext: nil,
        drivingArrivalPointId: nil
    ),
    YMKRequestPoint(
        point: YMKPoint(latitude: 25.187532, longitude: 55.275413),
        type: .waypoint,
        pointContext: nil,
        drivingArrivalPointId: nil
    ),
    YMKRequestPoint(
        point: YMKPoint(latitude: 25.189279, longitude: 55.282246),
        type: .waypoint,
        pointContext: nil,
        drivingArrivalPointId: nil
    ),
    YMKRequestPoint(
        point: YMKPoint(latitude: 25.196605, longitude: 55.280940),
        type: .waypoint,
        pointContext: nil,
        drivingArrivalPointId: nil
    )
]

navigation.requestRoutes(
    with: requestPoints,
    initialAzimuth: navigation.guidance.location?.heading
)

The first argument is the YMKRequestPoint list of coordinates the route passes through.

Route points are divided into two types:

• waypoint: Used for the start and destination points. These include the departure, the destination, and intermediate stops.
• viapoint: Used for correcting the route. The route will pass through all the via points.

The second argument is the YMKDrivingOptions object with the guidance parameters:

• initialAzimuth: Sets the user direction azimuth at the starting point of the route.
• routesCount: The number of routes to build.

To learn how to get the route request results, go to Route request results.

Route request by URIRoute request by URI

In YMKNavigation, you can request a route with the route URI saved earlier using the YMKNavigation.resolveUri(withUri:) method.

To learn how to get the route request results, go to Route request results.

Request alternate routesRequest alternate routes

A list of alternate routes may be built during guidance along the selected route in NaviKit SDK, they're called global alternatives. They need a separate request.

Use the YMKNavigation.requestAlternatives() asynchronous call.

To learn how to get alternate request results, go to Route request results.

EventsEvents

Using the YMKNavigationListener interface, you can subscribe to the YMKNavigation entity to get events related to internal navigation status changes.

Route request resultsRoute request results

The YMKNavigation.requestRoutes(with:initialAzimuth:) and YMKNavigation.requestAlternatives() calls are asynchronous since they use a network request. To process the request results, subscribe to navigation events using the YMKNavigationListener interface.

class NavigationListener: NSObject, YMKNavigationListener {
    func onRoutesBuilt() {
        let routes = navigation.routes
        let fastestRoute = routes[0]
        // Routes received successfully ...
    }

    func onRoutesRequestErrorWithError(_ error: Error) {
        // An error occurred when requesting routes ...
    }

    // Override other listener's methods
}

// You have to subscribe to Navigation before calling the route/alternative request
navigation.addListener(navigationListener)

The YMKNavigationListener.onRoutesBuilt() handler method is called after a successful route request. You can get the route request results using the YMKNavigation.routes method. It returns a list of routes that match the last request. The routes are sorted by travel time, with the quickest first.

To learn about route request errors, use the YMKNavigationListener.onRoutesRequestErrorWithError(_:) method.

Create a new requestCreate a new request

Using YMKNavigationListener, you can subscribe to new requests for YMKNavigation by the type of routes requested.

class NavigationListener: NSObject, YMKNavigationListener {
    func onRoutesRequested(with points: [YMKRequestPoint]) {
        // ...
    }

    func onAlternativesRequested(withCurrentRoute currentRoute: YMKDrivingRoute) {
        // ...
    }

    // Override other listener's methods
}

navigation.addListener(navigationListener)

• YMKNavigationListener.onRoutesRequested(with:) notifies you about new route requests.
• YMKNavigationListener.onAlternativesRequested(withCurrentRoute:) notifies you about new alternate route requests.

Reset routesReset routes

Using the YMKNavigationListener.onResetRoutes(), you can subscribe to resetting route status events.

Route request parametersRoute request parameters

Route requests may take into account additional parameters that use YMKNavigation methods:

• YMKNavigation.isAvoidTolls: Avoid toll roads.
• YMKNavigation.isAvoidUnpaved: Avoid unpaved roads.
• YMKNavigation.isAvoidPoorConditions: Avoid roads in poor condition.

Navigation for trucksNavigation for trucks

NaviKit SDK can request routes built around the special characteristics of different vehicle types. To use vehicle parameters, you can change them using YMKNavigation.vehicleOptions.

Vehicle parameters are passed using the YMKDrivingVehicleOptions class. It stores all data related to truck restrictions. For example, vehicle size (height, width, and length), weight parameters (actual weight, allowed weight, axle load, and load capacity), and other information (such as trailer availability and eco class).

Here's an example where routes are requested for a truck that's 4.5 meters high and weighs 45 tons:

navigation.vehicleOptions = {
    let options = YMKDrivingVehicleOptions()
    options.vehicleType = .truck
    options.height = 4.5,
    options.weight = 45
}()
navigation.requestRoutes(with: somePoints, initialAzimuth: nil)

After the route is requested with YMKDrivingVehicleOptions, it's built around the passed parameters for the selected vehicle.