Directions (Network Analyst)

Summary

Generates turn-by-turn directions from a network analysis layer with routes. The directions can be written to a file in text, XML, or HTML format. If you provide an appropriate stylesheet, the directions can be written to any other file format.

Usage

  • The tool solves the network analysis layer if it does not already have a valid result, so it is not required to solve the network analysis layer before generating directions.

Parameters

LabelExplanationData Type
Input Network Analysis Layer

Network analysis layer for which directions will be generated. Directions can be generated only for route, closest facility, and vehicle routing problem network analysis layers.

Network Analyst Layer
Output File Type

The format of the output directions file. This parameter is ignored if the stylesheet parameter has a value.

  • XML — The output directions file will be generated as an XML file. Apart from direction strings and the length and time information for the routes, the file will also contain information about the maneuver type and the turn angle for each direction.
  • Text — The output directions file will be generated as a simple TXT file containing the direction strings, the length and, optionally, the time information for the routes.
  • HTML —The output directions file will be generated as an HTML file containing the direction strings, the length and, optionally, the time information for the routes.
String
Output Directions File

The full path to the directions file that will be written.

If you provide a stylesheet in the Stylesheet parameter, make sure the file suffix for Output Directions File matches the file type your stylesheet produces.

File
Report Length in These Units

Specifies the linear units in which the length information will be reported in the directions file. For example, even though your impedance was in meters, you can show directions in miles.

  • Nautical miles —Nautical miles
  • Feet —Feet
  • Yards —Yards
  • Miles —Miles
  • Meters —Meters
  • Kilometers —Kilometers
String
Report Travel Time
(Optional)
  • Checked—Report travel times in the directions file. This is the default value.
  • Unchecked—Do not report travel times in the directions file.
Boolean
Time Attribute
(Optional)

The time-based cost attribute to provide travel times in the directions. The cost attribute must exist on the network dataset used by the input network analysis layer.

String
Language
(Optional)

Choose a language in which to generate driving directions.

The input for this parameter should be a two- or five-character language code representing one of the available languages for directions generation. In Python, you can retrieve a list of available language codes using the ListDirectionsLanguages function.

String
Style Name
(Optional)

Choose the name of the formatting style for the directions.

  • Printable driving directions —Printable turn-by-turn directions
  • Driving directions for a navigation device —Turn-by-turn directions designed for an in-vehicle navigation device
  • Walking directions —Turn-by-turn walking directions, which are designed for pedestrian routes
String
Stylesheet
(Optional)

The stylesheet for generating a formatted output file type (such as a PDF, Word, or HTML file). The suffix of the file in the output directions file parameter should match the file type that the stylesheet generates. The Directions tool overrides the output file type parameter if this parameter contains a value.

Tip:

If you want a head start on creating your own text and HTML stylesheets, copy and edit the stylesheets Network Analyst uses. You can find them in the following directory: <ArcGIS installation directory>\ArcGIS\ArcGIS Pro\Resources\NetworkAnalyst\Directions\Styles. The stylesheet is Dir2PHTML.xsl, and the text stylesheet is Dir2PlainText.xsl.

File

Derived Output

LabelExplanationData Type
Network Analysis Layer

The updated network analysis layer with routes.

Network Analyst Layer

arcpy.na.Directions(in_network_analysis_layer, file_type, out_directions_file, report_units, {report_time}, {time_attribute}, {language}, {style_name}, {stylesheet})
NameExplanationData Type
in_network_analysis_layer

Network analysis layer for which directions will be generated. Directions can be generated only for route, closest facility, and vehicle routing problem network analysis layers.

Network Analyst Layer
file_type

The format of the output directions file. This parameter is ignored if the stylesheet parameter has a value.

  • XMLThe output directions file will be generated as an XML file. Apart from direction strings and the length and time information for the routes, the file will also contain information about the maneuver type and the turn angle for each direction.
  • TEXTThe output directions file will be generated as a simple TXT file containing the direction strings, the length and, optionally, the time information for the routes.
  • HTMLThe output directions file will be generated as an HTML file containing the direction strings, the length and, optionally, the time information for the routes.
String
out_directions_file

If you provide a stylesheet in the stylesheet parameter, make sure the file suffix for out_directions_file matches the file type your stylesheet produces.

File
report_units

Specifies the linear units in which the length information will be reported in the directions file. For example, even though your impedance was in meters, you can show directions in miles.

  • FeetFeet
  • YardsYards
  • MilesMiles
  • MetersMeters
  • KilometersKilometers
  • NauticalMilesNautical miles
String
report_time
(Optional)
  • NO_REPORT_TIMEDo not report travel times in the directions file.
  • REPORT_TIMEReport travel times in the directions file. This is the default.
Boolean
time_attribute
(Optional)

The time-based cost attribute to provide travel times in the directions. The cost attribute must exist on the network dataset used by the input network analysis layer.

String
language
(Optional)

Choose a language in which to generate driving directions.

The input for this parameter should be a two- or five-character language code representing one of the available languages for directions generation. In Python, you can retrieve a list of available language codes using the ListDirectionsLanguages function.

String
style_name
(Optional)

Choose the name of the formatting style for the directions.

  • NA DesktopPrintable turn-by-turn directions
  • NA NavigationTurn-by-turn directions designed for an in-vehicle navigation device
  • NA CampusTurn-by-turn walking directions, which are designed for pedestrian routes
String
stylesheet
(Optional)

The stylesheet for generating a formatted output file type (such as a PDF, Word, or HTML file). The suffix of the file in the output directions file parameter should match the file type that the stylesheet generates. The Directions tool overrides the output file type parameter if this parameter contains a value.

Tip:

If you want a head start on creating your own text and HTML stylesheets, copy and edit the stylesheets Network Analyst uses. You can find them in the following directory: <ArcGIS installation directory>\ArcGIS\ArcGIS Pro\Resources\NetworkAnalyst\Directions\Styles. The stylesheet is Dir2PHTML.xsl, and the text stylesheet is Dir2PlainText.xsl.

File

Derived Output

NameExplanationData Type
output_layer

The updated network analysis layer with routes.

Network Analyst Layer

Code sample

Directions example 1 (Python window)

Execute the Directions tool with all the parameters.

arcpy.na.Directions("Route", "TEXT", "C:/Data/Route_Directions.txt", "Miles",
                    "REPORT_TIME", "Minutes")
Directions example 2 (workflow)

The following stand-alone Python script demonstrates how the Directions tool can be used to generate driving directions in a HTML file for a route.

# Name: Directions_Workflow.py
# Description: Generate driving directions in an html file for a route that
#              visits the store locations in the best sequence in order to
#              minimize the total travel time
# Requirements: Network Analyst Extension

#Import system modules
import arcpy
from arcpy import env
import os

try:
    #Check out Network Analyst license if available. Fail if the Network Analyst license is not available.
    if arcpy.CheckExtension("network") == "Available":
        arcpy.CheckOutExtension("network")
    else:
        raise arcpy.ExecuteError("Network Analyst Extension license is not available.")
    
    #Set environment settings
    output_dir = "C:/Data"
    #The NA layer's data will be saved to the workspace specified here
    env.workspace = os.path.join(output_dir, "Output.gdb")
    env.overwriteOutput = True

    #Set inputs and outputs
    input_gdb = "C:/Data/SanFrancisco.gdb"
    network = os.path.join(input_gdb, "Transportation", "Streets_ND")
    layer_name = "StoreRoute"
    travel_mode = "Driving Time"
    start_location = os.path.join(input_gdb, "Analysis", "DistributionCenter")
    store_locations = os.path.join(input_gdb, "Analysis", "Stores")
    output_directions = os.path.join(output_dir,
                                                layer_name + "_Directions.html")
    output_layer_file = os.path.join(output_dir, layer_name + ".lyrx")

    #Create a new route layer. The route starts at the distribution center and
    #visits the stores in the best order to yield the shortest travel time.
    result_object = arcpy.na.MakeRouteAnalysisLayer(network, layer_name,
                                        travel_mode, "PRESERVE_FIRST",
                                        time_of_day="8:00 AM")

    #Get the layer object from the result object. The route layer can
    #now be referenced using the layer object.
    layer_object = result_object.getOutput(0)

    #Get the names of all the sublayers within the route layer.
    sublayer_names = arcpy.na.GetNAClassNames(layer_object)
    #Stores the layer names that we will use later
    stops_layer_name = sublayer_names["Stops"]

    #Load the distribution center as the start location using default field
    #mappings and search tolerance
    arcpy.na.AddLocations(layer_object, stops_layer_name, start_location, "",
                                                                            "")

    #Load the store locations as stops. Make sure the store locations are
    #appended to the Stops sublayer so the distribution center you just loaded
    #isn't overwritten. Map the ServiceTime field from the input data to the
    #Attr_[impedance] property in the Stops sublayer so that the time it takes to
    #service each store is included in the total travel time for the route.
    #Figure out what the impedance attrbute is
    solver_props = arcpy.na.GetSolverProperties(layer_object)
    impedance = solver_props.impedance
    #Handle field mappings
    field_mappings = arcpy.na.NAClassFieldMappings(layer_object,
                                                            stops_layer_name)
    field_mappings["Name"].mappedFieldName = "Name"
    field_mappings["Attr_" + impedance].mappedFieldName = "ServiceTime"
    arcpy.na.AddLocations(layer_object, stops_layer_name, store_locations,
                          field_mappings, "", append="APPEND",
                          exclude_restricted_elements = "EXCLUDE")

    #Generate driving directions in an HTML file
    arcpy.na.Directions(layer_object, "HTML", output_directions, "Miles",
                        "REPORT_TIME", impedance)

    #Save the solved na layer as a layer file on disk
    layer_object.saveACopy(output_layer_file)

    print("Script completed successfully")

except Exception as e:
    # If an error occurred, print line number and error message
    import traceback, sys
    tb = sys.exc_info()[2]
    print("An error occurred on line %i" % tb.tb_lineno)
    print(str(e))

Environments

Licensing information

  • Basic: Requires Network Analyst
  • Standard: Requires Network Analyst
  • Advanced: Requires Network Analyst

Related topics