Route Instructions

_{Estimated reading time: 3 minutes}

In this guide you will learn how to get the text instructions for a computed route.

Setup

1. Get your Magic Lane API key token: if you do not have a token, see the Getting Started guide
2. Download the Maps & Navigation SDK for Android archive file
3. Download the RouteInstructions project archive file or clone the project with Git
4. See the Configure Android Example guide

Run the example

In Android Studio, from the File menu, select Sync Project with Gradle Files

An android device should be connected via USB cable.
Press SHIFT+F10 to compile, install and run the example on the android device.

This example computes a route and then displays the text instructions for navigation along that route.

How it works

You can open the MainActivity.kt file to see how the route is computed and the text instructions are obtained.

// Kotlin code
private val routingService = RoutingService()

val wayPoints = arrayListOf(
    Landmark("Frankfurt am Main", Coordinates(50.11428, 8.68133)),
    Landmark("Karlsruhe", Coordinates(49.0069, 8.4037)),
    Landmark("Munich", Coordinates(48.1351, 11.5820))
)
routingService.calculateRoute(wayPoints)

A private val routingService = RoutingService() instance is declared.

Two Landmark instances are defined, one for the departure, and one for the destination coordinates of the route endpoints. A route must have at least 2 Landmark instances(waypoints), but optionally can have more, for any optional additional waypoints along the route.

Then the routingService.calculateRoute(wayPoints) function is used to compute the route.

routingService.onCompleted = onCompleted@{ routes, reason, _ ->
    when (val gemError = SdkError.fromInt(reason))
    {
        SdkError.NoError ->
        {
            // No error encountered, we can handle the results.
            SdkCall.execute
            {
                // Get the main route from the ones that were found.
                mainRoute = if (routes.size > 0)
                {
                    routes[0]
                } else {
                    null
                }
                postOnMain { mainRoute?.let { displayRouteInstructions(it) } }
            }
        }
    }
}

When the route computation is complete, routingService.onCompleted = onCompleted@{ the first route, index 0, is selected routes[0]

fun displayRouteInstructions(route: Route)
{
    val instructions = arrayListOf<RouteInstruction>()
    SdkCall.execute
    {
        // Get all the route segments.
        val segmentList = route.getSegments()
        if (segmentList != null)
        {
            // For each segment, get the route instructions.
            for (segment in segmentList)
            {
                val instructionList = segment.getInstructions() ?: continue
                for (instruction in instructionList)
                {
                    instructions.add(instruction)
                }
            }
        }
    }
}

The segments of the selected route are obtained:

• val segmentList = route.getSegments()

The instructions for each segment are obtained:

• val instructionList = segment.getInstructions() ?: continue

The instructions are added to a list:

• instructions.add(instruction)

Android Examples

Maps SDK for Android Examples can be downloaded or cloned with Git