Summary
Find Routes determines the shortest paths to visit the input stops and returns the driving directions, information about the visited stops, and the route paths, including travel time and distance.
The tool is capable of finding routes that visit several input stops in a sequence you predetermine or in the sequence that minimizes overall travel. You can group the input stops into different routes using the RouteName field, and the tool will output one route for each group of stops, allowing you to generate routes for many vehicles in a single solve operation.
Note:
When using Find Routes to route multiple vehicles, you need to assign stops to routes before solving. If you need a tool that determines the best way to divide stops among different vehicles, and then route the vehicles, use the Solve Vehicle Routing Problem tool instead.
Caution:
For up-to-date information about this tool, see the most recent edition of this topic in the web help. ArcGIS Online makes regular functional updates to services such as this, so the installed help may become outdated.
Illustration
Usage
Tools in the Ready To Use toolbox areArcGIS Online geoprocessing services that use ArcGIS Online's hosted data and analysis capabilities.
The tool finds the shortest routes based on travel time if the value for the Measurement Units parameter is time based and on travel distance if the value is distance based.
You need to specify at least two stops to successfully execute the tool. You can load up to 10,000 stops and assign a maximum of 150 stops per route.
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 cannot intersect more than 2,000 features.
You can choose to use the road hierarchy when solving so that results are generated quicker than exact routes, but the solution may be somewhat less than optimal.
Regardless of whether the Use Hierarchy parameter is checked (True), hierarchy is always used when the straight-line distance between any pair of stops is greater than 50 miles (80.46 kilometers).
The straight-line distance between any pair of stops 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.
Syntax
arcpy.agolservices.FindRoutes(Stops, Measurement_Units, {Analysis_Region}, {Reorder_Stops_to_Find_Optimal_Routes}, {Preserve_Terminal_Stops}, {Return_to_Start}, {Use_Time_Windows}, {Time_of_Day}, {Time_Zone_for_Time_of_Day}, {UTurn_at_Junctions}, {Point_Barriers}, {Line_Barriers}, {Polygon_Barriers}, {Use_Hierarchy}, {Restrictions}, {Attribute_Parameter_Values}, {Route_Shape}, {Route_Line_Simplification_Tolerance}, {Populate_Route_Edges}, {Populate_Directions}, {Directions_Language}, {Directions_Distance_Units}, {Directions_Style_Name}, {Travel_Mode}, {Impedance}, {Time_Zone_for_Time_Windows}, {Save_Output_Network_Analysis_Layer}, {Overrides}, {Save_Route_Data}, {Time_Impedance}, {Distance_Impedance}, {Output_Format})| Parameter | Explanation | Data Type |
Stops |
Specifies the locations the output route or routes will visit. You can add up to 10,000 stops and assign up to 150 stops to a single route. (Assign stops to routes using the RouteName attribute.) When specifying the stops, you can set properties for each—such as its name or service time— using the following attributes: Name The name of the stop. 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 stops, routes, and directions. RouteName The name of the route to which the stop is assigned. Assigning the same route name to different stops causes those stops to be grouped together and visited by the same route. You can generate many routes in a single solve by assigning unique route names to different groups of stops. You can group up to 150 stops into one route. Sequence The output routes will visit the stops in the order you specify with this attribute. In a group of stops that have the same RouteName value, the sequence number should be greater than 0 but not greater than the total number of stops. Also, the sequence number should not be duplicated. If Reorder Stops To Find Optimal Routes is checked (True), all but possibly the first and last sequence values for each route name are ignored so the tool can find the sequence that minimizes overall travel for each route. (The settings for Preserve Ordering of Stops and Return to Start determine whether the first or last sequence values for each route are ignored.) AdditionalTime The amount of time spent at the stop, 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. You can account for the extra time it takes at the stop to complete a task, such as to repair an appliance, deliver a package, or inspect the premises. AdditionalDistance The extra distance traveled at the stops, 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 stop, 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 actual stop 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 stop, 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. TimeWindowStart The earliest time the stop can be visited. By specifying a start and end time for a stop's time window, you are defining when a route should visit the stop. When the travel mode for the analysis uses an impedance attribute that is time based, by specifying time-window values the analysis will find a solution that minimizes overall travel and reaches the stop within the prescribed time window. Make sure you specify the value as a date and time value, such as 8/12/2015 12:15 PM. When solving a problem that spans multiple time zones, time-window values refer to the time zone in which the stop is located. This field can contain a null value; a null value indicates that a route can arrive at any time before the time indicated in the TimeWindowEnd attribute. If a null value is also present in TimeWindowEnd, a route can visit the stop at any time. TimeWindowEnd The latest time the stop can be visited. By specifying a start and end time for a stop's time window, you are defining when a route will visit the stop. When the travel mode for the analysis uses an impedance attribute that is time based, specifying time-window values will cause the analysis to find a solution that minimizes overall travel and reaches the stop within the prescribed time window. Make sure you specify the value as a date and time value, such as 8/12/2015 12:15 PM. When solving a problem that spans multiple time zones, time-window values refer to the time zone in which the stop is located. This field can contain a null value; a null value indicates that a route can arrive at any time after the time indicated in the TimeWindowStart attribute. If a null value is also present in TimeWindowStart, a route can visit the stop at any time. CurbApproach Specifies the direction a vehicle may arrive at and depart from the stop. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):
The CurbApproach attribute is designed to work with both kinds of national driving standards: right-hand traffic (United States) and left-hand traffic (United Kingdom). First, consider a stop 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 stop 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 stop and not have a lane of traffic between the vehicle and the stop, choose 1 (Right side of vehicle) in the United States and 2 (Left side of vehicle) in the United Kingdom. LocationType Specifies the stop type. The field value is specified as one of the following integers (use the numeric code, not the name in the parentheses):
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. Learn more about bearing and bearing tolerance 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 value from the Bearing field 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. Learn more about bearing and bearing tolerance NavLatency This field is only used in the solve process if Bearing and BearingTol also have values; however, entering a NavLatency 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 units you choose for this parameter determine whether the tool will measure distance or time to find the best routes. Choose a time unit to minimize travel time for your chosen travel mode (driving or walking time, for instance). To minimize travel distance for the given travel mode, choose a distance unit. Your choice also determines in which units the tool will report total time or distance in the results.
| 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 your inputs. To specify a region, use one of the following values:
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 your region.
| String |
Reorder_Stops_to_Find_Optimal_Routes (Optional) | Specifies whether to visit the stops in the order you define or the order the tool determines will minimize overall travel.
Finding the optimal stop order and the best routes is commonly known as solving the traveling salesperson problem (TSP). | Boolean |
Preserve_Terminal_Stops (Optional) | Specifies how terminal stops will be preserved. When Reorder Stops to Find Optimal Routes is checked (or True), you can preserve the starting or ending stops, and the tool can reorder the rest. The first and last stops are determined by their Sequence attribute values or, if the Sequence values are null, by their Object ID values.
Preserve Terminal Stops is ignored when Reorder Stops to Find Optimal Routes is unchecked (or False). | String |
Return_to_Start (Optional) | Specifies whether routes will start and end at the same location. With this option, you can avoid duplicating the first stop feature and sequencing the duplicate stop at the end. The starting location of the route is the stop feature with the lowest value in the Sequence attribute. If the Sequence values are null, it is the stop feature with the lowest Object ID value.
| Boolean |
Use_Time_Windows (Optional) | Specifies whether time windows will be honored. Check this option (or set it to True) if any input stops have time windows that specify when the route will reach the stop. You can add time windows to input stops by entering time values in the TimeWindowStart and TimeWindowEnd attributes.
The tool will take slightly longer to run when Use Time Windows is checked (or True), even when none of the input stops have time windows, so it is recommended that you uncheck this option (set to False) if possible. | Boolean |
Time_of_Day (Optional) | The time and date the routes will begin. If you are modeling the driving travel mode and specify the current date and time as the value for this parameter, the tool will use live traffic conditions to find the best routes, and the total travel time will be based on traffic conditions. Specifying a time of day results in more accurate routes and estimations of travel times because the travel times account 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 stop is located. The tool ignores this parameter when Measurement Units isn't set to a time-based unit. | Date |
Time_Zone_for_Time_of_Day (Optional) | Specifies the time zone of the Time of Day parameter.
| 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. | 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):
Additional_Time The added travel time when the barrier is traversed. This field is applicable only for added-cost barriers. This field value must be greater than or equal to zero, and its units are 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. The field value must be greater than or equal to zero, and its units are the same as those specified in the Measurement Units parameter. Additional_Cost The added cost when the barrier is traversed. This field is applicable only for added-cost barriers. 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):
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):
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. Learn more about bearing and bearing tolerance 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 value from the Bearing field 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. Learn more about bearing and bearing tolerance NavLatency This field is only used in the solve process if Bearing and BearingTol also have values; however, entering a NavLatency 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):
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. 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. 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. | Feature Set |
Use_Hierarchy (Optional) | Specifies whether hierarchy will be used when finding the shortest paths between stops.
The tool automatically reverts to using hierarchy if the straight-line distance between facilities and demand points is greater than 50 miles (80.46 kilometers), even if this parameter is unchecked (set to False in Python). This parameter is ignored unless Travel Mode is set to Custom. When modeling a custom walking mode, it is recommended that you turn off hierarchy since hierarchy is designed for motorized vehicles. | Boolean |
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 your vehicle. If you are carrying corrosive materials on your 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 in the Attribute Parameter Values parameter. The ParameterValue field should be specified in 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:
| 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:
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:
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 try to 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 thus 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 thus 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 out of its way to travel on the roads associated with the restriction. | Record Set |
Route_Shape (Optional) | Specifies the type of route features that are 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. | String |
Route_Line_Simplification_Tolerance (Optional) | Specify by how much you want to simplify the geometry of the output lines for routes, directions, and route edges. 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 execution time. | Linear Unit |
Populate_Route_Edges (Optional) | Specifies whether the tool will generate edges for each route. Route edges represent the individual street features or other similar features that are traversed by a route. The output Route Edges layer is commonly used to see which streets or paths are traveled on the most or least by the resultant routes.
| Boolean |
Populate_Directions (Optional) | Specifies whether the tool will generate driving directions for each route.
| 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:
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).
| 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).
| 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 your organization's workflows. You need to specify the name of a travel mode that is supported by your organization. To get a list of supported travel mode names, use the same GIS server connection you used to access this tool, and run the GetTravelModes tool in the Utilities toolbox. The GetTravelModes tool adds the Supported Travel Modes table 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 reduces the tool execution time because the tool does not have to find the settings based on the travel mode name. The default value, Custom, allows you to configure your own 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 your 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. Choose from the following impedance values:
If you choose a time-based impedance, such as TravelTime, TruckTravelTime, Minutes, TruckMinutes, or WalkTime, the Measurement Units parameter must be set to a time-based value. If you choose a distance-based impedance, such as Miles or Kilometers, Measurement Units must be distance-based. 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 |
Time_Zone_for_Time_Windows (Optional) | Specifies the time zone for the time window values on stops. The time windows are specified as part of TimeWindowStart and TimeWindowEnd fields on stops. This parameter is applicable only when the Use Time Windows parameter is checked (or set to True).
| 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.
| Boolean |
Overrides (Optional) | Additional settings that can influence the behavior of the solver when finding solutions for the network analysis problems. The value for this parameter must be specified in JavaScript Object Notation (JSON). For example, a valid value is of the following form: {"overrideSetting1" : "value1", "overrideSetting2" : "value2"}. The override setting name is always enclosed in double quotation marks. The values can be a number, Boolean, or string. The default value for this parameter is no value, which indicates not to override any solver settings. Overrides are advanced settings that should be used only after careful analysis of the results obtained before and after applying the settings. For a list of supported override settings for each solver and their acceptable values, contact Esri Technical Support. | 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.
| Boolean |
Time_Impedance (Optional) | The time-based impedance is a value that 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.
| String |
Distance_Impedance (Optional) | The distance-based impedance is a value that 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.
| String |
Output_Format (Optional) |
Specifies the format in which the output features will be created.
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 execution in the geoprocessing history of your project. In ArcMap, the location of the file can be determined by accessing the Copy Location option in the shortcut menu on the Output Result File parameter in the entry corresponding to the tool execution in the Geoprocessing Results window. | String |
Derived Output
| Name | Explanation | Data Type |
| Solve_Succeeded | Determines if the service was able to find routes successfully. | Boolean |
| Output_Routes | This provides access to the resulting routes. | Feature Set |
| Output_Route_Edges | This provides access to the individual network edges along which the routes travel. | Feature Set |
| Output_Directions | This provides access to the turn-by-turn directions for each resulting route. | Feature Set |
| Output_Stops | This provides access to the attributes of the stops that are visited by the routes as well as stops that cannot be reached by any of the routes. | 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_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 |
Code sample
The following Python script demonstrates how to use the Find Routes tool in a script.
"""This example shows how to find a best route that optimizes the sequence in which the stops are visitied."""
import sys
import time
import datetime
import arcpy
# Change the username and password applicable to your own ArcGIS Online account
username = "<your user name>"
password = "<your password>"
route_service = "https://logistics.arcgis.com/arcgis/services;World/Route;{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(route_service)
# Set the variables to call the tool
stops = "C:/data/Inputs.gdb/Stores"
output_routes = "C:/data/Results.gdb/Routes"
output_directions = "C:/data/Results.gdb/Directions"
# Call the tool specifying current UTC time as start time. This will ensure that the route is
# calculated based on the current traffic conditions. We also want to find the best sequence in
# which to visit the stops but do not want to change the sequence of the first stop since the
# first stop is a pre-defined start location such as an office.
result = arcpy.FindRoutes_Route(stops, "Minutes",
Reorder_Stops_to_Find_Optimal_Routes=True,
Preserve_Terminal_Stops="Preserve First",
Time_of_Day=datetime.datetime.utcnow(),
Time_Zone_for_Time_of_Day="UTC")
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 route and driving directions to a geodatabase
result.getOutput(1).save(output_routes)
result.getOutput(3).save(output_directions)The following example shows how to perform a route analysis using a custom travel mode.
"""This example shows how to perform a route analysis using a custom travel mode
that models trucks carrying wide load."""
import sys
import time
import datetime
import json
import arcpy
username = "<your user name>"
password = "<your password>"
route_service = "https://logistics.arcgis.com/arcgis/services;World/Route;{0};{1}".format(username, password)
# Add the geoprocessing service as a toolbox.
arcpy.ImportToolbox(route_service)
# Set the variables to call the tool
stops = "C:/data/Inputs.gdb/Stops"
output_routes = "C:/data/Results.gdb/Routes"
output_directions = "C:/data/Results.gdb/Directions"
# 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.FindRoutes_Route(stops, "Minutes", Travel_Mode=travel_mode,
Time_of_Day=datetime.datetime(2019, 6, 25, 8, 0, 0))
# 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 route and driving directions to a geodatabase
result.getOutput(1).save(output_routes)
result.getOutput(3).save(output_directions)