Learn how to find a route and directions with the route service.
Routing is the process of finding the path from an origin to a destination in a street network. You can use the Routing service to find routes, get driving directions, calculate drive times, and solve complicated, multiple vehicle routing problems. To create a route, you typically define a set of stops (origin and one or more destinations) and use the service to find a route with directions. You can also use a number of additional parameters such as barriers and mode of travel to refine the results.
In this tutorial, you define an origin and destination by clicking on the map. These values are used to get a route and directions from the route service. The directions are also displayed on the map.
Prerequisites
The following are required for this tutorial:
An ArcGIS account to access API keys. If you don't have an account, sign up for free.
A development and deployment environment that meets the system requirements.
An IDE for Android development in Kotlin.
Steps
Open an Android Studio project
To start this tutorial, complete the Display a map tutorial. Or download and unzip the Display a map solution in a new folder.
Modify the old project for use in this new tutorial. Expand More info for instructions.
On your file system, delete the .idea folder, if present, at the top level of your project.
In the Android tool window, open app > res > values > strings.xml.
In the <string name="app_name"> element, change the text content to Find a route and directions.
strings.xml
Use dark colors for code blocks
1
2
3
4
5
Change line
1
2
3
4
5
<resources><stringname="app_name">Find a route and directions</string></resources>
In the Android tool window, open Gradle Scripts > settings.gradle.
Change the value of rootProject.name to Find a route and directions.
Click File > Sync Project with Gradle files. Android Studio will recognize your changes and create a new .idea folder.
If you downloaded the solution project, set your API key.
An API Key enables access to services, web maps, and web scenes hosted in ArcGIS Online.
Go to your developer dashboard to get your API key.
For these tutorials, use your default API key. It is scoped to include all of the services demonstrated in the tutorials.
In Android Studio: in the Android tool window, open app > java > com.example.app > MainActivity.
In the setApiKey() function, find the ApiKey.create() call and paste your API key inside the quotes, replacing YOUR_API_KEY.
MainActivity.kt
Use dark colors for code blocks
Change line
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
privatefunsetApiKey() {
// It is not best practice to store API keys in source code. We have you insert one here// to streamline this tutorial. ArcGISEnvironment.apiKey = ApiKey.create("YOUR_API_KEY")
}
Add import statements, class properties, and application context
Modify import statements to reference the packages and classes required for this tutorial. Then add properties to the class that are used in multiple functions within this tutorial.
Replace the import statements with the imports needed for this tutorial.
A streets basemap layer is typically used in routing applications. Update the basemap to use the ArcGISStreets basemap style, change the position of the map to center on Los Angeles and add a GraphicsOverlay.
In the setupMap() function, change the BasemapStyle from ArcGISTopographic to ArcGISStreets, and change the latitude and longitude coordinates to center on Los Angeles.
Add the graphicsOverlay to the mapView.graphicsOverlays property. A graphics overlay is a container for graphics. Graphics will be added later in this tutorial as a visual means to display the route stops and route result on the map.
In MainActivity.kt, in the onCreate() function, assign arrayAdapter to the listView.adapter property. The ArrayAdapter will create and populate the listView with TextView objects, one text view for each string in the directionsList.
A RouteTask requires at least an origin and a destination stop to find a route. Create a function that adds Stop objects to the routeStops list.
When a user taps on the map, a stop will be added to a list of route stops. In this tutorial, the first tap will create the origin stop and the second will create the destination stop.
A task can make asynchronous requests to an online service or offline data and then return the results. In this tutorial, we will solve the route between the origin and destination stops using a RouteTask that accesses a routing service.
A routing service with global coverage is part of ArcGIS location services. You can also publish custom routing services using ArcGIS Enterprise.
To solve a route, the route task needs appropriate RouteParameters. We will start by retrieving the default route parameters and then modify them.
Get the default route parameters by calling RouteTask.createDefaultParameters(). When the call fails: in the getOrElse lambda, output an error message and return from lifecycleScope.launch. When the call returns a RouteParameters object: use it to add the route stops and configure the task to return step-by-step directions.
Note that createDefaultParameters()function is a suspend function that returns a Result<RouteParameters> object. For more information on Result<> in Kotlin, see Result. Scroll down to getOrElse.
For more information on RouteParameters, see setStops() and returnDirections in the API Reference for ArcGIS Maps SDK for Kotlin.
Solve the route by calling solveRoute() on the route task, passing in the route parameters. This is the route between the origin and the destination stops.
When the call fails: in the getOrElse lambda, output an error message and return from lifecycleScope.launch. When the call returns a RouteResults object: use it to get the list of routes from the route result, verify that the list is not empty, and retrieve the first route in the list.
Note that solveRoute()function is a suspend function that returns a Result<RouteResult> object. For more information on Result<> in Kotlin, see Result. Scroll down to getOrElse.
For more information on routeResult, see RouteResult in the API Reference for ArcGIS Maps SDK for Kotlin.
Create a new graphic that will be used to display this route. Call the Graphic constructor, passing in the route's Geometry and a SimpleLineSymbol. Then add the graphic to the graphicsOverlay.
Direction maneuvers are the step-by-step navigation actions for a route. Each direction maneuver has direction text, such as "Turn right at Avenue A."
Clear any existing directions in the directionsList property you created at the start of this tutorial.
Access the list of manuevers from the directionManeuvers property of route. Use forEach to iterate through the maneuvers, adding the direction text for each meaneuver to the directionsList property.
Call notifyDataSetChanged() on the arrayAdapter property, which causes the list view (in the listView property) to be updated with the text directions.