Route Terrain Profile

_{Estimated reading time: 4 minutes}

In this guide you will learn how to obtain and display terrain statistics for a route, given the coordinates of the departure and destination points. The terrain profile statistics include the minimum and the maximum elevation above sea level in meters, as well as the total vertical meters climbed, and the total vertical meters descended during the 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 RouteTerrainProfile 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.

How it works

You can open the MainActivity.kt file to see how the route terrain profile statistics are obtained and displayed.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    progressBar = findViewById(R.id.progressBar)

    SdkSettings.onMapDataReady = onMapDataReady@{ isReady ->
        if (!isReady) return@onMapDataReady
        // Defines an action that should be done after the world map is ready.
        calculateRoute()
    }
    SdkSettings.onApiTokenRejected = {
        Toast.makeText(this, "TOKEN REJECTED", Toast.LENGTH_LONG).show()
    }
    if (!GemSdk.initSdkWithDefaults(this)) {
        // The SDK initialization was not completed.
        finish()
    }
    if (!Util.isInternetConnected(this)) {
        Toast.makeText(this, "You must be connected to internet!", Toast.LENGTH_LONG).show()
    }
}

The MainActivity overrides the onCreate function which checks that internet access is available using Util.isInternetConnected() and calls the calculateRoute() function after the map is instantiated, as indicated by the isReady flag.

private fun calculateRoute() = SdkCall.execute {
    val waypoints = arrayListOf(
        Landmark("Zaragoza", 41.645, -0.883),
        Landmark("Toulouse", 43.6, 1.438)
    )
    /*
    Setting setBuildTerrainProfile(true) in the Routing Service preferences
    is mandatory to get data related to the route terrain profile,
    otherwise the terrain profile is not calculated in the routing process.
    */
    routingService.preferences.buildTerrainProfile = true
    routingService.calculateRoute(waypoints)
}

The calculateRoute() function computes a route between two or more landmarks, given as a list of waypoints, where the first one is the departure point, and the last one is the destination point.

The landmarks contain a name, latitude and longitude, in degrees.

routingService.preferences.buildTerrainProfile = true has to be set to true before routingService.calculateRoute(waypoints) in order to also get the terrain profile statistics.

@SuppressLint("SetTextI18n")
private fun displayTerrainInfo(terrain: RouteTerrainProfile) {
    var maxElv = .0f
    var minElv = .0f
    var elevationAt = .0f
    var totalUp = .0f
    var totalDown = .0f
    var climbingSections = 0

    SdkCall.execute {
        maxElv = terrain.maxElevation
        minElv = terrain.minElevation
        elevationAt = terrain.getElevation(1000) // 1 KM
        totalUp = terrain.totalUp
        totalDown = terrain.totalDown
        climbingSections = terrain.climbSections?.size ?: 0
    }
    findViewById<TextView>(R.id.text).text =
        "Details: \nMin. Elevation = $minElv m, " +
            "\nMax. Elevation = $maxElv m, " +
            "\nElevation after 1KM = $elevationAt m," +
            "\nTotal Up = $totalUp m, \n" +
            "Total Down = $totalDown m \n\n\n" +
            "Number of Climbing Section: \n$climbingSections"
}

The above function, displayTerrainInfo() displays some basic statistics about the computed route in this example in text format, to show how to access the terrain profile data.

The RouteTerrainProfile class contains a lot of information, but this example presents only the minimum and maximum elevation above sea level in meters, elevation at a certain point along the route, the total vertical meters ascending and descending, and the number of climbing sections in the selected route.

To display a chart representing the elevation of the route, the method getElevationSamples(samplesCount) can be used, specifying the number of samples, and thus resolution, of the resulting terrain data.

There are also additional methods about route terrain profile in the documentation.

Android Examples

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