GP service example: Shortest route on a street network

Complexity: Intermediate Data Requirement: ArcGIS Tutorial Data Setup Data Path: C:\ArcGIS\ArcTutor\GP Service Examples\ShortestRoute Goal: Author, publish, and use a geoprocessing service that finds the shortest route on a street network and generates driving directions.

Folder	ShortestRoute
Purpose	Creates a shortest route between given points on a street network and generates driving directions in a text or HTML file.
Services	SanFranciscoBaseMap (map service) ShortestRouteService (geoprocessing service)
Geoprocessing tasks	Calculate Shortest Route and Text Directions Calculate Shortest Route and HTML Directions
Inputs	Two or more user-digitized points.
Outputs	A shortest route between the user-specified points based on the travel time. An HTML or text file (depending on the task used) containing driving directions.
Data	Uses a street network dataset for the San Francisco area provided in the ToolData folder.
Extensions	Network Analyst
Of note	Demonstrates how to reuse an existing Route network analysis layer each time the task is executed. Calculate Shortest Route and HTML Directions task—How an external Python library can be used from a script tool to convert driving directions from XML to HTML format.

About this example

Corresponding folder

C:\arcgis\ArcTutor\GP Service Examples\ShortestRoute contains the completed models, script tool, and data.

About this example

ShortestRouteService, created in this example, shows you how to publish geoprocessing tasks that calculate the shortest route on a street network between user-specified points and generate a file containing the driving directions. The Calculate Shortest Route and Text Directions task generates driving directions in a text file whereas the Calculate Shortest Route and HTML Directions task generates driving directions in an HTML file. Both the tasks also output the shortest route as a feature set.

Example output from Calculate Shortest Route and Text Directions task

Data

The data for this example comes from C:\arcgis\ArcTutor\GP Service Examples\ShortestRoute.

ShortestRoute folder contents

Network dataset

The ToolData folder contains a file geodatabase, SanFrancisco.gdb. This geodatabase contains a network dataset, Streets_ND, within the Transportation feature dataset. This network dataset models the street network for the San Francisco area. It provides a network attribute, TravelTime, which indicates the time taken to travel each street segment in minutes.

Basemap

The basemap layer within SanFranciscoBaseMap.mxd has a layer, Streets, as illustrated below. This layer shows the extent of the network dataset. This means that this task can be used to determine the shortest route only in this extent.

San Francisco basemap showing the network dataset extent

SanFranciscoBaseMap.mxd is published as a map service.

Toolbox and map document

The toolbox for the geoprocessing service is ShortestRouteService, and the source map document for the service is ShortestRouteService.mxd. ShortestRouteService contains two models and a script tool, Convert directions to HTML. This script tool is used within the Calculate Shortest Route and HTML Directions model. ShortestRouteService.mxd contains two source data layers, Streets_ND (the network dataset) and Route (the network analysis layer).

Model

Model overview

The Calculate Shortest Route and Text Directions model is illustrated below. There is one input parameter, Input Stops, which is points. The shortest route visits the stops based on the digitized sequence. The model adds the user-digitized points as stops to an existing Route network analysis layer, performs a solve to determine the shortest route, generates driving directions, and writes them to a text file.

Using an existing network analysis layer

In this model, a network analysis layer is not created in the model as it is in the DriveTimePolygonsService example. Instead, the existing route layer, Route, is used. (This layer was created using the Make Route Layer tool.) The existing layer can be used because none of the analysis properties for the route layer, such as impedance attribute, are exposed as model parameters. In the DriveTimePolygonsService example, the default break values (an analysis property for service area layers) was exposed as a model parameter, so the Make Service Area Layer tool was required as a model process.

Note that if any of the route analysis properties, such as impedance attribute, are to be exposed as model parameters, the Make Route Layer tool has to be used as a first process in the model.

The Route layer used as an input variable in the model was created by first adding the Streets_ND network dataset to the ShortestRouteService.mxd, then using the Make Route Layer tool. For this example, the following parameters were used for the Make Route Layer tool. Default values were used for the parameters not mentioned in this table.

Parameter	Value
Input analysis network	Streets_ND
Output layer name	Route
Impedance attribute	TravelTime
Accumulators	TravelTime;Meters
U-turn policy	ALLOW_DEAD_ENDS_AND_INTERSECTIONS_ONLY

Parameter values used with Make Route Layer tool

Creating a route layer

Model processes

The Add Locations tool adds user-digitized points as stops to the route layer. The Input Locations parameter for the tool is specified through a model parameter, Input Stops. This parameter is a feature set data type. The schema and symbology for the feature set are derived from the InputStops.lyr file found within the ToolData folder.

The schema for the Input Stops feature set contains a text field, Name. This field can be used to provide stop names while generating driving directions by mapping the Name property to the name field in Field mappings, as illustrated below. If the value for the name field is not specified by the user, default values of Location 1, Location 2, and so on, are used for stop names.

Since the same route layer is used for each model run, any existing stops need to be removed before adding the new stops. To delete existing stops, the Append to existing locations option, illustrated below, is unchecked.

Adding stops

The Solve tool calculates the shortest route based on the TravelTime network attribute and other options as specified in the Route layer. The calculated route is written to the Routes sublayer in the output route layer.

Network analysis layers (such as Route) are not supported output parameter data types for ArcGIS Server clients. So the Select Data tool is used to get the Routes sublayer from the Route layer.

The Directions tool is used to generate the driving directions and output them to a text file. The output text file containing driving directions is created in the jobs directory on the server using the %scratchworkspace% inline variable. The SolveSucceeded variable derived from the Solve tool is used as a precondition for the Directions tool. This means that the directions file is generated only if the Solve tool can find a route between input points.

Generating driving directions

Tool layer

The Calculate Shortest Route and Text Directions tool layer is created by dragging the Calculate Shortest Route and Text Directions model into the ArcMap table of contents. Since the model updates the existing Route layer, the tool layer output derives its symbology from the Routes sublayer within the Route layer in the table of contents.

Symbology for the tool layer

Publishing

SanFranciscoBaseMap.mxd is published as a map service. ShortestRouteService.mxd is published as a geoprocessing service with no result map service, as follows:

1. In the Catalog window, right-click SanFranciscoBaseMap.mxd and click Publish to ArcGIS Server.
2. Accept all defaults.
3. In the Catalog window, navigate to your server administrative connection under the GIS Servers node, right-click, then choose Add New Service. Name the service ShortestRouteService and choose Geoprocessing Service as the type.
4. Click Next.
5. In the next panel, choose Synchronous for Execution Type. For The tools exposed by the Geoprocessing Service are stored in option, choose A map and specify ShortestRouteService.mxd for Map Document. Since you will test your service, check Show Messages.

   Publishing ShortestRouteService

6. Click Next. From this point on, you can accept the default values provided by the wizard and create the service.

Using

1. Start ArcMap with a blank document.
2. Create a user connection to ArcGIS Server from the Catalog window if one does not exist.
3. Add the SanFranciscoBaseMap map service to the ArcMap table of contents.
4. In the Catalog window, under your GIS Servers user connection node, expand the ShortestRouteService toolbox and open the Calculate Shortest Route and Text Directions tool. The illustration below shows the result of these steps:
5. Add two or more points to create stops. Optionally, specify names for each stop and click OK to run the task.

   After the task completes, the table of contents contains the Shortest Route output layer, as illustrated below. The input stops are not output from the task but are added to the table of contents from the Inputs node in the Results window.

   Task result

6. The text file containing the directions is copied from the jobs directory on the server to the scratch workspace for the current ArcMap session. The text file containing the directions can be viewed by double-clicking it in the Results window.

   Viewing the directions file

Generating HTML directions

The Directions tool used in the Calculate Shortest Route and Text Directions model can generate directions in text or XML format. The directions in XML format can be converted to a nicely formatted HTML file by applying a style sheet using a Python script. The script, ApplyStyleSheet.py, found in the Scripts folder within the ShortestRoute folder, can be used to convert directions from XML to HTML format. The scripts folder also contains the style sheet file, Dir2WebDocumentNoMaps.xsl, that specifies the format of the HTML file.

Scripts folder contents

Installing the external Python library

The ApplyStyleSheet.py script uses an external Python library, libxml2. This library is not provided with ArcGIS and is not supported by ESRI. It is external, third-party software. You will need to download and install this library on your ArcGIS Server SOC machines. Navigate to http://xmlsoft.org/sources/win32/python/, download the latest libxml2 setup for Python 2.6 (for example, libxml2-python-2.7.4.win32-py2.6.exe—earlier versions may not work). After downloading, double-click the executable file to install the library.

Creating the script tool

To use the ApplyStyleSheet.py script in the model, it is added to ShortestRouteService toolbox as a script tool called Convert Directions to HTML. This script tool takes the style sheet file and the XML file as input and generates an output HTML file.

Adding the script tool

Adding the script tool to the model

The Generate Shortest Route and Text Directions model is renamed and saved as Generate Shortest Route and HTML Directions so as to add the Convert Directions to HTML script tool. In this model, the output file type parameter for the Directions tool is changed to XML. This XML file and the Dir2WebDocumentNoMaps.xsl file are used as input variables for the script tool. The output HTML file is written to the jobs directory on the server using the %scratchworkspace% inline variable.

Publishing and using

The Calculate Shortest Route and HTML Directions model can be published as a new task within the ShortestRouteService geoprocessing service created earlier, as described below:

1. Create the Calculate Shortest Route and HTML Directions tool layer in ShortestRouteService.mxd by dragging the Calculate Shortest Route and HTML Directions model from the Catalog window to the ArcMap table of contents.
2. Save ShortestRouteService.mxd.
3. In the Catalog window, stop and start the ShortestRouteService geoprocessing service.

The ShortestRouteService service should now have a second task called Calculate Shortest Route and HTML Directions. This task is similar to the Calculate Shortest Route and Text Directions task except that it generates the directions in HTML format.

Directions in HTML format