ArcGIS Server Banner

GP Service example: Shortest route on a street network

GP Service example: Shortest route on a street network

Release 9.3 E-mail This TopicPrintable VersionGive Us feedback


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 User digitizes two or more points.
Outputs

  1. A shortest route between the user-specified points based on the travel time.
  2. An HTML or Text file (depending on the task used) containing driving directions.
Data This example uses a street network dataset for 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 shows how an external Python library can be used from a script tool to convert driving directions from XML to HTML format.

Corresponding Folder

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

About this example

The ShortestRouteService created in this example shows you how to publish geoprocessing tasks that calculates 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 where as the Calculate Shortest Route and HTML Directions task generates driving directions in a HTML file. Both the tasks also output the shortest route as a feature class.

Example output from Calculate Shortest Route and Text Directions

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, DriveTime, which indicates the time taken to travel each street segment.

Basemap

The basemap for this example, 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

SanFranciscoBaseMap is published as a map service.

Toolbox and map document

The toolbox for the geoprocessing service is ShortestRouteService.tbx, and the source map document for the service is ShortestRouteService.mxd. ShortestRouteService.tbx contains two models and a script tool, Convert directions to HTML. This 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 variable, Input Stops, which are 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.

Calculate Shortest Route and Text Directions model

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 value (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 input variable in the model was created by first adding the Streets_ND network dataset to the ShortestRouteService.mxd and 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 DriveTime
Accumulators DriveTime;Meters
U-turn policy ALLOW_DEAD_ENDS_ONLY

Creating a route layer

Model Processes

The details about the model follow.

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 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 stops names while generating driving directions by mapping the Name property to the name field in the Field Mappings, as illustrated below. If the value for the name field is not specified by the user, a default value of Location 1, Location 2, and so on is 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 DriveTime 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.

Learn more about the Select Data tool.

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 %ScratchWorkspace%.

Generating driving directions

Tool layer

The Calculate Shortest Route and Text Directions layer is created by dragging and dropping 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 ArcCatalog, right-click SanFranciscoBaseMap.mxd and click Publish to ArcGIS Server.
  2. Accept all defaults.
  3. In ArcCatalog, navigate to your server, right-click and choose Add New Service. Name the service ShortestRouteService and choose Geoprocessing Service as the type.
  4. Click Next.
  5. In the next panel you choose Synchronous for Execution type. For the tools exposed by the Geoprocessing service are stored in option, select A map option and specify ShortestRouteService.mxd for the Map Document. Since you will test your service, check Show Messages.
  6. Publishing the ShortestRoute Service

  7. 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. Optionally, change the background color for the data frame to light blue.
  3. Add the SanFranciscoBasemap map service to the ArcMap table of contents.
  4. Add the ShortestRouteService geoprocessing service to ArcToolbox.
  5. Expand the ShortestRouteService toolbox and open the Calculate Shortest Route and Text Directions tool. The illustration below shows the result of these steps.
  6. Services in ArcMap session

  7. Add two or more points to create Stops. Optionally, specify names for each stop and click OK to run the task.
  8. After the task completes, the table of contents should have the Shortest Route output layer, as illustrated below. The input stops are added to the table of contents from the results tab.
  9. Task result

  10. The text file containing the directions can be viewed by double-clicking it in the results tab.
  11. Viewing directions file

Generating HTML directions

The Directions tool used in 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, lib2xml. 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.5 (for example, libxml2-python-2.6.30.win32-py2.5.exe — earlier versions may not work). After downloading, double-click the .exe to install the library.

Creating the script tool

In order to use the ApplyStyleSheet.py script in the model, it is added to ShoretestRouteService.tbx 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 resaved as Generate Shoretest 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 %ScratchWorkspace% in line variable.

Calculate Shortest Route and HTML Directions model

Publishing and using

The Calculate Shortest Route and HTML Directions model can be published as a new task with in 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 and dropping the Calculate Shortest Route and HTML Directions model from ArcToolbox to the ArcMap table of contents.
  2. Save ShortestRouteService.mxd.
  3. In ArcCatalog, 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

See Also

  • Guide to the geoprocessing service examples