Make Closest Facility Layer (Network Analyst)

Summary

Makes a closest facility network analysis layer and sets its analysis properties. A closest facility analysis layer is useful in determining the closest facility or facilities to an incident based on a specified network cost.

Usage

  • After creating the analysis layer with this tool, you can add network analysis objects to it using the Add Locations tool, solve the analysis using the Solve tool, and save the results on disk using the Save To Layer File tool.

  • When using this tool in geoprocessing models, if the model is run as a tool, the output network analysis layer must be made a model parameter; otherwise, the output layer is not added to the contents of the map.

Parameters

LabelExplanationData Type
Input Analysis Network

The network dataset on which the closest facility analysis will be performed.

Network Dataset Layer
Output Layer Name

Name of the closest facility network analysis layer to create.

String
Impedance Attribute

The cost attribute to be used as impedance in the analysis.

String
Travel From or To Facility
(Optional)

Specifies the direction of travel between facilities and incidents.

  • TRAVEL_FROMDirection of travel is from facilities to incidents. Fire departments commonly use the this setting, since they are concerned with the time it takes to travel from the fire station (facility) to the location of the emergency (incident).
  • TRAVEL_TODirection of travel is from incidents to facilities. Retail stores commonly use this setting, since they are concerned with the time it takes the shoppers (incidents) to reach the store (facility).

Using this option can find different facilities on a network with one-way restrictions and different impedances based on direction of travel. For instance, a facility may be a 10-minute drive from the incident while traveling from the incident to the facility, but while traveling from the facility to the incident, it may be a 15-minute journey because of different travel time in that direction.

String
Default Cutoff
(Optional)

Default impedance value at which to stop searching for facilities for a given incident. This default can be overridden by specifying the cutoff value on incidents when the direction of travel is from incidents to facilities or by specifying the cutoff value on facilities when the direction of travel is from facilities to incidents.

Double
Number of Facilities to Find
(Optional)

Default number of closest facilities to find per incident. The default can be overridden by specifying a value for the TargetFacilityCount property on the incidents.

Long
Accumulators
(Optional)

A list of cost attributes to be accumulated during analysis. These accumulation attributes are for reference only; the solver only uses the cost attribute specified by the Impedance Attribute parameter to calculate the route.

For each cost attribute that is accumulated, a Total_[Impedance] property is added to the routes that are output by the solver.

String
U-Turn Policy
(Optional)

Specifies the U-turn policy that will be used at junctions. Allowing U-turns implies that the solver can turn around at a junction and double back on the same street. Given that junctions represent street intersections and dead ends, different vehicles may be able to turn around at some junctions but not at others—it depends on whether the junction represents an intersection or a dead end. To accommodate this, the U-turn policy parameter is implicitly specified by the number of edges that connect to the junction, which is known as junction valency. The acceptable values for this parameter are listed below; each is followed by a description of its meaning in terms of junction valency.

  • ALLOW_UTURNSU-turns are permitted at junctions with any number of connected edges. This is the default value.
  • NO_UTURNSU-turns are prohibited at all junctions, regardless of junction valency. However, U-turns are still permitted at network locations even when this setting is chosen, but you can set the individual network location's CurbApproach property to prohibit U-turns there as well.
  • ALLOW_DEAD_ENDS_ONLYU-turns are prohibited at all junctions, except those that have only one adjacent edge (a dead end).
  • ALLOW_DEAD_ENDS_AND_INTERSECTIONS_ONLYU-turns are prohibited at junctions where exactly two adjacent edges meet but are permitted at intersections (junctions with three or more adjacent edges) and dead ends (junctions with exactly one adjacent edge). Often, networks have extraneous junctions in the middle of road segments. This option prevents vehicles from making U-turns at these locations.

If you need a more precisely defined U-turn policy, consider adding a global turn delay evaluator to a network cost attribute or adjusting its settings if one exists, and pay particular attention to the configuration of reverse turns. You can also set the CurbApproach property of your network locations.

String
Restrictions
(Optional)

A list of restriction attributes to be applied during the analysis.

String
Use Hierarchy in Analysis
(Optional)
  • Checked—The hierarchy attribute will be used for the analysis. Using a hierarchy results in the solver preferring higher-order edges to lower-order edges. Hierarchical solves are faster, and they can be used to simulate the preference of a driver who chooses to travel on freeways rather than local roads when possible—even if that means a longer trip. This option is active only if the input network dataset has a hierarchy attribute.
  • Unchecked—The hierarchy attribute will not be used for the analysis. If hierarchy is not used, the result is an exact route for the network dataset.

The parameter is inactive if a hierarchy attribute is not defined on the network dataset used to perform the analysis.

Boolean
Hierarchy Rank Settings
(Optional)

Legacy:

Prior to version 10, this parameter allowed you to change the hierarchy ranges for the analysis from the default hierarchy ranges established in the network dataset. At version 10, this parameter is no longer supported. To change the hierarchy ranges for the analysis, update the default hierarchy ranges in the network dataset.

Network Analyst Hierarchy Settings
Output Path Shape
(Optional)

Specifies the shape type that will be used for the route features that are output by the analysis.

  • TRUE_LINES_WITH_MEASURESThe output routes will have the exact shape of the underlying network sources. The output includes route measurements for linear referencing. The measurements increase from the first stop and record the cumulative impedance to reach a given position.
  • TRUE_LINES_WITHOUT_MEASURESThe output routes will have the exact shape of the underlying network sources.
  • STRAIGHT_LINESThe output route shape will be a single straight line between each paired incident and facility.
  • NO_LINESNo shape will be generated for the output routes.

Regardless of the output shape type specified, the best route is always determined by the network impedance, never Euclidean distance. This means that only the route shapes are different, not the underlying traversal of the network.

String
Time of Day
(Optional)

Specifies the time and date at which the routes should begin or end. The interpretation of this value depends on whether Time of Day Usage is set to be the start time or the end time of the route.

If you have chosen a traffic-based impedance attribute, the solution will be generated given dynamic traffic conditions at the time of day specified here. A date and time can be specified as 5/14/2012 10:30 AM.

Instead of using a particular date, a day of the week can be specified using the following dates.

  • Today—12/30/1899
  • Sunday—12/31/1899
  • Monday—1/1/1900
  • Tuesday—1/2/1900
  • Wednesday—1/3/1900
  • Thursday—1/4/1900
  • Friday—1/5/1900
  • Saturday—1/6/1900
For example, to specify that travel should begin at 5:00 PM on Tuesday, specify the parameter value as 1/2/1900 5:00 PM.

Date
Time of Day Usage
(Optional)

Indicates whether the value of the Time of Day parameter represents the arrival or departure time for the route or routes.

  • START_TIMETime of Day is interpreted as the departure time from the facility or incident.When this setting is chosen, Time of Day indicates the solver should find the best route given a departure time.
  • END_TIMETime of Day is interpreted as the arrival time at the facility or incident. This option is useful if you want to know what time to depart from a location so that you arrive at the destination at the time specified in Time of Day.
  • NOT_USEDWhen Time of Day doesn't have a value, this setting is the only choice. When Time of Day has a value, this setting isn't available.
String

Derived Output

LabelExplanationData Type
Network Analyst Layer

The newly created network analysis layer.

Network Analyst Layer

arcpy.management.MakeClosestFacilityLayer(in_network_dataset, out_network_analysis_layer, impedance_attribute, {travel_from_to}, {default_cutoff}, {default_number_facilities_to_find}, {accumulate_attribute_name}, {UTurn_policy}, {restriction_attribute_name}, {hierarchy}, {hierarchy_settings}, {output_path_shape}, {time_of_day}, {time_of_day_usage})
NameExplanationData Type
in_network_dataset

The network dataset on which the closest facility analysis will be performed.

Network Dataset Layer
out_network_analysis_layer

Name of the closest facility network analysis layer to create.

String
impedance_attribute

The cost attribute to be used as impedance in the analysis.

String
travel_from_to
(Optional)

Specifies the direction of travel between facilities and incidents.

  • TRAVEL_FROMDirection of travel is from facilities to incidents. Fire departments commonly use the this setting, since they are concerned with the time it takes to travel from the fire station (facility) to the location of the emergency (incident).
  • TRAVEL_TODirection of travel is from incidents to facilities. Retail stores commonly use this setting, since they are concerned with the time it takes the shoppers (incidents) to reach the store (facility).

Using this option can find different facilities on a network with one-way restrictions and different impedances based on direction of travel. For instance, a facility may be a 10-minute drive from the incident while traveling from the incident to the facility, but while traveling from the facility to the incident, it may be a 15-minute journey because of different travel time in that direction.

String
default_cutoff
(Optional)

Default impedance value at which to stop searching for facilities for a given incident. This default can be overridden by specifying the cutoff value on incidents when the direction of travel is from incidents to facilities or by specifying the cutoff value on facilities when the direction of travel is from facilities to incidents.

Double
default_number_facilities_to_find
(Optional)

Default number of closest facilities to find per incident. The default can be overridden by specifying a value for the TargetFacilityCount property on the incidents.

Long
accumulate_attribute_name
[accumulate_attribute_name,...]
(Optional)

A list of cost attributes to be accumulated during analysis. These accumulation attributes are for reference only; the solver only uses the cost attribute specified by the Impedance Attribute parameter to calculate the route.

For each cost attribute that is accumulated, a Total_[Impedance] property is added to the routes that are output by the solver.

String
UTurn_policy
(Optional)

Specifies the U-turn policy that will be used at junctions. Allowing U-turns implies that the solver can turn around at a junction and double back on the same street. Given that junctions represent street intersections and dead ends, different vehicles may be able to turn around at some junctions but not at others—it depends on whether the junction represents an intersection or a dead end. To accommodate this, the U-turn policy parameter is implicitly specified by the number of edges that connect to the junction, which is known as junction valency. The acceptable values for this parameter are listed below; each is followed by a description of its meaning in terms of junction valency.

  • ALLOW_UTURNSU-turns are permitted at junctions with any number of connected edges. This is the default value.
  • NO_UTURNSU-turns are prohibited at all junctions, regardless of junction valency. However, U-turns are still permitted at network locations even when this setting is chosen, but you can set the individual network location's CurbApproach property to prohibit U-turns there as well.
  • ALLOW_DEAD_ENDS_ONLYU-turns are prohibited at all junctions, except those that have only one adjacent edge (a dead end).
  • ALLOW_DEAD_ENDS_AND_INTERSECTIONS_ONLYU-turns are prohibited at junctions where exactly two adjacent edges meet but are permitted at intersections (junctions with three or more adjacent edges) and dead ends (junctions with exactly one adjacent edge). Often, networks have extraneous junctions in the middle of road segments. This option prevents vehicles from making U-turns at these locations.

If you need a more precisely defined U-turn policy, consider adding a global turn delay evaluator to a network cost attribute or adjusting its settings if one exists, and pay particular attention to the configuration of reverse turns. You can also set the CurbApproach property of your network locations.

String
restriction_attribute_name
[restriction_attribute_name,...]
(Optional)

A list of restriction attributes to be applied during the analysis.

String
hierarchy
(Optional)
  • USE_HIERARCHYThe hierarchy attribute will be used for the analysis. Using a hierarchy results in the solver preferring higher-order edges to lower-order edges. Hierarchical solves are faster, and they can be used to simulate the preference of a driver who chooses to travel on freeways rather than local roads when possible—even if that means a longer trip. This option is valid only if the input network dataset has a hierarchy attribute.
  • NO_HIERARCHYThe hierarchy attribute will not be used for the analysis. If hierarchy is not used, the result is an exact route for the network dataset.

The parameter is not used if a hierarchy attribute is not defined on the network dataset used to perform the analysis.

Boolean
hierarchy_settings
(Optional)

Legacy:

Prior to version 10, this parameter allowed you to change the hierarchy ranges for the analysis from the default hierarchy ranges established in the network dataset. At version 10, this parameter is no longer supported and should be specified as an empty string. To change the hierarchy ranges for the analysis, update the default hierarchy ranges in the network dataset.

Network Analyst Hierarchy Settings
output_path_shape
(Optional)

Specifies the shape type that will be used for the route features that are output by the analysis.

  • TRUE_LINES_WITH_MEASURESThe output routes will have the exact shape of the underlying network sources. The output includes route measurements for linear referencing. The measurements increase from the first stop and record the cumulative impedance to reach a given position.
  • TRUE_LINES_WITHOUT_MEASURESThe output routes will have the exact shape of the underlying network sources.
  • STRAIGHT_LINESThe output route shape will be a single straight line between each paired incident and facility.
  • NO_LINESNo shape will be generated for the output routes.

Regardless of the output shape type specified, the best route is always determined by the network impedance, never Euclidean distance. This means that only the route shapes are different, not the underlying traversal of the network.

String
time_of_day
(Optional)

Specifies the time and date at which the routes should begin or end. The interpretation of this value depends on whether Time of Day Usage is set to be the start time or the end time of the route.

If you have chosen a traffic-based impedance attribute, the solution will be generated given dynamic traffic conditions at the time of day specified here. A date and time can be specified as 5/14/2012 10:30 AM.

Instead of using a particular date, a day of the week can be specified using the following dates.

  • Today—12/30/1899
  • Sunday—12/31/1899
  • Monday—1/1/1900
  • Tuesday—1/2/1900
  • Wednesday—1/3/1900
  • Thursday—1/4/1900
  • Friday—1/5/1900
  • Saturday—1/6/1900
For example, to specify that travel should begin at 5:00 PM on Tuesday, specify the parameter value as 1/2/1900 5:00 PM.

Date
time_of_day_usage
(Optional)

Indicates whether the value of the Time of Day parameter represents the arrival or departure time for the route or routes.

  • START_TIMETime of Day is interpreted as the departure time from the facility or incident.When this setting is chosen, Time of Day indicates the solver should find the best route given a departure time.
  • END_TIMETime of Day is interpreted as the arrival time at the facility or incident. This option is useful if you want to know what time to depart from a location so that you arrive at the destination at the time specified in Time of Day.
  • NOT_USEDWhen Time of Day doesn't have a value, this setting is the only choice. When Time of Day has a value, this setting isn't available.
String

Derived Output

NameExplanationData Type
output_layer

The newly created network analysis layer.

Network Analyst Layer

Code sample

MakeClosestFacilityLayer example 1 (Python window)

Run the tool using only the required parameters.

network = "C:/Data/SanFrancisco.gdb/Transportation/Streets_ND"
arcpy.na.MakeClosestFacilityLayer(network, "ClosestFireStations", "TravelTime")
MakeClosestFacilityLayer example 2 (Python window)

Run the tool using all parameters.

network = "C:/Data/SanFrancisco.gdb/Transportation/Streets_ND"
arcpy.na.MakeClosestFacilityLayer(network, "ClosestHospitals", "TravelTime",
                                    "TRAVEL_TO", 5 ,3, ["Meters", "TravelTime"],
                                    "ALLOW_UTURNS", ["Oneway"], "USE_HIERARCHY",
                                    "", "TRUE_LINES_WITH_MEASURES")
MakeClosestFacilityLayer example 3 (workflow)

The following stand-alone Python script demonstrates how the MakeClosestFacilityLayer tool can be used to find the closest warehouse from the store locations.

# Name: MakeClosestFacilityLayer_Workflow.py
# Description: Find the closest warehouse from the store locations and save the
#              results to a layer file on disk.
# Requirements: Network Analyst Extension

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

try:
    #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 local variables
    input_gdb = "C:/Data/Paris.gdb"
    network = os.path.join(input_gdb, "Transportation", "ParisMultimodal_ND")
    layer_name = "ClosestWarehouse"
    impedance = "DriveTime"
    accumulate_attributes = ["Meters"]
    facilities = os.path.join(input_gdb, "Analysis", "Warehouses")
    incidents = os.path.join(input_gdb, "Analysis", "Stores")
    output_layer_file = os.path.join(output_dir, layer_name + ".lyrx")

    #Create a new closest facility analysis layer. Apart from finding the drive
    #time to the closest warehouse, we also want to find the total distance, so
    #we will accumulate the "Meters" impedance attribute.
    result_object = arcpy.na.MakeClosestFacilityLayer(network, layer_name,
                                                   impedance, "TRAVEL_TO",
                                                   "", 1, accumulate_attributes,
                                                   "NO_UTURNS")

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

    #Get the names of all the sublayers within the closest facility layer.
    sublayer_names = arcpy.na.GetNAClassNames(layer_object)
    #Stores the layer names that we will use later
    facilities_layer_name = sublayer_names["Facilities"]
    incidents_layer_name = sublayer_names["Incidents"]

    #Load the warehouses as Facilities using the default field mappings and
    #search tolerance
    arcpy.na.AddLocations(layer_object, facilities_layer_name,
                            facilities, "", "")

    #Load the stores as Incidents. Map the Name property from the NOM field
    #using field mappings
    field_mappings = arcpy.na.NAClassFieldMappings(layer_object,
                                                    incidents_layer_name)
    field_mappings["Name"].mappedFieldName = "NOM"
    arcpy.na.AddLocations(layer_object, incidents_layer_name, incidents,
                          field_mappings, "")

    #Solve the closest facility layer
    arcpy.na.Solve(layer_object)

    #Save the solved closest facility 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