Skip To Content

Finding a Route

In this topic

The primary class for routing in the ArcGIS Runtime SDK for Android comes in the form of a RouteTask. A RouteTask allows you to calculate point-to-point and multi-point routes using ArcGIS Server Network Analyst services or local, on-board Network Analyst data.

Network Analyst services contain one or more Network Analysis layers. ArcGIS provides different types of analysis layers, such as Route, Service Area, Closest Facility, etc depending upon the type of analysis to be performed. An online RouteTask relies on a Route analysis layer to compute routes.

ArcGIS Online provides worldwide Network Analyst services you can use with a subscription to ArcGIS Online. You can also create your services using ArcGIS Server. Learn more about creating Network Analysis services.

For local data usage, Network Datasets can be exported to an ArcGIS Runtime format using export tools found in ArcGIS Desktop.

Creating a Route Task

Choosing the right type of RouteTask depends on your data availability and needs. Offline routing offers the benefits of increased performance and removes the need for network connectivity, but as a consequence, a significant amount of storage space may be needed on-device. An online RouteTask allows you to take advantage of robust ArcGIS Online services and requires no additional data deployment, but network speeds and REST response size can negatively impact performance.

Creating an Online Route Task

To instantiate an online RouteTask, you need to provide a URL to REST resource that represents a Route layer in a Network Analyst service. If the service is secured, you will also need to provide the credentials that can be used to access the service. The following code snippet shows how to create a RouteTask for the Route layer in the ESRI_Route_NA service on ArcGIS Online.

String routeTaskURL = "http://route.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World";
RouteTask routeTask = RouteTask.createOnlineRouteTask(routeTaskURL, null);
Creating a Local Route Task

To instantiate a RouteTask using local data, you need to provide a path to the local database and the name of the Network Dataset within the database. The following snippet shows how to create a Route task from data located in the /<external-storage-directory>/ArcGIS/Routing/ folder on your device. In this snippet, the database is named “SanDiego.db” and the exported Network Dataset files start with the prefix “Streets_ND”.

String extern = Environment.getExternalStorageDirectory().getPath();
RouteTask routeTask = RouteTask.createLocalRouteTask(extern + "/ArcGIS/Samples/Routing/SanDiego.geodatabase", "Streets_ND");

Route Task parameters

You provide input to the RouteTask using an instance of the RouteParameters class. You can instantiate a new RouteParameters object by using the retrieveDefaultRouteTaskParameters() method on your RouteTask object. Using this method will set the appropriate default settings for routing. Consequently, the only required parameter that you need to set is the stops parameter. The following sections describe some of the inputs you can provide to a RouteTask.

Note:

Creating the default parameters object using an online RouteTask involves making a network call, so Android threading considerations should be made accordingly.

Impedance

Impedance specifies a cost that should be minimized in the resulting route. For example, impedance can be set to Time in order to calculate the fastest route or Length to calculate the shortest route.

Online Service Descriptions

For online services, impedances supported by the service are listed in the Services Directory under Network Dataset → Network Attributes with a Usage Type of esriNAUTCost.

In the example shown above, Length and Time are supported impedances. The following code snippets sets the impedance to Length to calculate the shortest route.

// set impedance for length
RouteParameters routeParams = new RouteParameters();
routeParams.setImpedanceAttributeName("Length");

Accessing Service Descriptions Programmatically

For both online and offline RouteTasks, available cost attributes can also be accessed through the NetworkDescription object. This object contains important network information such as supported languages for driving directions, cost attributes, and restriction attributes. This object is useful for displaying routing options on your user interface. The following snippet shows accessing the network description, and setting the first cost attribute as the impedance for the solve operation.

// Create a parameters object and retrieve the network description
RouteParameters routeParams = mRouteTask.retrieveDefaultRouteTaskParameters();
NetworkDescription description = mRouteTask.getNetworkDescription();
List<CostAttribute> costAttributes = description.getCostAttributes();
 
// Assign the first cost attribute as the impedance
if (costAttributes.size() > 0)
  routeParams.setImpedanceAttributeName(costAttributes.get(0).getName());

Stops

Stops specify the locations that must be visited along the route. You need at least two stops to calculate a valid route; however, you can add more stops if necessary. There are two ways to specify stops:

Features

The NAFeaturesAsFeatures class contains stops represented as graphics. You can create an array of StopGraphic objects representing stop features. You can then assign these features to the parameter object using the setFeatures() method. The following code snippet assumes you have constructed two points representing your current location (mLocation) and the destination location (mDestination) to route to.

// create routing features class
NAFeaturesAsFeature naFeatures = new NAFeaturesAsFeature();
// Create the stop points from point geometry
StopGraphic startPnt = new StopGraphic(mLocation);
StopGraphic endPnt = new StopGraphic(mDestination);
// set features on routing feature class
naFeatures.setFeatures(new Graphic[] {point1, point2});
// set stops on routing feature class
routeParams.setStops(naFeatures);

Layer definition

Apart from specifying stops by-value, for example, providing the actual values for each feature as described above, you can also specify them by-reference. This is useful when you already have a set of well known or commonly used stops stored with the Network Analyst service. In such cases, the application does not need to know the actual details about each stop. All it needs to do is set up a layer definition specifiying which stops should be included in the analysis.

A layer definition is represented by an object of the NAFeaturesAsLayer class. You can use SQL statements and/or spatial relationships to specify which stops should be used in the analysis. For example, the following code snippet sets up a layer definition referencing features that fall within Los Angeles and have a value of Overnight for the delivery_type attribute.

NAFeaturesAsLayer naLayer = new NAFeaturesAsLayer();
// set layer name with the layer in the service
// containing stops
naLayer.setLayerName("<layer_in_service_containing_stops>");
// set where clause for 'Overnight' delivery_type
naLayer.setWhere("delivery_type='Overnight'");
// set stops on routing layer
routeParams.setStops(naLayer);
Usage Considerationss

Using a layer definition is only supported when solving with an online RouteTask. The stops for a local RouteTask must be specified by value using the NAFeaturesAsFeatures class.

Calculating routes

Once you have set up the input parameters, calculating routes is as easy as invoking solve() method on RoutingTask and passing in the RoutingParameters object to use in the calculation.

RouteResult mResults = routeTask.solve(routeParams);

This method returns a RoutingResult object containing the relevant information for the entire server response. This includes all routes, as well as the stops, point/polyline/polygon barriers, and messages returned by the server. For information on displaying route geometry and driving directions, see Display Driving Directions