Skip To Content

Find a route

In this topic

A Route task allows you to calculate point-to-point and multipoint routes using ArcGIS for Server network analysis services or your own offline network dataset and a local geodatabase.

A network analysis service contains one or more network analysis layers. ArcGIS provides different types of analysis layers, such as route, service area, closest facility, and so on, depending on the type of analysis to be performed. A Route task relies on a route analysis layer to compute routes. ArcGIS Online provides network analysis services based on street data for the world and you can create your own services with ArcGIS for Server.

Finding a route with a local geodatabase requires that the local geodatabase contains a route analysis layer.

Learn about creating network analysis services

Create a Route task

There are two types of Route tasks. Choosing the right type of RouteTask depends on your data availability and needs. The LocalRouteTask 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 OnlineRouteTask 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.

To instantiate an OnlineRouteTask, provide a URL to a REST resource that represents a route layer in a network analysis service. If the service is secured, provide the credentials that can be used to access the service. The following code snippet shows how to create an OnlineRouteTask for the Route layer in the ESRI_Route_NA service on ArcGIS Online:

QString taskURL ("");
m_onlineRouteTask = new EsriRuntimeQt::OnlineRouteTask(taskURL, this);

To instantiate a LocalRouteTask for offline routing, provide the path to the local geodatabase and the name of the routing network in that geodatabase. The following code snippet shows how to create a LocalRouteTask for a streets network in a sample geodatabase provided with the ArcGIS Runtime API for Qt:

QString databasePath = getPathSampleData() + "disconnected" +QDir::separator() +
  "route" + QDir::separator() + "SanFrancisco" + QDir::separator() +

m_localRouteTask = new EsriRuntimeQt::LocalRouteTask(databasePath, "Streets_ND", this);


A LocalRouteTask can take a considerable amount of time to construct depending on the size of the source data. It is recommended that a LocalRouteTask be created once and kept alive for the life of the application.

Route task input parameters

The OnlineRouteTask solves a routing problem using an instance of the OnlineRouteTaskParameters class as input. To create a new OnlineRouteTaskParameters object, you must call the defaultParameters method on the OnlineRouteTask object and modify its properties as needed for the task. Calling OnlineRouteTask::defaultParameters involves making a network query to the service, so consider how this should be handled in the context of threading when you use this method.

Similarly, the LocalRouteTask accepts a LocalRouteTaskParameters object as input. You should create one by calling the LocalRouteTask::defaultParameters method.

The following sections describe some of the inputs you can provide to a Route task.


Impedance specifies a cost that should be minimized in the resulting route. For example, impedance could 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.

Network attributes list

In the example shown above, Length and Time are supported impedances. The following code snippet sets the impedance to Length in order to calculate the shortest route. It assumes you have constructed an OnlineRouteTask object named m_onlineRouteTask that is used to create the parameters object.

// set impedance for length
EsriRuntimeQt::OnlineRouteTaskParameters* routeParams = qobject_cast<EsriRuntimeQt::OnlineRouteTaskParameters*>(m_onlineRouteTask->defaultParameters());

Access service descriptions programmatically

For both online and local 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
EsriRuntimeQt::OnlineRouteTaskParameters* onlineRouteParams = qobject_cast<EsriRuntimeQt::OnlineRouteTaskParameters*>(m_onlineRouteTask->defaultParameters());
EsriRuntimeQt::NetworkDescription description = m_onlineRouteTask->networkDescription();
QList<EsriRuntimeQt::CostAttribute> costAttributes = description.costAttributes();

// Assign the first cost attribute as the impedance
if (costAttributes.size() > 0)


Stops specify the locations that must be visited along the route. Your route can have many stops, but you need at least two stops to calculate a valid route.

Stops as features

You can create an array of graphics representing stop features. You can then assign these features to the parameter object using setStops.

// Set up the routing task parameters
EsriRuntimeQt::LocalRouteTaskParameters* parameters = qobject_cast<EsriRuntimeQt::LocalRouteTaskParameters*>(m_routingTask->defaultParameters());

// Create and draw the Start and End stop graphics
EsriRuntimeQt::Point startPt(-117.08, 32.7, m_map->spatialReference());
EsriRuntimeQt::Graphic* startGraphic = new EsriRuntimeQt::Graphic(startPt, EsriRuntimeQt::SimpleMarkerSymbol(Qt::blue, 11), this);

EsriRuntimeQt::Point endPt(-118.24, 34.05, m_map->spatialReference());
EsriRuntimeQt::Graphic* endGraphic = new EsriRuntimeQt::Graphic(endPt, EsriRuntimeQt::SimpleMarkerSymbol(Qt::blue, 11), this);

// Add the graphics to a list
QList<EsriRuntimeQt::Graphic*> stopGraphics;

// Create the stops features from the list of stops
EsriRuntimeQt::NAFeaturesAsFeature* stops = new EsriRuntimeQt::NAFeaturesAsFeature(this);

// Add the stop features to the parameters object

The order of the objects in the array indicates, by default, the sequence in which stops are visited by the route. However, if you enable the setFindBestSequence property on RouteTaskParameters, the service attempts to reorder the stops to find the optimal route. You can also enable the setPreserveFirstStop and setPreserveLastStop properties on RouteTaskParameters if you do not want the origin and destination stops to be reordered.

If you enable time windows in your analysis, you can also assign each stop a start and end time specifying the time window during which the stop needs to be visited. If a stop's setStartTime property is set to 10:00 a.m. and the route arrives at the stop at 9:50 a.m., there is a wait time of 10 minutes that is added to the total time. If the setEndTime property is set to 11:00 a.m., and the earliest a route can reach the stop is 11:25 a.m., a violation of 25 minutes is noted.

A stop can have additional attributes depending on how the route layer in the Network Analyst service is configured. These attributes are listed in the Network Analysis Classes > Class Name: Stops section in the Services Directory.

Attributes of stops
Attributes of stops

Attributes can be of type input, output, or both. Input attributes are specified by the client and are taken into consideration by the service while performing the analysis, for example, the time window's start and end time and routeName.

Output attributes are returned by the service with the computed result when you enable setReturnStops on RouteTaskParameters. Output attributes provide additional information about the stop pertaining to the results, for example, the time of arrival and departure and which side of the vehicle the curb is on.

Some attributes can be both input and output. These attributes are specified by the client but can be modified or overridden by the service, for example, when the service finds a more optimal sequence than the one specified.

Learn more about attributes supported by stop features

Layer definition

As shown above, for online routing you can define stops by providing the actual locations for each stop. An alternative is to specify them using a layer definition. This is useful when you already have a set of well-known or commonly used stops stored along with the network analysis 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 specifying 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 spatial relationships to specify which stops should be used in the analysis. For example, the following code snippets set up a layer definition referencing features that fall within the City of Los Angeles and have a value of Overnight for the delivery_type attribute.

EsriRuntimeQt::NAFeaturesAsLayer* naLayer = new EsriRuntimeQt::NAFeaturesAsLayer(this);
// Set layer name with the layer in the service containing stops
// Set where clause for 'Overnight' delivery_type
// Set routing layer stops on OnlineRouteParameters object

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


Barriers represent ad hoc restrictions that must be taken into consideration when calculating a route. A barrier can specify a set of roads or a region that must be completely avoided by the route, for example, a bridge that may be closed due to construction work. Some barriers may permit travel through them albeit at an added cost. For example, an accident on a freeway may temporarily slow down traffic. This can be represented by a barrier that allows travel along the freeway but increases the required travel time.

Barriers as features

You can create an array of NAFeaturesAsFeatures objects representing barrier features and populate each feature with a geometry representing the barrier's location and shape. The geometry can be a point, polyline, or polygon. You can then assign these barrier features to the parameter object using pointBarriers, polylineBarriers, or polygonBarriers depending on the feature's assigned geometry type.


Create separate arrays for point, polyline, and polygon barriers.

A barrier can also have additional attributes depending on how the route layer in the Network Analyst service is configured. These attributes are listed in the Network Analysis Classes > Class Name: Barriers, PolylineBarriers, PolygonBarriers section in the Services Directory. Attributes can be of type input (specified by the client), output (returned by the server), or both.

Learn more about barriers and the attributes supported by point, polyline, and polygon barriers

Time windows

A time window specifies a period of time within which a stop should be visited by a route. For example, if you make appointments to meet several customers at different locations, enable time windows in the analysis and specify a time window for each location to get a route that allows you to keep your appointments.

Learn more about time windows

To enable time windows in your analysis, do the following:

  • Enable the useTimeWindows property on RouteTaskParameters.
  • Specify the departure time from the origin using the setStartTime property on RouteTaskParameters.
  • Assign a time window to each stop.

Drive directions

The Route task can also return turn-by-turn driving directions for the route if you enable setReturnDirections on RouteTaskParameters. Specify the distance units to use (miles, kilometers, and so on) through the setDirectionsLengthUnit property and, depending on the languages supported by the service, specify which language to use through the setDirectionsLanguage property.

Result options

Ignore invalid locations

Enabling the setIgnoreInvalidLocations property allows the Route task to return a route even if some stops are invalid, for example, if they're not reachable on the underlying transportation network. If this property is disabled, the Route task returns an error even if one stop is invalid.

See the RouteTaskParameters API reference for a complete list of inputs for the Route task.

Calculate routes

Once you set up the input parameters, calculate the route by invoking the solve method. The Route task emits a solveTaskComplete signal with results. Connect a slot to this signal to process the results. The operation's results are contained in a RoutingResults object.

// This method was connected as a slot for the solveRouteComplete signal. 
// It is called when the solve finishes on its thread.
void MyApp::onSolveTaskComplete(EsriRuntimeQt::RoutingResult* result)
  if (!result)
    qDebug() << "There was an error solving the route. RoutingResult is empty.";
  // Process the results...
  // make sure the result is deleted

Retrieve results

A RoutingResult object contains an array of objects representing the calculated routes. Each RoutingResult object contains the following:

  • A graphic representing the route feature. The graphic's attributes provide information about route properties.
  • An array of graphics representing the stops that are visited by the route (if you enabled setReturnStops on RouteTaskParameters). Each graphic contains attributes that correspond to stop properties. These properties provide valuable information about the stop as it pertains to the computed route.
  • A set of turn-by-turn driving directions (if you enabled setReturnDirections on RouteTaskParameters).

The RoutingResult object also contains an array of messages providing information about warnings or errors encountered while calculating the route.

The following example retrieves the route, applies a symbol to it, adds it to a graphics layer, prints the directions to the console, and zooms the map to the graphic:

EsriRuntimeQt::Route route = result->routes().at(0);
EsriRuntimeQt::Graphic routeGraphic(route.route().geometry(), EsriRuntimeQt::SimpleLineSymbol(QColor(92,92,255), 2)), this);

// Add the route graphic
qint64 id = m_graphicsLayer->addGraphic(routeGraphic);

// print out directions
QList<EsriRuntimeQt::RoutingDirection> dirs = route.routingDirections();

foreach (EsriRuntimeQt::RoutingDirection dir, dirs)
  qDebug() << dir.text();

// Zoom to route envelope
EsriRuntimeQt::Envelope env = route.envelope();

Related topics