Build routes

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

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

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

Request routes

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

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

// Coordinates routes are requested for
let requestPoints = [
    MMKRequestPoint(
        point: MMKPoint(latitude: 25.190614, longitude: 55.265616),
        type: .waypoint,
        pointContext: nil,
        drivingArrivalPointId: nil
    ),
    MMKRequestPoint(
        point: MMKPoint(latitude: 25.187532, longitude: 55.275413),
        type: .waypoint,
        pointContext: nil,
        drivingArrivalPointId: nil
    ),
    MMKRequestPoint(
        point: MMKPoint(latitude: 25.189279, longitude: 55.282246),
        type: .waypoint,
        pointContext: nil,
        drivingArrivalPointId: nil
    ),
    MMKRequestPoint(
        point: MMKPoint(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 MMKRequestPoint 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 MMKDrivingOptions 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.

Note

The number of simultaneous route requests through MMKNavigation is limited — there can only be one active request at a time. If you create a new request before the previous one is completed, the previous one is canceled.

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

Route request by URI

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

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

Request 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 MMKNavigation.requestAlternatives() asynchronous call.

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

Events

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

Route request results

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

class NavigationListener: NSObject, MMKNavigationListener {
    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 MMKNavigationListener.onRoutesBuilt() handler method is called after a successful route request. You can get the route request results using the MMKNavigation.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 MMKNavigationListener.onRoutesRequestErrorWithError(_:) method.

Create a new request

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

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

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

    // Override other listener's methods
}

navigation.addListener(navigationListener)

Reset routes

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

Route request parameters

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

Navigation 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 MMKNavigation.vehicleOptions.

Vehicle parameters are passed using the MMKDrivingVehicleOptions 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 = MMKDrivingVehicleOptions()
    options.vehicleType = .truck
    options.height = 4.5,
    options.weight = 45
}()
navigation.requestRoutes(with: somePoints, initialAzimuth: nil)

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

Previous
Architecture
Next
Guidance