Find Closest Facilities (Ready To Use)

Summary

Finds one or more facilities that are closest from an incident based on travel time or travel distance and outputs the best routes, driving directions between the incidents and the chosen facilities, and a copy of the chosen facilities. You can use the tool, for example, to find the closest hospital to an accident, the closest police cars to a crime scene, or the closest store to a customer's address.

When finding closest facilities, you can specify how many to find and whether the direction of travel is toward or away from them. You can also specify the time of day to account for travel times based on live or predictive traffic conditions for that time and date. For instance, you can use the tool to search for hospitals within a 15-minute drive time of the site of an accident at a given time of day. Any hospitals that take longer than 15 minutes to reach based on the traffic conditions will not be included in the results.

Legacy:
This is a deprecated tool.

Illustration

FindClosestFacilities results

Usage

  • Tools in the Ready To Use toolbox are ArcGIS Online geoprocessing services that use ArcGIS Online hosted data and analysis capabilities.

  • The tool finds the closest facilities based on travel time if the value for the Measurement Units parameter is time based. Similarly, the tool uses travel distance if the measurement units are distance based.

  • You must specify at least one facility and one incident to successfully run the tool. You can load up to 5,000 facilities and 5,000 incidents, and you can find up to 100 closest facilities from each incident. So each solve of the tool is capable of finding up to 500,000 closest facilities.

  • You can add up to 250 point barriers. You can add any number of line or polygon barriers, but line barriers cannot intersect more than 500 street features, and polygon barriers can't intersect more than 2,000 features.

  • You can choose to use the road hierarchy when solving so that results are generated quicker, but the solution may be less than optimal.

  • Regardless of whether the Use Hierarchy parameter is checked (True), hierarchy is used when the straight-line distance between any pair of features representing incidents or facilities is greater than 50 miles (80.46 kilometers).

  • The straight-line distance between any pair of features representing incidents or facilities cannot be greater than 27 miles (43.45 kilometers) when Travel Mode is set to Walking, or when it is set to Custom and the Walking restriction is used.

  • If the distance between an input point and its nearest traversable street is greater than 12.42 miles (20 kilometers), the point is excluded from the analysis.

  • Using this service consumes credits. For more information, see Service Credits Overview.

Parameters

LabelExplanationData Type
Incidents

The locations that will be used as starting or ending points in a closest facility analysis.

You can specify one or more incidents (up to 5,000). These are the locations from which the tool searches for the nearby locations.

When specifying the incidents, you can set properties for each—such as its name or service time—using the following attributes:

Name

The name of the incident. The name is used in the driving directions. If the name is not specified, a unique name prefixed with Location is automatically generated in the output routes and directions.

ID

A unique identifier for the incident. The identifier is included in the output routes (as the IncidentID field) and can help join additional information from the output routes, such as the total travel time or total distance, to attributes from your incidents or vice versa. If the ID isn't specified, the service automatically generates a unique identifier for each incident.

AdditionalTime

The amount of time spent at the incident, which is added to the total time of the route. The default value is 0.

The units for this attribute value are specified by the Measurement Units parameter. The attribute value is included in the analysis only when the measurement units are time based.

If you are finding the closest fire stations to fire incidents to estimate response times, for example, the AdditionalTime attribute can store the amount of time it takes firefighters to hook up their equipment at the location of the incident before they can begin fighting the fire.

AdditionalDistance

The extra distance traveled at the incident, which is added to the total distance of the route. The default value is 0.

The units for this attribute value are specified by the Measurement Units parameter. The attribute value is included in the analysis only when the measurement units are distance based.

Generally, the location of an incident, such as a home, isn't exactly on the street; it is set back somewhat from the road. This attribute value can be used to model the distance between the incident location and its location on the street if it is important to include that distance in the total travel distance.

AdditionalCost

The extra cost spent at the incident, which is added to the total cost of the route. The default value is 0.

This attribute value should be used when the travel mode for the analysis uses an impedance attribute that is neither time based nor distance based The units for the attribute values are interpreted to be in unknown units.

TargetFacilityCount

The number of facilities that need to be found for the given incident. This field allows you to specify a different number of facilities to find for each incident. For example, using this field you can find the three closest facilities from one incident and the two closest facilities from another incident.

Cutoff

The impedance value at which to stop searching for facilities from a given incident. This attribute allows you to specify a different cutoff value for each incident. For example, using this attribute you can search for facilities within five minutes travel time from one incident and search for facilities within eight minutes travel time from another incident.

CurbApproach

Specifies the direction a vehicle may arrive at and depart from the incident. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (Either side of vehicle)—The vehicle can approach and depart the incident in either direction, so a U-turn is allowed at the incident. This setting can be chosen if it is possible and practical for a vehicle to turn around at the incident. This decision may depend on the width of the road and the amount of traffic or whether the incident has a parking lot where vehicles can pull in and turn around.
  • 1 (Right side of vehicle)—When the vehicle approaches and departs the incident, the curb must be on the right side of the vehicle. A U-turn is prohibited. This is typically used for vehicles such as buses that must arrive with the bus stop on the right-hand side.
  • 2 (Left side of vehicle)—When the vehicle approaches and departs the incident, the curb must be on the left side of the vehicle. A U-turn is prohibited. This is typically used for vehicles such as buses that must arrive with the bus stop on the left-hand side.
  • 3 (No U-Turn)—When the vehicle approaches the incident, the curb can be on either side of the vehicle; however, the vehicle must depart without turning around.

The CurbApproach attribute is designed to work with both types of national driving standards: right-hand traffic (United States) and left-hand traffic (United Kingdom). First, consider an incident on the left side of a vehicle. It is always on the left side regardless of whether the vehicle travels on the left or right half of the road. What may change with national driving standards is your decision to approach an incident from one of two directions, that is, so it ends up on the right or left side of the vehicle. For example, if you want to arrive at an incident and not have a lane of traffic between the vehicle and the incident, choose 1 (Right side of vehicle) in the United States and 2 (Left side of vehicle) in the United Kingdom.

Bearing

The direction in which a point is moving. The units are degrees and are measured clockwise from true north. This field is used in conjunction with the BearingTol field.

Bearing data is usually sent automatically from a mobile device equipped with a GPS receiver. Try to include bearing data if you are loading an input location that is moving, such as a pedestrian or a vehicle.

Using this field tends to prevent adding locations to the wrong edges, which can occur when a vehicle is near an intersection or an overpass, for example. Bearing also helps the tool determine on which side of the street the point is.

BearingTol

The bearing tolerance value creates a range of acceptable bearing values when locating moving points on an edge using the Bearing field. If the Bearing field value is within the range of acceptable values that are generated from the bearing tolerance on an edge, the point can be added as a network location there; otherwise, the closest point on the next-nearest edge is evaluated.

The units are in degrees, and the default value is 30. Values must be greater than 0 and less than 180. A value of 30 means that when Network Analyst attempts to add a network location on an edge, a range of acceptable bearing values is generated 15 degrees to either side of the edge (left and right) and in both digitized directions of the edge.

NavLatency

This field is only used in the solve process if the Bearing and BearingTol fields also have values; however, entering a NavLatency field value is optional, even when values are present in Bearing and BearingTol. NavLatency indicates how much cost is expected to elapse from the moment GPS information is sent from a moving vehicle to a server and the moment the processed route is received by the vehicle's navigation device.

The units of NavLatency are the same as the units of the impedance attribute.

Feature Set
Facilities

The locations that will be used as starting or ending points in a closest facility analysis.

You can specify one or more facilities (up to 5,000). These are the locations that are searched for when finding the closest location.

When specifying the facilities, you can set properties for each—such as its name or service time—using the following attributes:

Name

The name of the facility. The name is used in the driving directions. If the name is not specified, a unique name prefixed with Location is automatically generated in the output routes and directions.

ID

A unique identifier for the facility. The identifier is included in the output routes and the output closest facilities as FacilityID fields. The FacilityID field can be used to join additional information from the output routes, such as the total travel time or total distance, to attributes from your facilities. If the ID isn't specified, the service automatically generates a unique identifier for each facility.

AdditionalTime

The amount of time spent at the facility, which is added to the total time of the route. The default value is 0.

The units for this attribute value are specified by the Measurement Units parameter. The attribute value is included in the analysis only when the measurement units are time based.

If you are finding the closest fire stations to fire incidents, for example, AdditionalTime can store the time it takes a crew to don the appropriate protective equipment and exit the fire station.

AdditionalDistance

The extra distance traveled at the facility, which is added to the total distance of the route. The default value is 0.

The units for this attribute value are specified by the Measurement Units parameter. The attribute value is included in the analysis only when the measurement units are distance based.

Generally, the location of a facility, such as a fire station, isn't exactly on the street; it is set back somewhat from the road. AdditionalDistance can model the distance between the facility location and its location on the street if it is important to include that distance in the total travel distance.

AdditionalCost

The extra cost spent at the facility, which is added to the total cost of the route. The default value is 0.

This attribute value should be used when the travel mode for the analysis uses an impedance attribute that is neither time based nor distance based The units for the attribute values are interpreted to be in unknown units.

Cutoff

The impedance value at which to stop searching for incidents from a given facility. This attribute allows you to specify a different cutoff value for each facility. For example, using this attribute you can search for incidents within five minutes of travel time from one facility and search for incidents within eight minutes of travel time from another facility.

CurbApproach

Specifies the direction a vehicle may arrive at and depart from the facility.

  • 0 (Either side of vehicle)—The vehicle can approach and depart the facility in either direction, so a U-turn is allowed at the facility. This setting can be chosen if it is possible and practical for a vehicle to turn around at the facility. This decision may depend on the width of the road and the amount of traffic or whether the facility has a parking lot where vehicles can pull in and turn around.
  • 1 (Right side of vehicle)—When the vehicle approaches and departs the facility, the facility must be on the right side of the vehicle. A U-turn is prohibited. This is typically used for vehicles such as buses that must arrive with the bus stop on the right-hand side.
  • 2 (Left side of vehicle)—When the vehicle approaches and departs the facility, the curb must be on the left side of the vehicle. A U-turn is prohibited. This is typically used for vehicles such as buses that must arrive with the bus stop on the left-hand side.
  • 3 (No U-Turn)—When the vehicle approaches the facility, the curb can be on either side of the vehicle; however, the vehicle must depart without turning around.

The CurbApproach attribute is designed to work with both types of national driving standards: right-hand traffic (United States) and left-hand traffic (United Kingdom). First, consider a facility on the left side of a vehicle. It is always on the left side regardless of whether the vehicle travels on the left or right half of the road. What may change with national driving standards is your decision to approach a facility from one of two directions, that is, so it ends up on the right or left side of the vehicle. For example, if you want to arrive at a facility and not have a lane of traffic between the vehicle and the facility, choose 1 (Right side of vehicle) in the United States and 2 (Left side of vehicle) in the United Kingdom.

Bearing

The direction in which a point is moving. The units are degrees and are measured clockwise from true north. This field is used in conjunction with the BearingTol field.

Bearing data is usually sent automatically from a mobile device equipped with a GPS receiver. Try to include bearing data if you are loading an input location that is moving, such as a pedestrian or a vehicle.

Using this field tends to prevent adding locations to the wrong edges, which can occur when a vehicle is near an intersection or an overpass, for example. Bearing also helps the tool determine on which side of the street the point is.

BearingTol

The bearing tolerance value creates a range of acceptable bearing values when locating moving points on an edge using the Bearing field. If the Bearing field value is within the range of acceptable values that are generated from the bearing tolerance on an edge, the point can be added as a network location there; otherwise, the closest point on the next-nearest edge is evaluated.

The units are in degrees, and the default value is 30. Values must be greater than 0 and less than 180. A value of 30 means that when Network Analyst attempts to add a network location on an edge, a range of acceptable bearing values is generated 15 degrees to either side of the edge (left and right) and in both digitized directions of the edge.

NavLatency

This field is only used in the solve process if the Bearing and BearingTol fields also have values; however, entering a NavLatency field value is optional, even when values are present in Bearing and BearingTol. NavLatency indicates how much cost is expected to elapse from the moment GPS information is sent from a moving vehicle to a server and the moment the processed route is received by the vehicle's navigation device.

The units of NavLatency are the same as the units of the impedance attribute.

Feature Set
Measurement Units

Specifies the units that will be used to measure and report the total travel time or travel distance for the output routes. The tool finds the closest facility by measuring the travel time or the travel distance along the streets.

The units specified for this parameter determine whether the tool will measure driving distance or driving time to find what is closest. Choose a time unit to measure driving time. To measure driving distance, choose a distance unit. Your choice also determines the units in which the tool will report total driving time or distance in the results.

  • MetersThe linear unit will be meters.
  • KilometersThe linear unit will be kilometers.
  • FeetThe linear unit will be feet.
  • YardsThe linear unit will be yards.
  • MilesThe linear unit will be miles.
  • Nautical MilesThe linear unit will be nautical miles.
  • SecondsThe time unit will be seconds.
  • MinutesThe time unit will be minutes.
  • HoursThe time unit will be hours.
  • DaysThe time unit will be days.
String
Analysis Region
(Optional)

The region in which the analysis will be performed. If a value is not specified for this parameter, the tool will automatically calculate the region name based on the location of the input points. Setting the name of the region is required only if the automatic detection of the region name is not accurate for the inputs.

To specify a region, use one of the following values:

  • EuropeThe analysis region will be Europe.
  • JapanThe analysis region will be Japan.
  • KoreaThe analysis region will be Korea.
  • Middle East And AfricaThe analysis region will be Middle East and Africa.
  • North AmericaThe analysis region will be North America.
  • South AmericaThe analysis region will be South America.
  • South AsiaThe analysis region will be South Asia.
  • ThailandThe analysis region will be Thailand.
Legacy:

The following region names are no longer supported and will be removed in future releases. If you specify one of the deprecated region names, the tool automatically assigns a supported region name for the region.

  • Greece redirects to Europe
  • India redirects to SouthAsia
  • Oceania redirects to SouthAsia
  • SouthEastAsia redirects to SouthAsia
  • Taiwan redirects to SouthAsia

String
Number of Facilities to Find
(Optional)

The number of closest facilities to find per incident. This is useful in situations in which multiple fire engines may be required from different fire stations, such as a fire. You can specify, for example, to find the three nearest fire stations to a fire.

The value set in this parameter can be overridden on a per-incident basis using the TargetFacilityCount field in the input incidents.

The tool can find up to 100 facilities from each incident.

Long
Cutoff
(Optional)

The travel time or travel distance value at which to stop searching for facilities for a given incident. For example, while finding the closest hospitals from the site of an accident, a cutoff value of 15 minutes means that the tool will search for the closest hospital within 15 minutes from the incident. If the closest hospital is 17 minutes away, no routes will be returned in the output routes. A cutoff value is especially useful when searching for multiple facilities.

When the Travel Direction parameter is set to Facility to Incident, the cutoff can be overridden on a per-facility basis using the Cutoff field in the input facilities. When the Travel Direction parameter is set to Incident To Facility, the cutoff can be overridden on a per-incident basis using the Cutoff field in the input incidents.

The units for this parameter are specified by the Measurement Units parameter.

Double
Travel Direction
(Optional)

Specifies how the travel direction for the closest facility search will be measured.

Each option may find different facilities, as the travel time along some streets may vary based on the travel direction and one-way restrictions. 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 drive because of different travel time in that direction.

If you are also setting a value for the Time of Day parameter, traffic may also cause the Facility to Incident and Incident to Facility options to return different results.

Fire departments commonly use the Facility to Incident value for the parameter, since they are concerned with the time it takes to travel from the fire station (facility) to the location of the emergency (incident). Management at a retail store (facility) is more concerned with the time it takes shoppers (incidents) to reach the store (facility); therefore, store management commonly chooses Incident to Facility.

  • Facility to IncidentThe direction of travel is from facilities to incidents.
  • Incident to FacilityThe direction of travel is from incidents to facilities.
String
Use Hierarchy
(Optional)

Specifies whether hierarchy will be used when finding the best route between the facility and the incident.

  • Checked (True in Python)—Hierarchy will be used when finding routes. When hierarchy is used, the tool identifies higher-order streets (such as freeways) before lower-order streets (such as local roads) and can be used to simulate the driver preference of traveling on freeways instead of local roads even if that means a longer trip. This is especially useful when finding routes to faraway facilities, because drivers on long-distance trips tend to prefer traveling on freeways, where stops, intersections, and turns can be avoided. Using hierarchy is computationally faster, especially for long-distance routes, as the tool identifies the best route from a relatively smaller subset of streets.
  • Unchecked (False in Python)—Hierarchy will not be used when finding routes. If hierarchy is not used, the tool considers all the streets and doesn't necessarily identify higher-order streets when finding the route. This is often used for finding short-distance routes within a city.

The tool automatically reverts to using hierarchy if the straight-line distance between facilities and incidents is greater than 50 miles, even if this parameter is Unchecked (set to False in Python).

Boolean
Time of Day
(Optional)

The time and date the route will begin or end. The value is used as the start time or end time for the route depending on the value for the Time of Day Usage parameter. If you specify the current date and time as the value for this parameter, the tool will use live traffic conditions to find the closest facility, and the total travel time will be based on traffic conditions.

Specifying a time of day results in a more accurate estimation of travel time between the incident and facility because the travel time accounts for the traffic conditions that are applicable for that date and time.

The Time Zone for Time of Day parameter specifies whether this time and date refer to UTC or the time zone in which the facility or incident is located.

Date
Time of Day Usage
(Optional)

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

  • Start TimeThe tool considers the Time of Day parameter value as the departure time from the facility or incident to find the best route.
  • End TimeThe tool considers the Time of Day parameter value as the arrival time at the facility or incident to find the best route. This option is useful if you want to know the time to depart from a location so you arrive at the destination at the time specified in Time of Day.
String
UTurn at Junctions
(Optional)

Specifies the U-turn policy at junctions. Allowing U-turns implies 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 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.

This parameter is ignored unless Travel Mode is set to Custom.

  • AllowedU-turns are permitted at junctions with any number of connected edges. This is the default value.
  • Not AllowedU-turns are prohibited at all junctions, regardless of junction valency. However, U-turns are still permitted at network locations even when this option is chosen, but you can set the individual network locations' CurbApproach attribute to prohibit U-turns there as well.
  • Allowed only at Dead EndsU-turns are prohibited at all junctions except those that have only one adjacent edge (a dead end).
  • Allowed only at Intersections and Dead EndsU-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.
String
Point Barriers
(Optional)

Use this parameter to specify one or more points that will act as temporary restrictions or represent additional time or distance that may be required to travel on the underlying streets. For example, a point barrier can be used to represent a fallen tree along a street or a time delay spent at a railroad crossing.

The tool imposes a limit of 250 points that can be added as barriers.

When specifying point barriers, you can set properties for each, such as its name or barrier type, using the following attributes:

Name

The name of the barrier.

BarrierType

Specifies whether the point barrier restricts travel completely or adds time or distance when it is crossed. The value for this attribute is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (Restriction)—Prohibits travel through the barrier. The barrier is referred to as a restriction point barrier since it acts as a restriction.

  • 2 (Added Cost)—Traveling through the barrier increases the travel time or distance by the amount specified in the Additional_Time, Additional_Distance, or AdditionalCost field. This barrier type is referred to as an added cost point barrier.

Additional_Time

The added travel time when the barrier is traversed. This field is applicable only for added-cost barriers and when the Measurement Units parameter value is time based.

This field value must be greater than or equal to zero, and its units must be the same as those specified in the Measurement Units parameter.

Additional_Distance

The added distance when the barrier is traversed. This field is applicable only for added-cost barriers and when the Measurement Units parameter value is distance based.

The field value must be greater than or equal to zero, and its units must be the same as those specified in the Measurement Units parameter.

AdditionalCost

The added cost when the barrier is traversed. This field is applicable only for added-cost barriers when the Measurement Units parameter value is neither time based nor distance based.

FullEdge

Specifies how the restriction point barriers are applied to the edge elements during the analysis. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (False)—Permits travel on the edge up to the barrier but not through it. This is the default value.
  • 1 (True)—Restricts travel anywhere on the associated edge.

CurbApproach

Specifies the direction of traffic that is affected by the barrier. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (Either side of vehicle)—The barrier affects travel over the edge in both directions.
  • 1 (Right side of vehicle)—Vehicles are only affected if the barrier is on their right side during the approach. Vehicles that traverse the same edge but approach the barrier on their left side are not affected by the barrier.
  • 2 (Left side of vehicle)—Vehicles are only affected if the barrier is on their left side during the approach. Vehicles that traverse the same edge but approach the barrier on their right side are not affected by the barrier.

Because junctions are points and don't have a side, barriers on junctions affect all vehicles regardless of the curb approach.

The CurbApproach attribute works with both types of national driving standards: right-hand traffic (United States) and left-hand traffic (United Kingdom). First, consider a facility on the left side of a vehicle. It is always on the left side regardless of whether the vehicle travels on the left or right half of the road. What may change with national driving standards is your decision to approach a facility from one of two directions, that is, so it ends up on the right or left side of the vehicle. For example, to arrive at a facility and not have a lane of traffic between the vehicle and the facility, choose 1 (Right side of vehicle) in the United States and 2 (Left side of vehicle) in the United Kingdom.

Bearing

The direction in which a point is moving. The units are degrees and are measured clockwise from true north. This field is used in conjunction with the BearingTol field.

Bearing data is usually sent automatically from a mobile device equipped with a GPS receiver. Try to include bearing data if you are loading an input location that is moving, such as a pedestrian or a vehicle.

Using this field tends to prevent adding locations to the wrong edges, which can occur when a vehicle is near an intersection or an overpass, for example. Bearing also helps the tool determine on which side of the street the point is.

BearingTol

The bearing tolerance value creates a range of acceptable bearing values when locating moving points on an edge using the Bearing field. If the Bearing field value is within the range of acceptable values that are generated from the bearing tolerance on an edge, the point can be added as a network location there; otherwise, the closest point on the next-nearest edge is evaluated.

The units are in degrees, and the default value is 30. Values must be greater than 0 and less than 180. A value of 30 means that when Network Analyst attempts to add a network location on an edge, a range of acceptable bearing values is generated 15 degrees to either side of the edge (left and right) and in both digitized directions of the edge.

NavLatency

This field is only used in the solve process if the Bearing and BearingTol fields also have values; however, entering a NavLatency field value is optional, even when values are present in Bearing and BearingTol. NavLatency indicates how much cost is expected to elapse from the moment GPS information is sent from a moving vehicle to a server and the moment the processed route is received by the vehicle's navigation device.

The units of NavLatency are the same as the units of the impedance attribute.

Feature Set
Line Barriers
(Optional)

Use this parameter to specify one or more lines that prohibit travel anywhere the lines intersect the streets. For example, a parade or protest that blocks traffic across several street segments can be modeled with a line barrier. A line barrier can also quickly fence off several roads from being traversed, thereby channeling possible routes away from undesirable parts of the street network.

The tool imposes a limit on the number of streets you can restrict using the Line Barriers parameter. While there is no limit to the number of lines you can specify as line barriers, the combined number of streets intersected by all the lines cannot exceed 500.

When specifying the line barriers, you can set name and barrier type properties for each using the following attributes:

Name

The name of the barrier.

Feature Set
Polygon Barriers
(Optional)

Use this parameter to specify polygons that either completely restrict travel or proportionately scale the time or distance required to travel on the streets intersected by the polygons.

The service imposes a limit on the number of streets you can restrict using the Polygon Barriers parameter. While there is no limit to the number of polygons you can specify as polygon barriers, the combined number of streets intersected by all the polygons cannot exceed 2,000.

When specifying the polygon barriers, you can set properties for each, such as its name or barrier type, using the following attributes:

Name

The name of the barrier.

BarrierType

Specifies whether the barrier restricts travel completely or scales the cost (such as time or distance) for traveling through it. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (Restriction)—Prohibits traveling through any part of the barrier. The barrier is referred to as a restriction polygon barrier since it prohibits traveling on streets intersected by the barrier. One use of this type of barrier is to model floods covering areas of the street that make traveling on those streets impossible.

  • 1 (Scaled Cost)—Scales the cost (such as travel time or distance) required to travel the underlying streets by a factor specified using the ScaledTimeFactor or ScaledDistanceFactor field. If the streets are partially covered by the barrier, the travel time or distance is apportioned and then scaled. For example, a factor of 0.25 means that travel on underlying streets is expected to be four times faster than normal. A factor of 3.0 means it is expected to take three times longer than normal to travel on underlying streets. This barrier type is referred to as a scaled-cost polygon barrier. It can be used to model storms that reduce travel speeds in specific regions, for example.

ScaledTimeFactor

This is the factor by which the travel time of the streets intersected by the barrier is multiplied. The field value must be greater than zero.

This field is applicable only for scaled-cost barriers and when the Measurement Units parameter is time-based.

ScaledDistanceFactor

This is the factor by which the distance of the streets intersected by the barrier is multiplied. The field value must be greater than zero.

This field is applicable only for scaled-cost barriers and when the Measurement Units parameter is distance-based.

ScaledCostFactor

This is the factor by which the cost of the streets intersected by the barrier is multiplied. The field value must be greater than zero.

This field is applicable only for scaled-cost barriers when the Measurement Units parameter is neither time-based nor distance-based.

Feature Set
Restrictions
(Optional)

The restrictions that will be honored by the tool when finding the best routes.

A restriction represents a driving preference or requirement. In most cases, restrictions cause roads to be prohibited. For instance, using the Avoid Toll Roads restriction will result in a route that will include toll roads only when it is required to travel on toll roads to visit an incident or a facility. Height Restriction makes it possible to route around any clearances that are lower than the height of the vehicle. If you are carrying corrosive materials on the vehicle, using the Any Hazmat Prohibited restriction prevents hauling the materials along roads where it is marked illegal to do so.

Note:

Some restrictions require an additional value to be specified for their use. This value must be associated with the restriction name and a specific parameter intended to work with the restriction. You can identify such restrictions if their names appear in the AttributeName column of the Attribute Parameter Values parameter. Specify the ParameterValue field for the Attribute Parameter Values parameter for the restriction to be correctly used when finding traversable roads.

Note:

Some restrictions are supported only in certain countries; their availability is stated by region in the list below. Of the restrictions that have limited availability within a region, you can determine whether the restriction is available in a particular country by reviewing the table in the Country list section of Network analysis coverage. If a country has a value of Yes in the Logistics Attribute column, the restriction with select availability in the region is supported in that country. If you specify restriction names that are not available in the country where your incidents are located, the service ignores the invalid restrictions. The service also ignores restrictions when the Restriction Usage attribute parameter value is between 0 and 1 (see the Attribute Parameter Value parameter). It prohibits all restrictions when the Restriction Usage parameter value is greater than 0.

The tool supports the following restrictions:

  • Any Hazmat ProhibitedThe results will not include roads where transporting any kind of hazardous material is prohibited. Availability: Select countries in North America and Europe
  • Avoid Carpool RoadsThe results will avoid roads that are designated exclusively for car pool (high-occupancy) vehicles. Availability: All countries
  • Avoid Express LanesThe results will avoid roads designated as express lanes. Availability: All countries
  • Avoid FerriesThe results will avoid ferries. Availability: All countries
  • Avoid GatesThe results will avoid roads where there are gates, such as keyed access or guard-controlled entryways.Availability: All countries
  • Avoid Limited Access RoadsThe results will avoid roads that are limited-access highways.Availability: All countries
  • Avoid Private RoadsThe results will avoid roads that are not publicly owned and maintained.Availability: All countries
  • Avoid Roads Unsuitable for PedestriansThe results will avoid roads that are unsuitable for pedestrians.Availability: All countries
  • Avoid StairwaysThe results will avoid all stairways on a pedestrian-suitable route.Availability: All countries
  • Avoid Toll RoadsThe results will avoid all toll roads for automobiles.Availability: All countries
  • Avoid Toll Roads for TrucksThe results will avoid all toll roads for trucks.Availability: All countries
  • Avoid Truck Restricted RoadsThe results will avoid roads where trucks are not allowed, except when making deliveries.Availability: All countries
  • Avoid Unpaved RoadsThe results will avoid roads that are not paved (for example, dirt, gravel, and so on). Availability: All countries
  • Axle Count RestrictionThe results will not include roads where trucks with the specified number of axles are prohibited. The number of axles can be specified using the Number of Axles restriction parameter.Availability: Select countries in North America and Europe
  • Driving a BusThe results will not include roads where buses are prohibited. Using this restriction will also ensure that the results will honor one-way streets. Availability: All countries
  • Driving a TaxiThe results will not include roads where taxis are prohibited. Using this restriction will also ensure that the results will honor one-way streets. Availability: All countries
  • Driving a TruckThe results will not include roads where trucks are prohibited. Using this restriction will also ensure that the results will honor one-way streets. Availability: All countries
  • Driving an AutomobileThe results will not include roads where automobiles are prohibited. Using this restriction will also ensure that the results will honor one-way streets. Availability: All countries
  • Driving an Emergency VehicleThe results will not include roads where emergency vehicles are prohibited. Using this restriction will also ensure that the results will honor one-way streets.Availability: All countries
  • Height RestrictionThe results will not include roads where the vehicle height exceeds the maximum allowed height for the road. The vehicle height can be specified using the Vehicle Height (meters) restriction parameter. Availability: Select countries in North America and Europe
  • Kingpin to Rear Axle Length RestrictionThe results will not include roads where the vehicle length exceeds the maximum allowed kingpin to rear axle for all trucks on the road. The length between the vehicle kingpin and the rear axle can be specified using the Vehicle Kingpin to Rear Axle Length (meters) restriction parameter. Availability: Select countries in North America and Europe
  • Length RestrictionThe results will not include roads where the vehicle length exceeds the maximum allowed length for the road. The vehicle length can be specified using the Vehicle Length (meters) restriction parameter. Availability: Select countries in North America and Europe
  • Preferred for PedestriansThe results will use preferred routes suitable for pedestrian navigation. Availability: Select countries in North America and Europe
  • Riding a MotorcycleThe results will not include roads where motorcycles are prohibited. Using this restriction will also ensure that the results will honor one-way streets.Availability: All countries
  • Roads Under Construction ProhibitedThe results will not include roads that are under construction.Availability: All countries
  • Semi or Tractor with One or More Trailers ProhibitedThe results will not include roads where semis or tractors with one or more trailers are prohibited. Availability: Select countries in North America and Europe
  • Single Axle Vehicles ProhibitedThe results will not include roads where vehicles with single axles are prohibited.Availability: Select countries in North America and Europe
  • Tandem Axle Vehicles ProhibitedThe results will not include roads where vehicles with tandem axles are prohibited.Availability: Select countries in North America and Europe
  • Through Traffic ProhibitedThe results will not include roads where through traffic (nonlocal) is prohibited.Availability: All countries
  • Truck with Trailers RestrictionThe results will not include roads where trucks with the specified number of trailers on the truck are prohibited. The number of trailers on the truck can be specified using the Number of Trailers on Truck restriction parameter.Availability: Select countries in North America and Europe
  • Use Preferred Hazmat RoutesThe results will prefer roads that are designated for transporting any kind of hazardous materials. Availability: Select countries in North America and Europe
  • Use Preferred Truck RoutesThe results will prefer roads that are designated as truck routes, such as the roads that are part of the national network as specified by the National Surface Transportation Assistance Act in the United States, or roads that are designated as truck routes by the state or province, or roads that are preferred by truckers when driving in an area.Availability: Select countries in North America and Europe
  • WalkingThe results will not include roads where pedestrians are prohibited.Availability: All countries
  • Weight RestrictionThe results will not include roads where the vehicle weight exceeds the maximum allowed weight for the road. The vehicle weight can be specified using the Vehicle Weight (kilograms) restriction parameter.Availability: Select countries in North America and Europe
  • Weight per Axle RestrictionThe results will not include roads where the vehicle weight per axle exceeds the maximum allowed weight per axle for the road. The vehicle weight per axle can be specified using the Vehicle Weight per Axle (kilograms) restriction parameter.Availability: Select countries in North America and Europe
  • Width RestrictionThe results will not include roads where the vehicle width exceeds the maximum allowed width for the road. The vehicle width can be specified using the Vehicle Width (meters) restriction parameter.Availability: Select countries in North America and Europe
Note:

The values you provide for this parameter are ignored unless Travel Mode is set to Custom.

String
Attribute Parameter Values
(Optional)

Use this parameter to specify additional values required by an attribute or restriction, such as to specify whether the restriction prohibits, avoids, or prefers travel on restricted roads. If the restriction is meant to avoid or prefer roads, you can further specify the degree to which they are avoided or preferred using this parameter. For example, you can choose to never use toll roads, avoid them as much as possible, or prefer them.

Note:

The values you provide for this parameter are ignored unless Travel Mode is set to Custom.

If you specify the Attribute Parameter Values parameter from a feature class, the field names on the feature class must match the fields as follows:

  • AttributeName—The name of the restriction.
  • ParameterName—The name of the parameter associated with the restriction. A restriction can have one or more ParameterName field values based on its intended use.
  • ParameterValue—The value for ParameterName used by the tool when evaluating the restriction.

The Attribute Parameter Values parameter is dependent on the Restrictions parameter. The ParameterValue field is applicable only if the restriction name is specified as the value for the Restrictions parameter.

In Attribute Parameter Values, each restriction (listed as AttributeName) has a ParameterName field value, Restriction Usage, that specifies whether the restriction prohibits, avoids, or prefers travel on the roads associated with the restriction as well as the degree to which the roads are avoided or preferred. The Restriction Usage ParameterName can be assigned any of the following string values or their equivalent numeric values listed in the parentheses:

  • PROHIBITED (-1)—Travel on the roads using the restriction is completely prohibited.
  • AVOID_HIGH (5)—It is highly unlikely the tool will include in the route the roads that are associated with the restriction.
  • AVOID_MEDIUM (2)—It is unlikely the tool will include in the route the roads that are associated with the restriction.
  • AVOID_LOW (1.3)—It is somewhat unlikely the tool will include in the route the roads that are associated with the restriction.
  • PREFER_LOW (0.8)—It is somewhat likely the tool will include in the route the roads that are associated with the restriction.
  • PREFER_MEDIUM (0.5)—It is likely the tool will include in the route the roads that are associated with the restriction.
  • PREFER_HIGH (0.2)—It is highly likely the tool will include in the route the roads that are associated with the restriction.

In most cases, you can use the default value, PROHIBITED, as the Restriction Usage value if the restriction is dependent on a vehicle characteristic such as vehicle height. However, in some cases, the Restriction Usage value depends on your routing preferences. For example, the Avoid Toll Roads restriction has the default value of AVOID_MEDIUM for the Restriction Usage attribute. This means that when the restriction is used, the tool will route around toll roads when it can. AVOID_MEDIUM also indicates how important it is to avoid toll roads when finding the best route; it has a medium priority. Choosing AVOID_LOW puts lower importance on avoiding tolls; choosing AVOID_HIGH instead gives it a higher importance and makes it more acceptable for the service to generate longer routes to avoid tolls. Choosing PROHIBITED entirely disallows travel on toll roads, making it impossible for a route to travel on any portion of a toll road. Keep in mind that avoiding or prohibiting toll roads, and avoiding toll payments, is the objective for some. In contrast, others prefer to drive on toll roads, because avoiding traffic is more valuable to them than the money spent on tolls. In the latter case, choose PREFER_LOW, PREFER_MEDIUM, or PREFER_HIGH as the value for Restriction Usage. The higher the preference, the farther the tool will go to travel on the roads associated with the restriction.

Record Set
Route Shape
(Optional)

Specifies the type of route features that will be output by the tool.

When the Route Shape parameter is set to True Shape or True Shape with Measures, the generalization of the route shape can be further controlled using the appropriate value for the Route Line Simplification Tolerance parameter.

No matter which value you choose for the Route Shape parameter, the best route is always determined by minimizing the travel time or the travel distance, never using the straight-line distance between stops. This means that only the route shapes are different, not the underlying streets that are searched when finding the route.

  • True ShapeThe exact shape of the resulting route that is based on the underlying streets will be returned.
  • True Shape with MeasuresThe exact shape of the resulting route that is based on the underlying streets will be returned. Additionally, construct measures so the shape can be used in linear referencing. The measurements increase from the first stop and record the cumulative travel time or travel distance in the units specified by the Measurement Units parameter.
  • Straight LineA straight line between two stops will be returned.
  • NoneNo shapes for the routes will be returned. This value can be useful, and return results quickly, when you are only interested in determining the total travel time or travel distance of a route.
String
Route Line Simplification Tolerance
(Optional)

The distance that will be used to simplify the geometry of the output lines for routes and directions.

The tool ignores this parameter if the Route Shape parameter isn't set to True Shape.

Simplification maintains critical points on a route, such as turns at intersections, to define the essential shape of the route and removes other points. The simplification distance you specify is the maximum allowable offset that the simplified line can deviate from the original line. Simplifying a line reduces the number of vertices that are part of the route geometry. This improves the tool processing time.

Linear Unit
Populate Directions
(Optional)

Specifies whether the tool will generate driving directions for each route.

  • Checked (True in Python)—Directions will be generated and configured based on the values of the Directions Language, Directions Style Name, and Directions Distance Units parameters.
  • Unchecked (False in Python)—Directions will not be generated, and the tool will return an empty Directions layer.

Boolean
Directions Language
(Optional)

The language that will be used when generating travel directions.

This parameter is used only when the Populate Directions parameter is checked (True in Python).

The parameter value can be specified using one of the following two- or five-character language codes:

  • ar—Arabic
  • bg—Bulgarian
  • bs—Bosnian
  • ca—Catalan
  • cs—Czech
  • da—Danish
  • de—German
  • el—Greek
  • en—English
  • es—Spanish
  • et—Estonian
  • fi—Finnish
  • fr—French
  • he—Hebrew
  • hr—Croatian
  • hu—Hungarian
  • id—Indonesian
  • it—Italian
  • ja—Japanese
  • ko—Korean
  • lt—Lithuanian
  • lv—Latvian
  • nb—Norwegian
  • nl—Dutch
  • pl—Polish
  • pt-BR—Portuguese (Brazil)
  • pt-PT—Portuguese (Portugal)
  • ro—Romanian
  • ru—Russian
  • sk—Slovak
  • sl—Slovenian
  • sr—Serbian
  • sv—Swedish
  • th—Thai
  • tr—Turkish
  • uk—Ukrainian
  • vi—Vietnamese
  • zh-CN—Chinese (China)
  • zh-HK—Chinese (Hong Kong)
  • zh-TW—Chinese (Taiwan)

The tool first searches for an exact match for the specified language including any language localization. If an exact match is not found, it tries to match the language family. If a match is still not found, the tool returns the directions using the default language, English. For example, if the directions language is specified as es-MX (Mexican Spanish), the tool will return the directions in Spanish, as it supports the es language code but not es-MX.

Caution:

If a language supports localization, such as Brazilian Portuguese (pt-BR) and European Portuguese (pt-PT), specify the language family and the localization. If you only specify the language family, the tool will not match the language family and instead return directions in the default language, English. For example, if the directions language specified is pt, the tool will return the directions in English since it cannot determine whether the directions should be returned in pt-BR or pt-PT.

String
Directions Distance Units
(Optional)

Specifies the units that will display travel distance in the driving directions. This parameter is used only when the Populate Directions parameter is checked (True in Python).

  • MilesThe linear unit will be miles.
  • KilometersThe linear unit will be kilometers.
  • MetersThe linear unit will be meters.
  • FeetThe linear unit will be feet.
  • YardsThe linear unit will be yards.
  • Nautical MilesThe linear unit will be nautical miles.
String
Directions Style Name
(Optional)

Specifies the name of the formatting style for the directions. This parameter is used only when the Populate Directions parameter is checked (True in Python).

  • Network Analyst DesktopThe style will be turn-by-turn directions suitable for printing.
  • Network Analyst NavigationThe style will be turn-by-turn directions designed for an in-vehicle navigation device.
String
Time Zone for Time of Day
(Optional)

Specifies the time zone of the Time of Day parameter.

Regardless of the Time Zone for Time of Day setting, if your facilities and incidents are in multiple time zones, the following rules are enforced by the tool. All incidents and facilities must be in the same time zone for the following:

  • Specifying a start time and traveling from incident to facility
  • Specifying an end time and traveling from facility to incident
  • Specifying a start time and traveling from facility to incident
  • Specifying an end time and traveling from incident to facility

  • Geographically LocalThe Time of Day parameter refers to the time zone in which the facilities or incidents are located.If Time of Day Usage is set to Start Time and Travel Direction is Facility to Incident, this is the time zone of the facilities. If Time of Day Usage is set to Start Time and Travel Direction is Incident to Facility, this is the time zone of the incidents. If Time of Day Usage is set to End Time and Travel Direction is Facility to Incident, this is the time zone of the incidents. If Time of Day Usage is set to End Time and Travel Direction is Incident to Facility, this is the time zone of the facilities.
  • UTCThe Time of Day parameter refers to coordinated universal time (UTC). Choose this option if you want to find what's nearest for a specific time, such as now, but aren't certain in which time zone the facilities or incidents will be located.
String
Travel Mode
(Optional)

The mode of transportation to model in the analysis. Travel modes are managed in ArcGIS Online and can be configured by the administrator of your organization to reflect the organization's workflows. Specify the name of a travel mode that is supported by your organization.

To get a list of supported travel mode names, run the Get Travel Modes tool from the Utilities toolbox under the same GIS Server connection you used to access the tool. The Get Travel Modes tool adds a table, Supported Travel Modes, to the application. Any value in the Travel Mode Name field from the Supported Travel Modes table can be specified as input. You can also specify the value from the Travel Mode Settings field as input. This speeds up tool execution, as the tool does not have to find the settings based on the travel mode name.

The default value, Custom, allows you to configure a custom travel mode using the custom travel mode parameters (UTurn at Junctions, Use Hierarchy, Restrictions, Attribute Parameter Values, and Impedance). The default values of the custom travel mode parameters model traveling by car. You can also choose Custom and set the custom travel mode parameters listed above to model a pedestrian with a fast walking speed or a truck with a given height, weight, and cargo of certain hazardous materials. You can try different settings to get the analysis results you want. Once you have identified the analysis settings, work with your organization's administrator and save these settings as part of a new or existing travel mode so that everyone in your organization can run the analysis with the same settings.

Caution:

When you choose Custom, the values you set for the custom travel mode parameters are included in the analysis. Specifying another travel mode, as defined by your organization, causes any values you set for the custom travel mode parameters to be ignored; the tool overrides them with values from the specified travel mode.

String
Impedance
(Optional)

Specifies the impedance, which is a value that represents the effort or cost of traveling along road segments or on other parts of the transportation network.

Travel time is an impedance: a car may take 1 minute to travel a mile along an empty road. Travel times can vary by travel mode—a pedestrian may take more than 20 minutes to walk the same mile, so it is important to choose the right impedance for the travel mode you are modeling.

Travel distance can also be an impedance; the length of a road in kilometers can be thought of as impedance. Travel distance in this sense is the same for all modes—a kilometer for a pedestrian is also a kilometer for a car. (What may change is the pathways on which the different modes are allowed to travel, which affects distance between points, and this is modeled by travel mode settings.)

If you choose a time-based impedance, such as TravelTime, TruckTravelTime, Minutes, TruckMinutes, or WalkTime, the Break Units parameter must be set to a time-based value; if you choose a distance-based impedance such as Miles or Kilometers, Break Units must be a distance-based value.

  • Travel TimeHistorical and live traffic data is used. This option is good for modeling the time it takes automobiles to travel along roads at a specific time of day using live traffic speed data where available. When using TravelTime, you can optionally set the TravelTime::Vehicle Maximum Speed (km/h) attribute parameter to specify the physical limitation of the speed the vehicle is capable of traveling.
  • MinutesLive traffic data is not used, but historical average speeds for automobiles data is used.
  • Truck Travel TimeHistorical and live traffic data is used, but the speed is capped at the posted truck speed limit. This is good for modeling the time it takes for the trucks to travel along roads at a specific time. When using TruckTravelTime, you can optionally set the TruckTravelTime::Vehicle Maximum Speed (km/h) attribute parameter to specify the physical limitation of the speed the truck is capable of traveling.
  • Truck MinutesLive traffic data is not used, but the smaller of the historical average speeds for automobiles and the posted speed limits for trucks is used.
  • Walk TimeThe default is a speed of 5 km/hr on all roads and paths, but this can be configured through the WalkTime::Walking Speed (km/h) attribute parameter.
  • MilesLength measurements along roads are stored in miles and can be used for performing analysis based on shortest distance.
  • KilometersLength measurements along roads are stored in kilometers and can be used for performing analysis based on shortest distance.
  • Time At One Kilometer Per HourThe default is a speed of 1 km/hr on all roads and paths. The speed cannot be changed using any attribute parameter.
  • Drive TimeTravel times for a car are modeled. These travel times are dynamic and fluctuate according to traffic flows in areas where traffic data is available. This is the default value.
  • Truck TimeTravel times for a truck are modeled. These travel times are static for each road and don't fluctuate with traffic.
  • Walk TimeTravel times for a pedestrian are modeled.
  • Travel DistanceLength measurements along roads and paths are stored. To model walk distance, choose this option and ensure that Walking is set for the Restriction parameter. Similarly, to model drive or truck distance, choose Travel Distance here and set the appropriate restrictions so the vehicle travels only on roads where it is permitted to do so.
Caution:

The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value.

Legacy:

Drive Time, Truck Time, Walk Time, and Travel Distance impedance values are no longer supported and will be removed in a future release. If you use one of these values, the tool uses the value of the Time Impedance parameter for time-based values and the Distance Impedance parameter for distance-based values.

String
Save Output Network Analysis Layer
(Optional)

Specifies whether the analysis settings will be saved as a network analysis layer file. You cannot directly work with this file even when you open the file in an ArcGIS Desktop application such as ArcMap. It is meant to be sent to Esri Technical Support to diagnose the quality of results returned from the tool.

  • Checked (True in Python)—The output will be saved as a network analysis layer file. The file will be downloaded to a temporary directory on your machine. In ArcGIS Pro, the location of the downloaded file can be determined by viewing the value for the Output Network Analysis Layer parameter in the entry corresponding to the tool service in the geoprocessing history of the project. In ArcMap, the location of the file can be determined by accessing the Copy Location option in the shortcut menu of the Output Network Analysis Layer parameter in the entry corresponding to the tool service in the Geoprocessing Results window.
  • Unchecked (False in Python)—The output will not be saved as a network analysis layer file. This is the default.

Boolean
Overrides
(Optional)

Note:

This parameter is for internal use only.

String
Save Route Data
(Optional)

Specifies whether the output will include a .zip file that contains a file geodatabase with the inputs and outputs of the analysis in a format that can be used to share route layers with ArcGIS Online or Portal for ArcGIS.

  • Checked (True in Python)—The route data will be saved as a .zip file. The file is downloaded to a temporary directory on your machine. In ArcGIS Pro, the location of the downloaded file can be determined by viewing the value for the Output Route Data parameter in the entry corresponding to the tool operation in the geoprocessing history of the project. In ArcMap, the location of the file can be determined by accessing the Copy Location option in the shortcut menu of the Output Route Data parameter in the entry corresponding to the tool operation in the Geoprocessing Results window.
  • Unchecked (False in Python)—The route data will not be saved as a .zip file. This is the default.

Boolean
Time Impedance
(Optional)

The time-based impedance value represents the travel time along road segments or on other parts of the transportation network.

  • MinutesTime impedance will be minutes.
  • Travel TimeTime impedance will be travel time.
  • Time At One Kilometer Per HourTime impedance will be time at one kilometer per hour.
  • Walk TimeTime impedance will be walk time.
  • Truck MinutesTime impedance will be truck minutes.
  • Truck Travel TimeTime impedance will be truck travel time.
Note:
If the impedance for the travel mode, as specified using the Impedance parameter, is time based, the values for the Time Impedance and Impedance parameters must be identical. Otherwise, the service will return an error.
String
Distance Impedance
(Optional)

The distance-based impedance value represents the travel distance along road segments or on other parts of the transportation network.

  • MilesDistance impedance will be miles.
  • KilometersDistance impedance will be kilometers.
Note:
If the impedance for the travel mode, as specified using the Impedance parameter, is distance based, the values for the Distance Impedance and Impedance parameters must be identical. Otherwise, the service will return an error.
String
Output Format
(Optional)

Specifies the format in which the output features will be returned.

When a file-based output format, such as JSON File or GeoJSON File, is specified, no outputs will be added to the display because the application, such as ArcMap or ArcGIS Pro, cannot draw the contents of the result file. Instead, the result file is downloaded to a temporary directory on your machine. In ArcGIS Pro, the location of the downloaded file can be determined by viewing the value for the Output Result File parameter in the entry corresponding to the tool operation in the geoprocessing history of the project. In ArcMap, the location of the file can be determined by accessing the Copy Location option in the shortcut menu of the Output Result File parameter in the entry corresponding to the tool operation in the Geoprocessing Results window.

  • Feature SetThe output features will be returned as feature classes and tables. This is the default.
  • JSON FileThe output features will be returned as a compressed file containing the JSON representation of the outputs. When this option is specified, the output is a single file (with a .zip extension) that contains one or more JSON files (with a .json extension) for each of the outputs created by the service.
  • GeoJSON FileThe output features will be returned as a compressed file containing the GeoJSON representation of the outputs. When this option is specified, the output is a single file (with a .zip extension) that contains one or more GeoJSON files (with a .geojson extension) for each of the outputs created by the service.
String
Ignore Invalid Locations
(Optional)

Specifies whether invalid input locations will be ignored.

  • Checked—Network locations that are unlocated will be ignored and the analysis will run using valid network locations only. The analysis will also continue if locations are on non-traversable elements or have other errors. This is useful if you know the network locations are not all correct, but you want to run the analysis with the network locations that are valid. This is the default.
  • Unchecked—Invalid locations will not be ignored. Do not run the analysis if there are invalid locations. Correct the invalid locations and rerun the analysis.
Boolean
Locate Settings
(Optional)

Use this parameter to specify settings that affect how inputs are located, such as the maximum search distance to use when locating the inputs on the network, or the network sources being used for locating.

Learn more about locating inputs

The parameter value is specified as a JSON object. The JSON object allows you to specify a locator JSON for all input feature in the analysis, or optionally you could specify an override for a particular input. The override allows you to have different settings for each analysis input.

The locator JSON object has following properties:

  • tolerance and toleranceUnits—Allows you to control the maximum search distance when locating inputs. If no valid network location is found within this distance, the input features will be considered unlocated. A small search tolerance decreases the likelihood of locating on the wrong street but increases the likelihood of not finding any valid network location. The toleranceUnits parameter value should be specified as one of the following values:
    • esriCentimeters
    • esriDecimalDegrees
    • esriDecimeters
    • esriFeet
    • esriInches
    • esriIntFeet
    • esriIntInches
    • esriIntMiles
    • esriIntNauticalMiles
    • esriIntYards
    • esriKilometers
    • esriMeters
    • esriMiles
    • esriMillimeters
    • esriNauticalMiles
    • esriYards
  • sources— Allows you to control which network source can be used for locating. For example, you can configure the analysis to locate inputs on streets but not on sidewalks. The list of possible sources on which to locate is specific to the network dataset this service references. Only the sources that are present in the sources array are used for locating. Sources is specified as an array of objects each having the following property:
    • name—Name of the network source feature class that can be used for locating inputs.
  • allowAutoRelocate—Allows you to control whether inputs with existing network location fields can be automatically relocated when solving to ensure valid, routable location fields for the analysis. If the value is true, points located on restricted network elements and points affected by barriers will be relocated to the closest routable location. If the value is false, network location fields will be used as is even if the points are unreachable, and this may cause the solve to fail. Even if the value is false, inputs with no location fields or incomplete location fields will be located during solve.
Note:
At this point, the sources array doesn't allow to specify different source names. Also, allowAutoRelocate is always set to true since the service does not support location fields.

Locate_Settings JSON object allows you to specify a default locator JSON object for all input features in the analysis, as well as overrides for each input class. When specifying Locate_Settings JSON, you need to provide the following properties: tolerance, toleranceUnits, and allowAutoRelocate. If you need to provide a different locator JSON for a particular input class, you need to include overrides property for that input. The property name must match the input parameter name. The locator JSON for a particular input doesn't need to include all the properties; you only need to include the properties that are different from the default locator JSON properties.

String

Derived Output

LabelExplanationData Type
Output Routes

This provides access to the resulting route or routes between the facilities and the incidents.

Feature Set
Output Directions

This provides access to the turn-by-turn directions for each resulting route.

Feature Set
Solve Succeeded

Indicates whether solving the closest facility analysis succeeded.

Boolean
Output Closest Facilities

This provides access to the output facilities from a closest facility analysis.

Feature Set
Output Network Analysis Layer

The network analysis layer, with properties configured in the tool parameters, that can be used for further analysis or debugging in the map.

File
Output Route Data

A .zip file containing all the information for a particular route.

File
Output Incidents

This provides access to the locations used as starting or ending points in a closest facility analysis.

Feature Set
Output Facilities

The facilities used in the analysis.

Feature Set
Output Result File

A .zip file containing the results of the analysis with one or more files for each output. The format of the individual files is specified by the Output Format parameter.

File
Output Network Analysis Layer Package

A layer package that includes a network analysis layer with the data and settings used in the analysis.

File
Output Direction Points

This parameter provides access to turn-by-turn directions for the routes calculated in the analysis, represented as point locations along the routes where specific directions events or maneuvers occur.

Feature Set
Output Direction Lines

This parameter provides access to the route lines calculated in the analysis, sliced to represent each route segment between DirectionPoints events or maneuver locations.

Feature Set
Usage Cost

This parameter returns the credits used by the analysis.

Note:

Each analysis can generate a different number of billable objects and thus will use different number of credits. If the service fails to determine credits, the usage_cost parameter returns a value of -1 for credits.

JSON

arcpy.agolservices.FindClosestFacilities(Incidents, Facilities, Measurement_Units, {Analysis_Region}, {Number_of_Facilities_to_Find}, {Cutoff}, {Travel_Direction}, {Use_Hierarchy}, {Time_of_Day}, {Time_of_Day_Usage}, {UTurn_at_Junctions}, {Point_Barriers}, {Line_Barriers}, {Polygon_Barriers}, {Restrictions}, {Attribute_Parameter_Values}, {Route_Shape}, {Route_Line_Simplification_Tolerance}, {Populate_Directions}, {Directions_Language}, {Directions_Distance_Units}, {Directions_Style_Name}, {Time_Zone_for_Time_of_Day}, {Travel_Mode}, {Impedance}, {Save_Output_Network_Analysis_Layer}, {Overrides}, {Save_Route_Data}, {Time_Impedance}, {Distance_Impedance}, {Output_Format}, {Ignore_Invalid_Locations}, {Locate_Settings})
NameExplanationData Type
Incidents

The locations that will be used as starting or ending points in a closest facility analysis.

You can specify one or more incidents (up to 5,000). These are the locations from which the tool searches for the nearby locations.

When specifying the incidents, you can set properties for each—such as its name or service time—using the following attributes:

Name

The name of the incident. The name is used in the driving directions. If the name is not specified, a unique name prefixed with Location is automatically generated in the output routes and directions.

ID

A unique identifier for the incident. The identifier is included in the output routes (as the IncidentID field) and can help join additional information from the output routes, such as the total travel time or total distance, to attributes from your incidents or vice versa. If the ID isn't specified, the service automatically generates a unique identifier for each incident.

AdditionalTime

The amount of time spent at the incident, which is added to the total time of the route. The default value is 0.

The units for this attribute value are specified by the Measurement Units parameter. The attribute value is included in the analysis only when the measurement units are time based.

If you are finding the closest fire stations to fire incidents to estimate response times, for example, the AdditionalTime attribute can store the amount of time it takes firefighters to hook up their equipment at the location of the incident before they can begin fighting the fire.

AdditionalDistance

The extra distance traveled at the incident, which is added to the total distance of the route. The default value is 0.

The units for this attribute value are specified by the Measurement Units parameter. The attribute value is included in the analysis only when the measurement units are distance based.

Generally, the location of an incident, such as a home, isn't exactly on the street; it is set back somewhat from the road. This attribute value can be used to model the distance between the incident location and its location on the street if it is important to include that distance in the total travel distance.

AdditionalCost

The extra cost spent at the incident, which is added to the total cost of the route. The default value is 0.

This attribute value should be used when the travel mode for the analysis uses an impedance attribute that is neither time based nor distance based The units for the attribute values are interpreted to be in unknown units.

TargetFacilityCount

The number of facilities that need to be found for the given incident. This field allows you to specify a different number of facilities to find for each incident. For example, using this field you can find the three closest facilities from one incident and the two closest facilities from another incident.

Cutoff

The impedance value at which to stop searching for facilities from a given incident. This attribute allows you to specify a different cutoff value for each incident. For example, using this attribute you can search for facilities within five minutes travel time from one incident and search for facilities within eight minutes travel time from another incident.

CurbApproach

Specifies the direction a vehicle may arrive at and depart from the incident. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (Either side of vehicle)—The vehicle can approach and depart the incident in either direction, so a U-turn is allowed at the incident. This setting can be chosen if it is possible and practical for a vehicle to turn around at the incident. This decision may depend on the width of the road and the amount of traffic or whether the incident has a parking lot where vehicles can pull in and turn around.
  • 1 (Right side of vehicle)—When the vehicle approaches and departs the incident, the curb must be on the right side of the vehicle. A U-turn is prohibited. This is typically used for vehicles such as buses that must arrive with the bus stop on the right-hand side.
  • 2 (Left side of vehicle)—When the vehicle approaches and departs the incident, the curb must be on the left side of the vehicle. A U-turn is prohibited. This is typically used for vehicles such as buses that must arrive with the bus stop on the left-hand side.
  • 3 (No U-Turn)—When the vehicle approaches the incident, the curb can be on either side of the vehicle; however, the vehicle must depart without turning around.

The CurbApproach attribute is designed to work with both types of national driving standards: right-hand traffic (United States) and left-hand traffic (United Kingdom). First, consider an incident on the left side of a vehicle. It is always on the left side regardless of whether the vehicle travels on the left or right half of the road. What may change with national driving standards is your decision to approach an incident from one of two directions, that is, so it ends up on the right or left side of the vehicle. For example, if you want to arrive at an incident and not have a lane of traffic between the vehicle and the incident, choose 1 (Right side of vehicle) in the United States and 2 (Left side of vehicle) in the United Kingdom.

Bearing

The direction in which a point is moving. The units are degrees and are measured clockwise from true north. This field is used in conjunction with the BearingTol field.

Bearing data is usually sent automatically from a mobile device equipped with a GPS receiver. Try to include bearing data if you are loading an input location that is moving, such as a pedestrian or a vehicle.

Using this field tends to prevent adding locations to the wrong edges, which can occur when a vehicle is near an intersection or an overpass, for example. Bearing also helps the tool determine on which side of the street the point is.

BearingTol

The bearing tolerance value creates a range of acceptable bearing values when locating moving points on an edge using the Bearing field. If the Bearing field value is within the range of acceptable values that are generated from the bearing tolerance on an edge, the point can be added as a network location there; otherwise, the closest point on the next-nearest edge is evaluated.

The units are in degrees, and the default value is 30. Values must be greater than 0 and less than 180. A value of 30 means that when Network Analyst attempts to add a network location on an edge, a range of acceptable bearing values is generated 15 degrees to either side of the edge (left and right) and in both digitized directions of the edge.

NavLatency

This field is only used in the solve process if the Bearing and BearingTol fields also have values; however, entering a NavLatency field value is optional, even when values are present in Bearing and BearingTol. NavLatency indicates how much cost is expected to elapse from the moment GPS information is sent from a moving vehicle to a server and the moment the processed route is received by the vehicle's navigation device.

The units of NavLatency are the same as the units of the impedance attribute.

Feature Set
Facilities

The locations that will be used as starting or ending points in a closest facility analysis.

You can specify one or more facilities (up to 5,000). These are the locations that are searched for when finding the closest location.

When specifying the facilities, you can set properties for each—such as its name or service time—using the following attributes:

Name

The name of the facility. The name is used in the driving directions. If the name is not specified, a unique name prefixed with Location is automatically generated in the output routes and directions.

ID

A unique identifier for the facility. The identifier is included in the output routes and the output closest facilities as FacilityID fields. The FacilityID field can be used to join additional information from the output routes, such as the total travel time or total distance, to attributes from your facilities. If the ID isn't specified, the service automatically generates a unique identifier for each facility.

AdditionalTime

The amount of time spent at the facility, which is added to the total time of the route. The default value is 0.

The units for this attribute value are specified by the Measurement Units parameter. The attribute value is included in the analysis only when the measurement units are time based.

If you are finding the closest fire stations to fire incidents, for example, AdditionalTime can store the time it takes a crew to don the appropriate protective equipment and exit the fire station.

AdditionalDistance

The extra distance traveled at the facility, which is added to the total distance of the route. The default value is 0.

The units for this attribute value are specified by the Measurement Units parameter. The attribute value is included in the analysis only when the measurement units are distance based.

Generally, the location of a facility, such as a fire station, isn't exactly on the street; it is set back somewhat from the road. AdditionalDistance can model the distance between the facility location and its location on the street if it is important to include that distance in the total travel distance.

AdditionalCost

The extra cost spent at the facility, which is added to the total cost of the route. The default value is 0.

This attribute value should be used when the travel mode for the analysis uses an impedance attribute that is neither time based nor distance based The units for the attribute values are interpreted to be in unknown units.

Cutoff

The impedance value at which to stop searching for incidents from a given facility. This attribute allows you to specify a different cutoff value for each facility. For example, using this attribute you can search for incidents within five minutes of travel time from one facility and search for incidents within eight minutes of travel time from another facility.

CurbApproach

Specifies the direction a vehicle may arrive at and depart from the facility.

  • 0 (Either side of vehicle)—The vehicle can approach and depart the facility in either direction, so a U-turn is allowed at the facility. This setting can be chosen if it is possible and practical for a vehicle to turn around at the facility. This decision may depend on the width of the road and the amount of traffic or whether the facility has a parking lot where vehicles can pull in and turn around.
  • 1 (Right side of vehicle)—When the vehicle approaches and departs the facility, the facility must be on the right side of the vehicle. A U-turn is prohibited. This is typically used for vehicles such as buses that must arrive with the bus stop on the right-hand side.
  • 2 (Left side of vehicle)—When the vehicle approaches and departs the facility, the curb must be on the left side of the vehicle. A U-turn is prohibited. This is typically used for vehicles such as buses that must arrive with the bus stop on the left-hand side.
  • 3 (No U-Turn)—When the vehicle approaches the facility, the curb can be on either side of the vehicle; however, the vehicle must depart without turning around.

The CurbApproach attribute is designed to work with both types of national driving standards: right-hand traffic (United States) and left-hand traffic (United Kingdom). First, consider a facility on the left side of a vehicle. It is always on the left side regardless of whether the vehicle travels on the left or right half of the road. What may change with national driving standards is your decision to approach a facility from one of two directions, that is, so it ends up on the right or left side of the vehicle. For example, if you want to arrive at a facility and not have a lane of traffic between the vehicle and the facility, choose 1 (Right side of vehicle) in the United States and 2 (Left side of vehicle) in the United Kingdom.

Bearing

The direction in which a point is moving. The units are degrees and are measured clockwise from true north. This field is used in conjunction with the BearingTol field.

Bearing data is usually sent automatically from a mobile device equipped with a GPS receiver. Try to include bearing data if you are loading an input location that is moving, such as a pedestrian or a vehicle.

Using this field tends to prevent adding locations to the wrong edges, which can occur when a vehicle is near an intersection or an overpass, for example. Bearing also helps the tool determine on which side of the street the point is.

BearingTol

The bearing tolerance value creates a range of acceptable bearing values when locating moving points on an edge using the Bearing field. If the Bearing field value is within the range of acceptable values that are generated from the bearing tolerance on an edge, the point can be added as a network location there; otherwise, the closest point on the next-nearest edge is evaluated.

The units are in degrees, and the default value is 30. Values must be greater than 0 and less than 180. A value of 30 means that when Network Analyst attempts to add a network location on an edge, a range of acceptable bearing values is generated 15 degrees to either side of the edge (left and right) and in both digitized directions of the edge.

NavLatency

This field is only used in the solve process if the Bearing and BearingTol fields also have values; however, entering a NavLatency field value is optional, even when values are present in Bearing and BearingTol. NavLatency indicates how much cost is expected to elapse from the moment GPS information is sent from a moving vehicle to a server and the moment the processed route is received by the vehicle's navigation device.

The units of NavLatency are the same as the units of the impedance attribute.

Feature Set
Measurement_Units

Specifies the units that will be used to measure and report the total travel time or travel distance for the output routes. The tool finds the closest facility by measuring the travel time or the travel distance along the streets.

The units specified for this parameter determine whether the tool will measure driving distance or driving time to find what is closest. Choose a time unit to measure driving time. To measure driving distance, choose a distance unit. Your choice also determines the units in which the tool will report total driving time or distance in the results.

  • MetersThe linear unit will be meters.
  • KilometersThe linear unit will be kilometers.
  • FeetThe linear unit will be feet.
  • YardsThe linear unit will be yards.
  • MilesThe linear unit will be miles.
  • NauticalMilesThe linear unit will be nautical miles.
  • SecondsThe time unit will be seconds.
  • MinutesThe time unit will be minutes.
  • HoursThe time unit will be hours.
  • DaysThe time unit will be days.
String
Analysis_Region
(Optional)

The region in which the analysis will be performed. If a value is not specified for this parameter, the tool will automatically calculate the region name based on the location of the input points. Setting the name of the region is required only if the automatic detection of the region name is not accurate for the inputs.

To specify a region, use one of the following values:

  • EuropeThe analysis region will be Europe.
  • JapanThe analysis region will be Japan.
  • KoreaThe analysis region will be Korea.
  • MiddleEastAndAfricaThe analysis region will be Middle East and Africa.
  • NorthAmericaThe analysis region will be North America.
  • SouthAmericaThe analysis region will be South America.
  • SouthAsiaThe analysis region will be South Asia.
  • ThailandThe analysis region will be Thailand.
Legacy:

The following region names are no longer supported and will be removed in future releases. If you specify one of the deprecated region names, the tool automatically assigns a supported region name for the region.

  • Greece redirects to Europe
  • India redirects to SouthAsia
  • Oceania redirects to SouthAsia
  • SouthEastAsia redirects to SouthAsia
  • Taiwan redirects to SouthAsia

String
Number_of_Facilities_to_Find
(Optional)

The number of closest facilities to find per incident. This is useful in situations in which multiple fire engines may be required from different fire stations, such as a fire. You can specify, for example, to find the three nearest fire stations to a fire.

The value set in this parameter can be overridden on a per-incident basis using the TargetFacilityCount field in the input incidents.

The tool can find up to 100 facilities from each incident.

Long
Cutoff
(Optional)

The travel time or travel distance value at which to stop searching for facilities for a given incident. For example, while finding the closest hospitals from the site of an accident, a cutoff value of 15 minutes means that the tool will search for the closest hospital within 15 minutes from the incident. If the closest hospital is 17 minutes away, no routes will be returned in the output routes. A cutoff value is especially useful when searching for multiple facilities.

When the Travel Direction parameter is set to Facility to Incident, the cutoff can be overridden on a per-facility basis using the Cutoff field in the input facilities. When the Travel Direction parameter is set to Incident To Facility, the cutoff can be overridden on a per-incident basis using the Cutoff field in the input incidents.

The units for this parameter are specified by the Measurement Units parameter.

Double
Travel_Direction
(Optional)

Specifies how the travel direction for the closest facility search will be measured.

  • Facility to IncidentThe direction of travel is from facilities to incidents.
  • Incident to FacilityThe direction of travel is from incidents to facilities.

Each option may find different facilities, as the travel time along some streets may vary based on the travel direction and one-way restrictions. 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 drive because of different travel time in that direction.

If you are also setting a value for the Time of Day parameter, traffic may also cause the Facility to Incident and Incident to Facility options to return different results.

Fire departments commonly use the Facility to Incident value for the parameter, since they are concerned with the time it takes to travel from the fire station (facility) to the location of the emergency (incident). Management at a retail store (facility) is more concerned with the time it takes shoppers (incidents) to reach the store (facility); therefore, store management commonly chooses Incident to Facility.

String
Use_Hierarchy
(Optional)

Specifies whether hierarchy will be used when finding the best route between the facility and the incident.

  • Checked (True in Python)—Hierarchy will be used when finding routes. When hierarchy is used, the tool identifies higher-order streets (such as freeways) before lower-order streets (such as local roads) and can be used to simulate the driver preference of traveling on freeways instead of local roads even if that means a longer trip. This is especially useful when finding routes to faraway facilities, because drivers on long-distance trips tend to prefer traveling on freeways, where stops, intersections, and turns can be avoided. Using hierarchy is computationally faster, especially for long-distance routes, as the tool identifies the best route from a relatively smaller subset of streets.
  • Unchecked (False in Python)—Hierarchy will not be used when finding routes. If hierarchy is not used, the tool considers all the streets and doesn't necessarily identify higher-order streets when finding the route. This is often used for finding short-distance routes within a city.

The tool automatically reverts to using hierarchy if the straight-line distance between facilities and incidents is greater than 50 miles, even if this parameter is Unchecked (set to False in Python).

Boolean
Time_of_Day
(Optional)

The time and date the route will begin or end. The value is used as the start time or end time for the route depending on the value for the Time of Day Usage parameter. If you specify the current date and time as the value for this parameter, the tool will use live traffic conditions to find the closest facility, and the total travel time will be based on traffic conditions.

Specifying a time of day results in a more accurate estimation of travel time between the incident and facility because the travel time accounts for the traffic conditions that are applicable for that date and time.

The Time Zone for Time of Day parameter specifies whether this time and date refer to UTC or the time zone in which the facility or incident is located.

Date
Time_of_Day_Usage
(Optional)

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

  • Start TimeThe tool considers the Time of Day parameter value as the departure time from the facility or incident to find the best route.
  • End TimeThe tool considers the Time of Day parameter value as the arrival time at the facility or incident to find the best route. This option is useful if you want to know the time to depart from a location so you arrive at the destination at the time specified in Time of Day.
String
UTurn_at_Junctions
(Optional)

Specifies the U-turn policy at junctions. Allowing U-turns implies 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 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.

  • AllowedU-turns are permitted at junctions with any number of connected edges. This is the default value.
  • Not AllowedU-turns are prohibited at all junctions, regardless of junction valency. However, U-turns are still permitted at network locations even when this option is chosen, but you can set the individual network locations' CurbApproach attribute to prohibit U-turns there as well.
  • Allowed Only at Dead EndsU-turns are prohibited at all junctions except those that have only one adjacent edge (a dead end).
  • Allowed Only at Intersections and Dead EndsU-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.

This parameter is ignored unless Travel Mode is set to Custom.

String
Point_Barriers
(Optional)

Use this parameter to specify one or more points that will act as temporary restrictions or represent additional time or distance that may be required to travel on the underlying streets. For example, a point barrier can be used to represent a fallen tree along a street or a time delay spent at a railroad crossing.

The tool imposes a limit of 250 points that can be added as barriers.

When specifying point barriers, you can set properties for each, such as its name or barrier type, using the following attributes:

Name

The name of the barrier.

BarrierType

Specifies whether the point barrier restricts travel completely or adds time or distance when it is crossed. The value for this attribute is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (Restriction)—Prohibits travel through the barrier. The barrier is referred to as a restriction point barrier since it acts as a restriction.

  • 2 (Added Cost)—Traveling through the barrier increases the travel time or distance by the amount specified in the Additional_Time, Additional_Distance, or AdditionalCost field. This barrier type is referred to as an added cost point barrier.

Additional_Time

The added travel time when the barrier is traversed. This field is applicable only for added-cost barriers and when the Measurement Units parameter value is time based.

This field value must be greater than or equal to zero, and its units must be the same as those specified in the Measurement Units parameter.

Additional_Distance

The added distance when the barrier is traversed. This field is applicable only for added-cost barriers and when the Measurement Units parameter value is distance based.

The field value must be greater than or equal to zero, and its units must be the same as those specified in the Measurement Units parameter.

AdditionalCost

The added cost when the barrier is traversed. This field is applicable only for added-cost barriers when the Measurement Units parameter value is neither time based nor distance based.

FullEdge

Specifies how the restriction point barriers are applied to the edge elements during the analysis. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (False)—Permits travel on the edge up to the barrier but not through it. This is the default value.
  • 1 (True)—Restricts travel anywhere on the associated edge.

CurbApproach

Specifies the direction of traffic that is affected by the barrier. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (Either side of vehicle)—The barrier affects travel over the edge in both directions.
  • 1 (Right side of vehicle)—Vehicles are only affected if the barrier is on their right side during the approach. Vehicles that traverse the same edge but approach the barrier on their left side are not affected by the barrier.
  • 2 (Left side of vehicle)—Vehicles are only affected if the barrier is on their left side during the approach. Vehicles that traverse the same edge but approach the barrier on their right side are not affected by the barrier.

Because junctions are points and don't have a side, barriers on junctions affect all vehicles regardless of the curb approach.

The CurbApproach attribute works with both types of national driving standards: right-hand traffic (United States) and left-hand traffic (United Kingdom). First, consider a facility on the left side of a vehicle. It is always on the left side regardless of whether the vehicle travels on the left or right half of the road. What may change with national driving standards is your decision to approach a facility from one of two directions, that is, so it ends up on the right or left side of the vehicle. For example, to arrive at a facility and not have a lane of traffic between the vehicle and the facility, choose 1 (Right side of vehicle) in the United States and 2 (Left side of vehicle) in the United Kingdom.

Bearing

The direction in which a point is moving. The units are degrees and are measured clockwise from true north. This field is used in conjunction with the BearingTol field.

Bearing data is usually sent automatically from a mobile device equipped with a GPS receiver. Try to include bearing data if you are loading an input location that is moving, such as a pedestrian or a vehicle.

Using this field tends to prevent adding locations to the wrong edges, which can occur when a vehicle is near an intersection or an overpass, for example. Bearing also helps the tool determine on which side of the street the point is.

BearingTol

The bearing tolerance value creates a range of acceptable bearing values when locating moving points on an edge using the Bearing field. If the Bearing field value is within the range of acceptable values that are generated from the bearing tolerance on an edge, the point can be added as a network location there; otherwise, the closest point on the next-nearest edge is evaluated.

The units are in degrees, and the default value is 30. Values must be greater than 0 and less than 180. A value of 30 means that when Network Analyst attempts to add a network location on an edge, a range of acceptable bearing values is generated 15 degrees to either side of the edge (left and right) and in both digitized directions of the edge.

NavLatency

This field is only used in the solve process if the Bearing and BearingTol fields also have values; however, entering a NavLatency field value is optional, even when values are present in Bearing and BearingTol. NavLatency indicates how much cost is expected to elapse from the moment GPS information is sent from a moving vehicle to a server and the moment the processed route is received by the vehicle's navigation device.

The units of NavLatency are the same as the units of the impedance attribute.

Feature Set
Line_Barriers
(Optional)

Use this parameter to specify one or more lines that prohibit travel anywhere the lines intersect the streets. For example, a parade or protest that blocks traffic across several street segments can be modeled with a line barrier. A line barrier can also quickly fence off several roads from being traversed, thereby channeling possible routes away from undesirable parts of the street network.

The tool imposes a limit on the number of streets you can restrict using the Line Barriers parameter. While there is no limit to the number of lines you can specify as line barriers, the combined number of streets intersected by all the lines cannot exceed 500.

When specifying the line barriers, you can set name and barrier type properties for each using the following attributes:

Name

The name of the barrier.

Feature Set
Polygon_Barriers
(Optional)

Use this parameter to specify polygons that either completely restrict travel or proportionately scale the time or distance required to travel on the streets intersected by the polygons.

The service imposes a limit on the number of streets you can restrict using the Polygon Barriers parameter. While there is no limit to the number of polygons you can specify as polygon barriers, the combined number of streets intersected by all the polygons cannot exceed 2,000.

When specifying the polygon barriers, you can set properties for each, such as its name or barrier type, using the following attributes:

Name

The name of the barrier.

BarrierType

Specifies whether the barrier restricts travel completely or scales the cost (such as time or distance) for traveling through it. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (Restriction)—Prohibits traveling through any part of the barrier. The barrier is referred to as a restriction polygon barrier since it prohibits traveling on streets intersected by the barrier. One use of this type of barrier is to model floods covering areas of the street that make traveling on those streets impossible.

  • 1 (Scaled Cost)—Scales the cost (such as travel time or distance) required to travel the underlying streets by a factor specified using the ScaledTimeFactor or ScaledDistanceFactor field. If the streets are partially covered by the barrier, the travel time or distance is apportioned and then scaled. For example, a factor of 0.25 means that travel on underlying streets is expected to be four times faster than normal. A factor of 3.0 means it is expected to take three times longer than normal to travel on underlying streets. This barrier type is referred to as a scaled-cost polygon barrier. It can be used to model storms that reduce travel speeds in specific regions, for example.

ScaledTimeFactor

This is the factor by which the travel time of the streets intersected by the barrier is multiplied. The field value must be greater than zero.

This field is applicable only for scaled-cost barriers and when the Measurement Units parameter is time-based.

ScaledDistanceFactor

This is the factor by which the distance of the streets intersected by the barrier is multiplied. The field value must be greater than zero.

This field is applicable only for scaled-cost barriers and when the Measurement Units parameter is distance-based.

ScaledCostFactor

This is the factor by which the cost of the streets intersected by the barrier is multiplied. The field value must be greater than zero.

This field is applicable only for scaled-cost barriers when the Measurement Units parameter is neither time-based nor distance-based.

Feature Set
Restrictions
[Restrictions,...]
(Optional)

The restrictions that will be honored by the tool when finding the best routes.

A restriction represents a driving preference or requirement. In most cases, restrictions cause roads to be prohibited. For instance, using the Avoid Toll Roads restriction will result in a route that will include toll roads only when it is required to travel on toll roads to visit an incident or a facility. Height Restriction makes it possible to route around any clearances that are lower than the height of the vehicle. If you are carrying corrosive materials on the vehicle, using the Any Hazmat Prohibited restriction prevents hauling the materials along roads where it is marked illegal to do so.

Note:

The values you provide for this parameter are ignored unless Travel Mode is set to Custom.

Note:

Some restrictions require an additional value to be specified for their use. This value must be associated with the restriction name and a specific parameter intended to work with the restriction. You can identify such restrictions if their names appear in the AttributeName column of the Attribute Parameter Values parameter. Specify the ParameterValue field for the Attribute Parameter Values parameter for the restriction to be correctly used when finding traversable roads.

Note:

Some restrictions are supported only in certain countries; their availability is stated by region in the list below. Of the restrictions that have limited availability within a region, you can determine whether the restriction is available in a particular country by reviewing the table in the Country list section of Network analysis coverage. If a country has a value of Yes in the Logistics Attribute column, the restriction with select availability in the region is supported in that country. If you specify restriction names that are not available in the country where your incidents are located, the service ignores the invalid restrictions. The service also ignores restrictions when the Restriction Usage attribute parameter value is between 0 and 1 (see the Attribute Parameter Value parameter). It prohibits all restrictions when the Restriction Usage parameter value is greater than 0.

The tool supports the following restrictions:

  • Any Hazmat ProhibitedThe results will not include roads where transporting any kind of hazardous material is prohibited. Availability: Select countries in North America and Europe
  • Avoid Carpool RoadsThe results will avoid roads that are designated exclusively for car pool (high-occupancy) vehicles. Availability: All countries
  • Avoid Express LanesThe results will avoid roads designated as express lanes. Availability: All countries
  • Avoid FerriesThe results will avoid ferries. Availability: All countries
  • Avoid GatesThe results will avoid roads where there are gates, such as keyed access or guard-controlled entryways.Availability: All countries
  • Avoid Limited Access RoadsThe results will avoid roads that are limited-access highways.Availability: All countries
  • Avoid Private RoadsThe results will avoid roads that are not publicly owned and maintained.Availability: All countries
  • Avoid Roads Unsuitable for PedestriansThe results will avoid roads that are unsuitable for pedestrians.Availability: All countries
  • Avoid StairwaysThe results will avoid all stairways on a pedestrian-suitable route.Availability: All countries
  • Avoid Toll RoadsThe results will avoid all toll roads for automobiles.Availability: All countries
  • Avoid Toll Roads for TrucksThe results will avoid all toll roads for trucks.Availability: All countries
  • Avoid Truck Restricted RoadsThe results will avoid roads where trucks are not allowed, except when making deliveries.Availability: All countries
  • Avoid Unpaved RoadsThe results will avoid roads that are not paved (for example, dirt, gravel, and so on). Availability: All countries
  • Axle Count RestrictionThe results will not include roads where trucks with the specified number of axles are prohibited. The number of axles can be specified using the Number of Axles restriction parameter.Availability: Select countries in North America and Europe
  • Driving a BusThe results will not include roads where buses are prohibited. Using this restriction will also ensure that the results will honor one-way streets. Availability: All countries
  • Driving a TaxiThe results will not include roads where taxis are prohibited. Using this restriction will also ensure that the results will honor one-way streets. Availability: All countries
  • Driving a TruckThe results will not include roads where trucks are prohibited. Using this restriction will also ensure that the results will honor one-way streets. Availability: All countries
  • Driving an AutomobileThe results will not include roads where automobiles are prohibited. Using this restriction will also ensure that the results will honor one-way streets. Availability: All countries
  • Driving an Emergency VehicleThe results will not include roads where emergency vehicles are prohibited. Using this restriction will also ensure that the results will honor one-way streets.Availability: All countries
  • Height RestrictionThe results will not include roads where the vehicle height exceeds the maximum allowed height for the road. The vehicle height can be specified using the Vehicle Height (meters) restriction parameter. Availability: Select countries in North America and Europe
  • Kingpin to Rear Axle Length RestrictionThe results will not include roads where the vehicle length exceeds the maximum allowed kingpin to rear axle for all trucks on the road. The length between the vehicle kingpin and the rear axle can be specified using the Vehicle Kingpin to Rear Axle Length (meters) restriction parameter. Availability: Select countries in North America and Europe
  • Length RestrictionThe results will not include roads where the vehicle length exceeds the maximum allowed length for the road. The vehicle length can be specified using the Vehicle Length (meters) restriction parameter. Availability: Select countries in North America and Europe
  • Preferred for PedestriansThe results will use preferred routes suitable for pedestrian navigation. Availability: Select countries in North America and Europe
  • Riding a MotorcycleThe results will not include roads where motorcycles are prohibited. Using this restriction will also ensure that the results will honor one-way streets.Availability: All countries
  • Roads Under Construction ProhibitedThe results will not include roads that are under construction.Availability: All countries
  • Semi or Tractor with One or More Trailers ProhibitedThe results will not include roads where semis or tractors with one or more trailers are prohibited. Availability: Select countries in North America and Europe
  • Single Axle Vehicles ProhibitedThe results will not include roads where vehicles with single axles are prohibited.Availability: Select countries in North America and Europe
  • Tandem Axle Vehicles ProhibitedThe results will not include roads where vehicles with tandem axles are prohibited.Availability: Select countries in North America and Europe
  • Through Traffic ProhibitedThe results will not include roads where through traffic (nonlocal) is prohibited.Availability: All countries
  • Truck with Trailers RestrictionThe results will not include roads where trucks with the specified number of trailers on the truck are prohibited. The number of trailers on the truck can be specified using the Number of Trailers on Truck restriction parameter.Availability: Select countries in North America and Europe
  • Use Preferred Hazmat RoutesThe results will prefer roads that are designated for transporting any kind of hazardous materials. Availability: Select countries in North America and Europe
  • Use Preferred Truck RoutesThe results will prefer roads that are designated as truck routes, such as the roads that are part of the national network as specified by the National Surface Transportation Assistance Act in the United States, or roads that are designated as truck routes by the state or province, or roads that are preferred by truckers when driving in an area.Availability: Select countries in North America and Europe
  • WalkingThe results will not include roads where pedestrians are prohibited.Availability: All countries
  • Weight RestrictionThe results will not include roads where the vehicle weight exceeds the maximum allowed weight for the road. The vehicle weight can be specified using the Vehicle Weight (kilograms) restriction parameter.Availability: Select countries in North America and Europe
  • Weight per Axle RestrictionThe results will not include roads where the vehicle weight per axle exceeds the maximum allowed weight per axle for the road. The vehicle weight per axle can be specified using the Vehicle Weight per Axle (kilograms) restriction parameter.Availability: Select countries in North America and Europe
  • Width RestrictionThe results will not include roads where the vehicle width exceeds the maximum allowed width for the road. The vehicle width can be specified using the Vehicle Width (meters) restriction parameter.Availability: Select countries in North America and Europe
String
Attribute_Parameter_Values
(Optional)

Use this parameter to specify additional values required by an attribute or restriction, such as to specify whether the restriction prohibits, avoids, or prefers travel on restricted roads. If the restriction is meant to avoid or prefer roads, you can further specify the degree to which they are avoided or preferred using this parameter. For example, you can choose to never use toll roads, avoid them as much as possible, or prefer them.

Note:

The values you provide for this parameter are ignored unless Travel Mode is set to Custom.

If you specify the Attribute Parameter Values parameter from a feature class, the field names on the feature class must match the fields as follows:

  • AttributeName—The name of the restriction.
  • ParameterName—The name of the parameter associated with the restriction. A restriction can have one or more ParameterName field values based on its intended use.
  • ParameterValue—The value for ParameterName used by the tool when evaluating the restriction.

The Attribute Parameter Values parameter is dependent on the Restrictions parameter. The ParameterValue field is applicable only if the restriction name is specified as the value for the Restrictions parameter.

In Attribute Parameter Values, each restriction (listed as AttributeName) has a ParameterName field value, Restriction Usage, that specifies whether the restriction prohibits, avoids, or prefers travel on the roads associated with the restriction as well as the degree to which the roads are avoided or preferred. The Restriction Usage ParameterName can be assigned any of the following string values or their equivalent numeric values listed in the parentheses:

  • PROHIBITED (-1)—Travel on the roads using the restriction is completely prohibited.
  • AVOID_HIGH (5)—It is highly unlikely the tool will include in the route the roads that are associated with the restriction.
  • AVOID_MEDIUM (2)—It is unlikely the tool will include in the route the roads that are associated with the restriction.
  • AVOID_LOW (1.3)—It is somewhat unlikely the tool will include in the route the roads that are associated with the restriction.
  • PREFER_LOW (0.8)—It is somewhat likely the tool will include in the route the roads that are associated with the restriction.
  • PREFER_MEDIUM (0.5)—It is likely the tool will include in the route the roads that are associated with the restriction.
  • PREFER_HIGH (0.2)—It is highly likely the tool will include in the route the roads that are associated with the restriction.

In most cases, you can use the default value, PROHIBITED, as the Restriction Usage value if the restriction is dependent on a vehicle characteristic such as vehicle height. However, in some cases, the Restriction Usage value depends on your routing preferences. For example, the Avoid Toll Roads restriction has the default value of AVOID_MEDIUM for the Restriction Usage attribute. This means that when the restriction is used, the tool will route around toll roads when it can. AVOID_MEDIUM also indicates how important it is to avoid toll roads when finding the best route; it has a medium priority. Choosing AVOID_LOW puts lower importance on avoiding tolls; choosing AVOID_HIGH instead gives it a higher importance and makes it more acceptable for the service to generate longer routes to avoid tolls. Choosing PROHIBITED entirely disallows travel on toll roads, making it impossible for a route to travel on any portion of a toll road. Keep in mind that avoiding or prohibiting toll roads, and avoiding toll payments, is the objective for some. In contrast, others prefer to drive on toll roads, because avoiding traffic is more valuable to them than the money spent on tolls. In the latter case, choose PREFER_LOW, PREFER_MEDIUM, or PREFER_HIGH as the value for Restriction Usage. The higher the preference, the farther the tool will go to travel on the roads associated with the restriction.

Record Set
Route_Shape
(Optional)

Specifies the type of route features that will be output by the tool.

  • True ShapeThe exact shape of the resulting route that is based on the underlying streets will be returned.
  • True Shape with MeasuresThe exact shape of the resulting route that is based on the underlying streets will be returned. Additionally, construct measures so the shape can be used in linear referencing. The measurements increase from the first stop and record the cumulative travel time or travel distance in the units specified by the Measurement Units parameter.
  • Straight LineA straight line between two stops will be returned.
  • NoneNo shapes for the routes will be returned. This value can be useful, and return results quickly, when you are only interested in determining the total travel time or travel distance of a route.

When the Route Shape parameter is set to True Shape or True Shape with Measures, the generalization of the route shape can be further controlled using the appropriate value for the Route Line Simplification Tolerance parameter.

No matter which value you choose for the Route Shape parameter, the best route is always determined by minimizing the travel time or the travel distance, never using the straight-line distance between stops. This means that only the route shapes are different, not the underlying streets that are searched when finding the route.

String
Route_Line_Simplification_Tolerance
(Optional)

The distance that will be used to simplify the geometry of the output lines for routes and directions.

The tool ignores this parameter if the Route Shape parameter isn't set to True Shape.

Simplification maintains critical points on a route, such as turns at intersections, to define the essential shape of the route and removes other points. The simplification distance you specify is the maximum allowable offset that the simplified line can deviate from the original line. Simplifying a line reduces the number of vertices that are part of the route geometry. This improves the tool processing time.

Linear Unit
Populate_Directions
(Optional)

Specifies whether the tool will generate driving directions for each route.

  • Checked (True in Python)—Directions will be generated and configured based on the values of the Directions Language, Directions Style Name, and Directions Distance Units parameters.
  • Unchecked (False in Python)—Directions will not be generated, and the tool will return an empty Directions layer.

Boolean
Directions_Language
(Optional)

The language that will be used when generating travel directions.

This parameter is used only when the Populate Directions parameter is checked (True in Python).

The parameter value can be specified using one of the following two- or five-character language codes:

  • ar—Arabic
  • bg—Bulgarian
  • bs—Bosnian
  • ca—Catalan
  • cs—Czech
  • da—Danish
  • de—German
  • el—Greek
  • en—English
  • es—Spanish
  • et—Estonian
  • fi—Finnish
  • fr—French
  • he—Hebrew
  • hr—Croatian
  • hu—Hungarian
  • id—Indonesian
  • it—Italian
  • ja—Japanese
  • ko—Korean
  • lt—Lithuanian
  • lv—Latvian
  • nb—Norwegian
  • nl—Dutch
  • pl—Polish
  • pt-BR—Portuguese (Brazil)
  • pt-PT—Portuguese (Portugal)
  • ro—Romanian
  • ru—Russian
  • sk—Slovak
  • sl—Slovenian
  • sr—Serbian
  • sv—Swedish
  • th—Thai
  • tr—Turkish
  • uk—Ukrainian
  • vi—Vietnamese
  • zh-CN—Chinese (China)
  • zh-HK—Chinese (Hong Kong)
  • zh-TW—Chinese (Taiwan)

The tool first searches for an exact match for the specified language including any language localization. If an exact match is not found, it tries to match the language family. If a match is still not found, the tool returns the directions using the default language, English. For example, if the directions language is specified as es-MX (Mexican Spanish), the tool will return the directions in Spanish, as it supports the es language code but not es-MX.

Caution:

If a language supports localization, such as Brazilian Portuguese (pt-BR) and European Portuguese (pt-PT), specify the language family and the localization. If you only specify the language family, the tool will not match the language family and instead return directions in the default language, English. For example, if the directions language specified is pt, the tool will return the directions in English since it cannot determine whether the directions should be returned in pt-BR or pt-PT.

String
Directions_Distance_Units
(Optional)

Specifies the units that will display travel distance in the driving directions. This parameter is used only when the Populate Directions parameter is checked (True in Python).

  • MilesThe linear unit will be miles.
  • KilometersThe linear unit will be kilometers.
  • MetersThe linear unit will be meters.
  • FeetThe linear unit will be feet.
  • YardsThe linear unit will be yards.
  • NauticalMilesThe linear unit will be nautical miles.
String
Directions_Style_Name
(Optional)

Specifies the name of the formatting style for the directions. This parameter is used only when the Populate Directions parameter is checked (True in Python).

  • NA DesktopThe style will be turn-by-turn directions suitable for printing.
  • NA NavigationThe style will be turn-by-turn directions designed for an in-vehicle navigation device.
String
Time_Zone_for_Time_of_Day
(Optional)

Specifies the time zone of the Time of Day parameter.

  • Geographically LocalThe Time of Day parameter refers to the time zone in which the facilities or incidents are located.If Time of Day Usage is set to Start Time and Travel Direction is Facility to Incident, this is the time zone of the facilities. If Time of Day Usage is set to Start Time and Travel Direction is Incident to Facility, this is the time zone of the incidents. If Time of Day Usage is set to End Time and Travel Direction is Facility to Incident, this is the time zone of the incidents. If Time of Day Usage is set to End Time and Travel Direction is Incident to Facility, this is the time zone of the facilities.
  • UTCThe Time of Day parameter refers to coordinated universal time (UTC). Choose this option if you want to find what's nearest for a specific time, such as now, but aren't certain in which time zone the facilities or incidents will be located.

Regardless of the Time Zone for Time of Day setting, if your facilities and incidents are in multiple time zones, the following rules are enforced by the tool. All incidents and facilities must be in the same time zone for the following:

  • Specifying a start time and traveling from incident to facility
  • Specifying an end time and traveling from facility to incident
  • Specifying a start time and traveling from facility to incident
  • Specifying an end time and traveling from incident to facility

String
Travel_Mode
(Optional)

The mode of transportation to model in the analysis. Travel modes are managed in ArcGIS Online and can be configured by the administrator of your organization to reflect the organization's workflows. Specify the name of a travel mode that is supported by your organization.

To get a list of supported travel mode names, run the Get Travel Modes tool from the Utilities toolbox under the same GIS Server connection you used to access the tool. The Get Travel Modes tool adds a table, Supported Travel Modes, to the application. Any value in the Travel Mode Name field from the Supported Travel Modes table can be specified as input. You can also specify the value from the Travel Mode Settings field as input. This speeds up tool execution, as the tool does not have to find the settings based on the travel mode name.

The default value, Custom, allows you to configure a custom travel mode using the custom travel mode parameters (UTurn at Junctions, Use Hierarchy, Restrictions, Attribute Parameter Values, and Impedance). The default values of the custom travel mode parameters model traveling by car. You can also choose Custom and set the custom travel mode parameters listed above to model a pedestrian with a fast walking speed or a truck with a given height, weight, and cargo of certain hazardous materials. You can try different settings to get the analysis results you want. Once you have identified the analysis settings, work with your organization's administrator and save these settings as part of a new or existing travel mode so that everyone in your organization can run the analysis with the same settings.

Caution:

When you choose Custom, the values you set for the custom travel mode parameters are included in the analysis. Specifying another travel mode, as defined by your organization, causes any values you set for the custom travel mode parameters to be ignored; the tool overrides them with values from the specified travel mode.

String
Impedance
(Optional)

Specifies the impedance, which is a value that represents the effort or cost of traveling along road segments or on other parts of the transportation network.

Travel time is an impedance: a car may take 1 minute to travel a mile along an empty road. Travel times can vary by travel mode—a pedestrian may take more than 20 minutes to walk the same mile, so it is important to choose the right impedance for the travel mode you are modeling.

Travel distance can also be an impedance; the length of a road in kilometers can be thought of as impedance. Travel distance in this sense is the same for all modes—a kilometer for a pedestrian is also a kilometer for a car. (What may change is the pathways on which the different modes are allowed to travel, which affects distance between points, and this is modeled by travel mode settings.)

Caution:

The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value.

  • TravelTimeHistorical and live traffic data is used. This option is good for modeling the time it takes automobiles to travel along roads at a specific time of day using live traffic speed data where available. When using TravelTime, you can optionally set the TravelTime::Vehicle Maximum Speed (km/h) attribute parameter to specify the physical limitation of the speed the vehicle is capable of traveling.
  • MinutesLive traffic data is not used, but historical average speeds for automobiles data is used.
  • TruckTravelTimeHistorical and live traffic data is used, but the speed is capped at the posted truck speed limit. This is good for modeling the time it takes for the trucks to travel along roads at a specific time. When using TruckTravelTime, you can optionally set the TruckTravelTime::Vehicle Maximum Speed (km/h) attribute parameter to specify the physical limitation of the speed the truck is capable of traveling.
  • TruckMinutesLive traffic data is not used, but the smaller of the historical average speeds for automobiles and the posted speed limits for trucks is used.
  • WalkTimeThe default is a speed of 5 km/hr on all roads and paths, but this can be configured through the WalkTime::Walking Speed (km/h) attribute parameter.
  • MilesLength measurements along roads are stored in miles and can be used for performing analysis based on shortest distance.
  • KilometersLength measurements along roads are stored in kilometers and can be used for performing analysis based on shortest distance.
  • TimeAt1KPHThe default is a speed of 1 km/hr on all roads and paths. The speed cannot be changed using any attribute parameter.
  • Drive TimeTravel times for a car are modeled. These travel times are dynamic and fluctuate according to traffic flows in areas where traffic data is available. This is the default value.
  • Truck TimeTravel times for a truck are modeled. These travel times are static for each road and don't fluctuate with traffic.
  • Walk TimeTravel times for a pedestrian are modeled.
  • Travel DistanceLength measurements along roads and paths are stored. To model walk distance, choose this option and ensure that Walking is set for the Restriction parameter. Similarly, to model drive or truck distance, choose Travel Distance here and set the appropriate restrictions so the vehicle travels only on roads where it is permitted to do so.

If you choose a time-based impedance, such as TravelTime, TruckTravelTime, Minutes, TruckMinutes, or WalkTime, the Break Units parameter must be set to a time-based value; if you choose a distance-based impedance such as Miles or Kilometers, Break Units must be a distance-based value.

Legacy:

Drive Time, Truck Time, Walk Time, and Travel Distance impedance values are no longer supported and will be removed in a future release. If you use one of these values, the tool uses the value of the Time Impedance parameter for time-based values and the Distance Impedance parameter for distance-based values.

String
Save_Output_Network_Analysis_Layer
(Optional)

Specifies whether the analysis settings will be saved as a network analysis layer file. You cannot directly work with this file even when you open the file in an ArcGIS Desktop application such as ArcMap. It is meant to be sent to Esri Technical Support to diagnose the quality of results returned from the tool.

  • Checked (True in Python)—The output will be saved as a network analysis layer file. The file will be downloaded to a temporary directory on your machine. In ArcGIS Pro, the location of the downloaded file can be determined by viewing the value for the Output Network Analysis Layer parameter in the entry corresponding to the tool service in the geoprocessing history of the project. In ArcMap, the location of the file can be determined by accessing the Copy Location option in the shortcut menu of the Output Network Analysis Layer parameter in the entry corresponding to the tool service in the Geoprocessing Results window.
  • Unchecked (False in Python)—The output will not be saved as a network analysis layer file. This is the default.

Boolean
Overrides
(Optional)

Note:

This parameter is for internal use only.

String
Save_Route_Data
(Optional)

Specifies whether the output will include a .zip file that contains a file geodatabase with the inputs and outputs of the analysis in a format that can be used to share route layers with ArcGIS Online or Portal for ArcGIS.

  • Checked (True in Python)—The route data will be saved as a .zip file. The file is downloaded to a temporary directory on your machine. In ArcGIS Pro, the location of the downloaded file can be determined by viewing the value for the Output Route Data parameter in the entry corresponding to the tool operation in the geoprocessing history of the project. In ArcMap, the location of the file can be determined by accessing the Copy Location option in the shortcut menu of the Output Route Data parameter in the entry corresponding to the tool operation in the Geoprocessing Results window.
  • Unchecked (False in Python)—The route data will not be saved as a .zip file. This is the default.

Boolean
Time_Impedance
(Optional)

The time-based impedance value represents the travel time along road segments or on other parts of the transportation network.

Note:
If the impedance for the travel mode, as specified using the Impedance parameter, is time based, the values for the Time Impedance and Impedance parameters must be identical. Otherwise, the service will return an error.
  • MinutesTime impedance will be minutes.
  • TravelTimeTime impedance will be travel time.
  • TimeAt1KPHTime impedance will be time at one kilometer per hour.
  • WalkTimeTime impedance will be walk time.
  • TruckMinutesTime impedance will be truck minutes.
  • TruckTravelTimeTime impedance will be truck travel time.
String
Distance_Impedance
(Optional)

The distance-based impedance value represents the travel distance along road segments or on other parts of the transportation network.

Note:
If the impedance for the travel mode, as specified using the Impedance parameter, is distance based, the values for the Distance Impedance and Impedance parameters must be identical. Otherwise, the service will return an error.
  • MilesDistance impedance will be miles.
  • KilometersDistance impedance will be kilometers.
String
Output_Format
(Optional)

Specifies the format in which the output features will be returned.

  • Feature SetThe output features will be returned as feature classes and tables. This is the default.
  • JSON FileThe output features will be returned as a compressed file containing the JSON representation of the outputs. When this option is specified, the output is a single file (with a .zip extension) that contains one or more JSON files (with a .json extension) for each of the outputs created by the service.
  • GeoJSON FileThe output features will be returned as a compressed file containing the GeoJSON representation of the outputs. When this option is specified, the output is a single file (with a .zip extension) that contains one or more GeoJSON files (with a .geojson extension) for each of the outputs created by the service.

When a file-based output format, such as JSON File or GeoJSON File, is specified, no outputs will be added to the display because the application, such as ArcMap or ArcGIS Pro, cannot draw the contents of the result file. Instead, the result file is downloaded to a temporary directory on your machine. In ArcGIS Pro, the location of the downloaded file can be determined by viewing the value for the Output Result File parameter in the entry corresponding to the tool operation in the geoprocessing history of the project. In ArcMap, the location of the file can be determined by accessing the Copy Location option in the shortcut menu of the Output Result File parameter in the entry corresponding to the tool operation in the Geoprocessing Results window.

String
Ignore_Invalid_Locations
(Optional)

Specifies whether invalid input locations will be ignored.

  • SKIPNetwork locations that are unlocated will be ignored and the analysis will run using valid network locations only. The analysis will also continue if locations are on nontraversable elements or have other errors. This is useful if you know the network locations are not all correct, but you want to run the analysis with the network locations that are valid. This is the default.
  • HALTInvalid locations will not be ignored. Do not run the analysis if there are invalid locations. Correct the invalid locations and rerun the analysis.
Boolean
Locate_Settings
(Optional)

Use this parameter to specify settings that affect how inputs are located, such as the maximum search distance to use when locating the inputs on the network, or the network sources being used for locating.

Learn more about locating inputs

The parameter value is specified as a JSON object. The JSON object allows you to specify a locator JSON for all input feature in the analysis, or optionally you could specify an override for a particular input. The override allows you to have different settings for each analysis input.

The locator JSON object has following properties:

  • tolerance and toleranceUnits—Allows you to control the maximum search distance when locating inputs. If no valid network location is found within this distance, the input features will be considered unlocated. A small search tolerance decreases the likelihood of locating on the wrong street but increases the likelihood of not finding any valid network location. The toleranceUnits parameter value should be specified as one of the following values:
    • esriCentimeters
    • esriDecimalDegrees
    • esriDecimeters
    • esriFeet
    • esriInches
    • esriIntFeet
    • esriIntInches
    • esriIntMiles
    • esriIntNauticalMiles
    • esriIntYards
    • esriKilometers
    • esriMeters
    • esriMiles
    • esriMillimeters
    • esriNauticalMiles
    • esriYards
  • sources— Allows you to control which network source can be used for locating. For example, you can configure the analysis to locate inputs on streets but not on sidewalks. The list of possible sources on which to locate is specific to the network dataset this service references. Only the sources that are present in the sources array are used for locating. Sources is specified as an array of objects each having the following property:
    • name—Name of the network source feature class that can be used for locating inputs.
  • allowAutoRelocate—Allows you to control whether inputs with existing network location fields can be automatically relocated when solving to ensure valid, routable location fields for the analysis. If the value is true, points located on restricted network elements and points affected by barriers will be relocated to the closest routable location. If the value is false, network location fields will be used as is even if the points are unreachable, and this may cause the solve to fail. Even if the value is false, inputs with no location fields or incomplete location fields will be located during solve.
Note:
At this point, the sources array doesn't allow to specify different source names. Also, allowAutoRelocate is always set to true since the service does not support location fields.

Locate_Settings JSON object allows you to specify a default locator JSON object for all input features in the analysis, as well as overrides for each input class. When specifying Locate_Settings JSON, you need to provide the following properties: tolerance, toleranceUnits, and allowAutoRelocate. If you need to provide a different locator JSON for a particular input class, you need to include overrides property for that input. The property name must match the input parameter name. The locator JSON for a particular input doesn't need to include all the properties; you only need to include the properties that are different from the default locator JSON properties.

String

Derived Output

NameExplanationData Type
Output_Routes

This provides access to the resulting route or routes between the facilities and the incidents.

Feature Set
Output_Directions

This provides access to the turn-by-turn directions for each resulting route.

Feature Set
Solve_Succeeded

Indicates whether solving the closest facility analysis succeeded.

Boolean
Output_Closest_Facilities

This provides access to the output facilities from a closest facility analysis.

Feature Set
Output_Network_Analysis_Layer

The network analysis layer, with properties configured in the tool parameters, that can be used for further analysis or debugging in the map.

File
Output_Route_Data

A .zip file containing all the information for a particular route.

File
Output_Incidents

This provides access to the locations used as starting or ending points in a closest facility analysis.

Feature Set
Output_Facilities

The facilities used in the analysis.

Feature Set
Output_Result_File

A .zip file containing the results of the analysis with one or more files for each output. The format of the individual files is specified by the Output Format parameter.

File
Output_Network_Analysis_Layer_Package

A layer package that includes a network analysis layer with the data and settings used in the analysis.

File
Output_Direction_Points

This parameter provides access to turn-by-turn directions for the routes calculated in the analysis, represented as point locations along the routes where specific directions events or maneuvers occur.

Feature Set
Output_Direction_Lines

This parameter provides access to the route lines calculated in the analysis, sliced to represent each route segment between DirectionPoints events or maneuver locations.

Feature Set
Usage_Cost

This parameter returns the credits used by the analysis.

Note:

Each analysis can generate a different number of billable objects and thus will use different number of credits. If the service fails to determine credits, the usage_cost parameter returns a value of -1 for credits.

JSON

Code sample

FindClosestFacilities example (stand-alone script)

The following Python script demonstrates how to use the Find Closest Facilities tool in a script.

"""This example shows how to find three closest stores from each customer location."""

import sys
import time
import arcpy

# Change the username and password applicable to your own ArcGIS Online account
username = "<your user name>"
password = "<your password>"
cf_service = "https://logistics.arcgis.com/arcgis/services;World/ClosestFacility;{0};{1}".format(username, password)

# Add the geoprocessing service as a toolbox.
# Check https://pro.arcgis.com/en/pro-app/arcpy/functions/importtoolbox.htm for
# other ways in which you can specify credentials to connect to a geoprocessing service.
arcpy.ImportToolbox(cf_service)

# Set the variables to call the tool
facilities = "C:/data/Inputs.gdb/Stores"
incidents = "C:/data/Inputs.gdb/Customers"
output_routes = "C:/data/Results.gdb/Routes"
output_closest_facilities = "C:/data/Results.gdb/ClosestStores"

# Call the tool
result = arcpy.ClosestFacility.FindClosestFacilities(incidents, facilities, "Minutes", "", 3)
arcpy.AddMessage("Running the analysis with result ID: {}".format(result.resultID))

# Check the status of the result object every 1 second until it has a
# value of 4 (succeeded) or greater
while result.status < 4:
    time.sleep(1)

# print any warning or error messages returned from the tool
result_severity = result.maxSeverity
if result_severity == 2:
    arcpy.AddError("An error occured when running the tool")
    arcpy.AddError(result.getMessages(2))
    sys.exit(2)
elif result_severity == 1:
    arcpy.AddWarning("Warnings were returned when running the tool")
    arcpy.AddWarning(result.getMessages(1))

# Save the output routes and the closest facilities to a geodatabase
result.getOutput(0).save(output_routes)
result.getOutput(3).save(output_closest_facilities)
FindClosestFacilities example 2 (stand-alone script)

The following example shows how to perform a closest facility analysis using a custom travel mode.

"""This example shows how to perform a closest facility analysis using a custom travel mode
that models trucks carrying wide load."""

import sys
import time
import json
import arcpy

username = "<your user name>"
password = "<your password>"
cf_service = "https://logistics.arcgis.com/arcgis/services;World/ClosestFacility;{0};{1}".format(username, password)

# Add the geoprocessing service as a toolbox
arcpy.ImportToolbox(cf_service)

# Set the variables to call the tool
facilities = "C:/data/Inputs.gdb/Stores"
incidents = "C:/data/Inputs.gdb/Customers"
output_routes = "C:/data/Results.gdb/Routes"
output_closest_facilities = "C:/data/Results.gdb/ClosestStores"

# Change Vehicle Width attribute parameter value to 4.5 (about 15 feet) for the Trucking Time travel mode
# used for the analysis
portal_url = "https://www.arcgis.com"
arcpy.SignInToPortal(portal_url, username, password)
travel_mode_list = arcpy.na.GetTravelModes(portal_url)
tt = travel_mode_list["Trucking Time"]
tt_json = str(tt)
tt_dict = json.loads(tt_json)
tt_dict["restrictionAttributeNames"].append("Width Restriction")

for attr_param in tt_dict["attributeParameterValues"]:
    if attr_param['attributeName'] == 'Width Restriction' and attr_param['parameterName'] == 'Vehicle Width (meters)':
        attr_param['value'] = 4.5
travel_mode = json.dumps(tt_dict)

# Call the tool
result = arcpy.ClosestFacility.FindClosestFacilities(incidents, facilities, "Minutes", "", 2,
                                                     Travel_Mode=travel_mode)

# Check the status of the result object every 1 second until it has a
# value of 4 (succeeded) or greater
while result.status < 4:
    time.sleep(1)

# print any warning or error messages returned from the tool
result_severity = result.maxSeverity
if result_severity == 2:
    arcpy.AddError("An error occured when running the tool")
    arcpy.AddError(result.getMessages(2))
    sys.exit(2)
elif result_severity == 1:
    arcpy.AddWarning("Warnings were returned when running the tool")
    arcpy.AddWarning(result.getMessages(1))

# Save the output routes and the closest facilities to a geodatabase
result.getOutput(0).save(output_routes)
result.getOutput(3).save(output_closest_facilities)

Environments

This tool does not use any geoprocessing environments.