Build routes

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

Create Navigation

To create new navigation, call NavigationFactory.createNavigation.

val navigation = NavigationFactory.createNavigation(DrivingRouterType.COMBINED)

Request routes

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

To request routes, use the Navigation.requestRoutes method.

// Coordinates routes are requested for
val requestPoints = listOf(
    RequestPoint(Point(25.190614, 55.265616), RequestPointType.Waypoint, null),
    RequestPoint(Point(25.187532, 55.275413), RequestPointType.Waypoint, null),
    RequestPoint(Point(25.189279, 55.282246), RequestPointType.Viapoint, null),
    RequestPoint(Point(25.196605, 55.280940), RequestPointType.Waypoint, null),
)
navigation.requestRoutes(
    requestPoints,
    navigation.guidance.location?.heading,
    3,
)

The first argument is the RequestPoint 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 DrivingOptions 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 URI

In Navigation, you can request a route with the route URI saved earlier using the Navigation.resolveUri 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 Navigation.requestAlternatives asynchronous call.

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

Events

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

Route request results

The Navigation.requestRoutes and Navigation.requestAlternatives calls are asynchronous since they use a network request. To process the request results, subscribe to navigation events using the NavigationListener interface.

val navigationListener = object : NavigationListener {
    override fun onRoutesBuilt() {
        val routes = navigation.routes
        val fastestRoute = routes[0]
        // Routes received successfully ...
    }

    override fun onRoutesRequestError(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 NavigationListener.onRoutesBuilt handler method is called after a successful route request. You can get the route request results using the Navigation.getRoutes 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 NavigationListener.onRoutesRequestError method.

Create a new request

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

val navigationListener = object : NavigationListener {
    override fun onRoutesRequested(requestPoints: List<RequestPoint>) {
        // ...
    }

    override fun onAlternativesRequested(currentRoute: DrivingRoute) {
        // ...
    }

    // Override other listener's methods
}
navigation.addListener(navigationListener)

• NavigationListener.onRoutesRequested notifies you about new route requests.
• NavigationListener.onAlternativesRequested notifies you about new alternate route requests.

Reset routes

Using the NavigationListener.onResetRoutes, you can subscribe to resetting route status events.

Route request parameters

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

• Navigation.avoidTolls: Avoid toll roads.
• Navigation.avoidUnpaved: Avoid unpaved roads.
• Navigation.avoidPoorConditions: Avoid roads in poor condition.

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 Navigation.setVehicleOptions.

Vehicle parameters are passed using the VehicleOptions 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 = VehicleOptions().apply {
    vehicleType = VehicleType.TRUCK,
    height = 4.5f,
    weight = 45f,
}
navigation.requestRoutes(somePoints, someDrivingOptions)

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