Routing

In this guide you will learn how to render an interactive map, compute and render a route on the map, and fly to the route.

Setup

First, get an API key token, see the Getting Started guide.

Download the Maps & Navigation SDK for Android archive file

Download the RoutingOnMap project archive file or clone the project with Git

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 and draws a route on the map and flies to it.

Displays an interactive map which is fully 3D, supporting pan, pinch-zoom, rotate and tilt.

How it works

You can open the MainActivity.kt file to see how the route is computed and drawn on the map.

// Kotlin code
private fun calculateRoute() {
  val waypoints = arrayListOf(
    Landmark("London", Coordinates(51.5073204, -0.1276475)),
    Landmark("Paris", Coordinates(48.8566932, 2.3514616))
  )
  routingService.calculateRoute(waypoints)
}
private fun flyToRoute(route: Route) {
  val animation = Animation()
  animation.setType(EAnimation.Fly)

  // Center the map on a specific route using the provided animation.
  mainMapView?.centerOnRoute(route, Rect(), animation)
}

private fun formatAndAddRoutes(routes: ArrayList<Route>) {
  for (routeIndex in 0 until routes.size) {
    val route = routes[routeIndex]
    // Format the route name.
    val routeName = Util.formatRouteName(route)
    /*
    Create an image list that will be added to the route name
    and then be displayed in the route's bubble.
    */
    val imageList = arrayListOf<Image>()

    // Add the route to the map (along with the image list).
    mainMapView?.preferences()?.routes()?.add(
      route, routeIndex == 0, routeName, imageList
    )
  }
}

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.activity_main)
  progressBar = findViewById(R.id.progressBar)
  routingService.onCompleted = onCompleted@{ routes, reason, hint ->
    progressBar.visibility = View.GONE

    when (val gemError = SdkError.fromInt(reason)) {
      SdkError.NoError -> {
        SdkCall.execute {
          // Format route names and add them to the map.
          formatAndAddRoutes(routes)

          // Get the main route from the ones that were found.
          val mainRoute: Route? = if (routes.size > 0) {
            routes[0]
          } else {
            null
          }
          if (mainRoute != null) {
            flyToRoute(mainRoute)
          }
        }
      }
    }
  }
}

In the calculateRoute() function, 2 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.

Next, the routing service computes the route, and calls the onCompleted callback with the resulting routes, as there could be more than one: routingService.calculateRoute(waypoints) onCompleted is set here in the onCreate() function

Then, formatAndAddRoutes(routes) adds the routes to the map so they are rendered.

If there is at least one route, flyToRoute(mainRoute) calls the centerOnRoute() API function to fly to the selected route, such that its bounding box fits in the viewport.

Android Examples

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