arcgis.network.analysis module¶

Network analysis tools.

edit_vehicle_routing_problem¶

arcgis.network.analysis.edit_vehicle_routing_problem(orders, depots, routes, breaks=None, time_units=None, distance_units=None, analysis_region=None, default_date=None, uturn_policy=None, time_window_factor=None, spatially_cluster_routes=True, route_zones=None, route_renewals=None, order_pairs=None, excess_transit_factor=None, point_barriers=None, line_barriers=None, polygon_barriers=None, use_hierarchy_in_analysis=True, restrictions=None, attribute_parameter_values=None, populate_route_lines=True, route_line_simplification_tolerance=None, populate_directions=False, directions_language=None, directions_style_name=None, travel_mode=None, impedance=None, time_zone_usage_for_time_fields=None, save_output_layer=False, overrides=None, save_route_data=None, time_impedance=None, distance_impedance=None, populate_stop_shapes=False, output_format=None, gis=None, ignore_invalid_order_locations=False)

This ArcGIS Online service solves a vehicle routing problem (VRP) to find the best routes for a fleet of vehicles. It is similar to solve_vehicle_routing_problem, but edit_vehicle_routing_problem is designed to make a few, small edits to the results of a VRP and re-solve or solve a small VRP analysis of only two routes.

 Argument Description orders Required FeatureSet. Specify one or more orders (up to 2,000). These are the locations that the routes of the vehicle routing problem (VRP) analysis should visit. An order can represent a delivery (for example, furniture delivery), a pickup (such as an airport shuttle bus picking up a passenger), or some type of service or inspection (a tree trimming job or building inspection, for instance). depots Required FeatureSet. These represent the location where the routes will start and end at for the routes. routes Required FeatureSet. Specify one or more routes (up to 100). A route specifies vehicle and driver characteristics; after solving, it also represents the path between depots and orders. A route can have start and end depot service times, a fixed or flexible starting time, time-based operating costs, distance-based operating costs, multiple capacities, various constraints on a driver’s workday, and so on. When specifying the routes, you can set properties for each one by using attributes. breaks Optional FeatureSet. These are the rest periods, or breaks, for the routes in a given vehicle routing problem. A break is associated with exactly one route, and it can be taken after completing an order, while en-route to an order, or prior to servicing an order. It has a start time and a duration, for which the driver may or may not be paid. There are three options for establishing when a break begins: using a time window, a maximum travel time, or a maximum work time. time_units Optional String. The time units for all time-based field values in the analysis. Allowed values: Seconds, Minutes, Hours, or Days distance_units Optional String. The distance units for all distance-based field values in the analysis. Allowed values: Meters,Kilometers,Feet,Yards,Miles,NauticalMiles analysis_region Optional String. Specify the region in which to perform the analysis. 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. default_date Optional Datetime. The default date for time field values that specify a time of day without including a date. uturn_policy Optional String. Use this parameter to restrict or permit the service area to make U-turns at junctions. The parameter can have the following values: ALLOW_UTURNS-U - turns are permitted everywhere. Allowing U-turns implies that the vehicle can turn around at any junction and double back on the same street. This is the default value. NO_UTURNS-U - turns are prohibited at all junctions: pseudo-junctions, intersections, and dead-ends. Note, however, that U-turns may be permitted even when this option is chosen. ALLOW_DEAD_ENDS_ONLY-U - turns are prohibited at all junctions, except those that have only one connected street feature (a dead end). ALLOW_DEAD_ENDS_AND_INTERSECTIONS_ONLY-U - turns are prohibited at pseudo-junctions where exactly two adjacent streets meet, but U-turns are permitted at intersections and dead ends. This prevents turning around in the middle of the road where one length of road happened to be digitized as two street features. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value. time_window_factor Optional String. Rates the importance of honoring time windows. Allowed values: High, Medium or Low. spatially_cluster_routes Optional Boolean. If true, the dynamic seed points are automatically created for all routes and the orders assigned to an individual route are spatially clustered. This will reduce route intersections. When using route_zones set this parameter to False. route_zones Optional FeatureSet. Delineates work territories for given routes. A route zone is a polygon feature and is used to constrain routes to servicing only those orders that fall within or near the specified area. route_renewals Optional FeatureSet. Specifies the intermediate depots that routes can visit to reload or unload the cargo they are delivering or picking up. order_pairs Optional FeatureSet. This parameter pairs pickup and delivery orders so they are serviced by the same route. excess_transit_factor Optional String. Rates the importance of reducing excess transit time of order pairs. Excess transit time is the amount of time exceeding the time required to travel directly between the paired orders. Excess time can be caused by driver breaks or travel to intermediate orders and depots. Allowed values: High, Medium or Low. point_barriers Optional FeatureSet. Specify points that either completely restrict travel or proportionately scale the time or distance required to travel on the streets intersected by the polygons. line_barriers Optional FeatureSet. Specify polylines that either completely restrict travel or proportionately scale the time or distance required to travel on the streets intersected by the polygons. polygon_barriers Optional FeatureSet. Specify polygons that either completely restrict travel or proportionately scale the time or distance required to travel on the streets intersected by the polygons. use_hierarchy_in_analysis Optional Boolean. Specify whether hierarchy should be used when finding the best routes. True means use hierarchy when finding routes. restrictions Optional String. Specify which restrictions should be honored by the tool when finding the best routes. A restriction represents a driving preference or requirement. attribute_parameter_values Optional Dict. Specify additional values required by some restrictions, such as the weight of a vehicle for Weight Restriction. You can also use the attribute parameter to specify whether any restriction prohibits, avoids, or prefers travel on roads that use the restriction. populate_route_lines Optional Boolean. Specify if the output route line should be generated. route_line_simplification_tolerance Optional Float. Specify by how much you want to simplify the geometry of the output lines for routes and directions.The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value.The tool also ignores this parameter if the populate_route_lines parameter is false. Simplification maintains critical points on a route, such as turns at intersections, to define the essential shape of the route and removes other points. populate_directions Optional Boolean. If True, the directions will be returned. directions_language Optional String. Determines the output language of the directions. directions_style_name Optional String. Determines the style of the directions. travel_mode Optional String. Specify the mode of transportation to model in the analysis. impedance Optional String. Specify 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. time_zone_usage_for_time_fields Optional String. Specifies the time zone for the input date-time fields supported by the tool. The default is GEO_LOCAL. save_output_layer Optional Boolean. Specify if the tool should save the analysis settings as a network analysis layer file. True means save the data and False means do not. overrides Optional Dict. Specify additional settings that can influence the behavior of the solver when finding solutions for the network analysis problems. save_route_data Optional Boolean. Choose whether the output includes a zip file that contains a file geodatabase holding 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. True - Save the route data as a zip file. The file is downloaded in a temporary directory on your machine. False - Do not save the route data. This is the default. time_impedance Optional String. Specify the time-based impedance, which is a value that represents the travel time along road segments or on other parts of the transportation network. If the impedance for the travel mode, as specified using the impedance parameter, is time-based, the value for time_impedance and impedance parameters should be identical. Otherwise the service will return an error. distance_impedance Optional String. If the impedance for the travel mode, as specified using the impedance parameter, is distance-based, the value for distance_impedance and impedance parameters should be identical. Otherwise the service will return an error. Specify the distance-based impedance, which is a value that represents the travel distance along road segments or on other parts of the transportation network. populate_stop_shape Optional Boolean. Specify if the tool should create the shapes for the output assigned and unassigned stops. output_format Optional String. Specify the format in which the output features are created. Choose from the following formats: Feature Set: The output features are returned as feature classes and tables. This is the default. JSON File: The output features are 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 File: The output features are 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. gis Optional GIS. If provided this connection is used to perform the operation. ignore_invalid_order_locations Specifies whether invalid orders will be ignored when solving the vehicle routing problem. True - The solve operation will ignore any invalid orders and return a solution, given it didn’t encounter any other errors. If you need to generate routes and deliver them to drivers immediately, you may be able to ignore invalid orders, solve, and distribute the routes to your drivers. Next, resolve any invalid orders from the last solve and include them in the VRP analysis for the next workday or work shift. False - The solve operation will fail when any invalid orders are encountered. An invalid order is an order that the VRP solver can’t reach. An order may be unreachable for a variety of reasons, including if it’s located on a prohibited network element, it isn’t located on the network at all, or it’s located on a disconnected portion of the network.
Returns

Named Tuple

solve_vehicle_routing_problem¶

arcgis.network.analysis.solve_vehicle_routing_problem(orders: arcgis.features.feature.FeatureSet, depots: arcgis.features.feature.FeatureSet, routes: arcgis.features.feature.FeatureSet, breaks: arcgis.features.feature.FeatureSet = None, time_units: str = 'Minutes', distance_units: str = 'Miles', analysis_region: str = None, default_date: datetime.datetime = None, uturn_policy: str = 'ALLOW_DEAD_ENDS_AND_INTERSECTIONS_ONLY', time_window_factor: str = 'Medium', spatially_cluster_routes: bool = True, route_zones: arcgis.features.feature.FeatureSet = None, route_renewals: arcgis.features.feature.FeatureSet = None, order_pairs: arcgis.features.feature.FeatureSet = None, excess_transit_factor: str = 'Medium', point_barriers: arcgis.features.feature.FeatureSet = None, line_barriers: arcgis.features.feature.FeatureSet = None, polygon_barriers: arcgis.features.feature.FeatureSet = None, use_hierarchy_in_analysis: bool = True, restrictions: str = None, attribute_parameter_values: arcgis.features.feature.FeatureSet = None, populate_route_lines: bool = True, route_line_simplification_tolerance: arcgis.geoprocessing._types.LinearUnit = None, populate_directions: bool = False, directions_language: str = 'en', directions_style_name: str = 'NA Desktop', travel_mode: str = 'Custom', impedance: str = 'Drive Time', gis=None, time_zone_usage_for_time_fields: str = 'GEO_LOCAL', save_output_layer: bool = False, overrides: str = None, save_route_data: bool = False, time_impedance=None, distance_impedance=None, populate_stop_shapes=False, output_format=None, future=False, ignore_invalid_order_locations=False) → tuple

solve_vehicle_routing_problem tool solves a vehicle routing problem (VRP) to find the best routes for a fleet of vehicles. A dispatcher managing a fleet of vehicles is often required to make decisions about vehicle routing. One such decision involves how to best assign a group of customers to a fleet of vehicles and to sequence and schedule their visits. The objectives in solving such vehicle routing problems (VRP) are to provide a high level of customer service by honoring any time windows while keeping the overall operating and investment costs for each route as low as possible. The constraints are to complete the routes with available resources and within the time limits imposed by driver work shifts, driving speeds, and customer commitments. This method can be used to determine solutions for such complex fleet management tasks.

Consider an example of delivering goods to grocery stores from a central warehouse location. A fleet of three trucks is available at the warehouse. The warehouse operates only within a certain time window (from 8:00 a.m. to 5:00 p.m.) during which all trucks must return back to the warehouse. Each truck has a capacity of 15,000 pounds, which limits the amount of goods it can carry. Each store has a demand for a specific amount of goods ( in pounds) that needs to be delivered, and each store has time windows that confine when deliveries should be made. Furthermore, the driver can work only eight hours per day, requires a break for lunch, and is paid for the time spent on driving and servicing the stores. The goal is to come up with an itinerary for each driver (or route) such that the deliveries can be made while honoring all the service requirements and minimizing the total time spent on a particular route by the driver.

Argument

Description

orders

Required FeatureSet. Specify one or more orders (up to 2,000). These are the locations that the routes of the vehicle routing problem (VRP) analysis should visit. An order can represent a delivery (for example, furniture delivery), a pickup (such as an airport shuttle bus picking up a passenger), or some type of service or inspection (a tree trimming job or building inspection, for instance).

When specifying the orders, you can set properties for each one, such as its name or service time, by using attributes. The orders can be specified with the following attributes:

• ObjectID: The system-managed ID field.

• Name: The name of the order. The name must be unique. If the name is left null, a name is automatically generated at solve time.

• Description: The descriptive information about the order. This can contain any textual information for the order and has no restrictions for uniqueness. You may want to store a client’s ID number in the Name field and the client’s actual name or address in the Description field.

• ServiceTime: This property specifies how much time will be spent at the network location when the route visits it; that is, it stores the impedance value for the network location. A zero or null value indicates the network location requires no service time. The unit for this field value is specified by the time_units parameter.

• TimeWindowStart1: The beginning time of the first time window for the network location. This field can contain a null value; a null value indicates no beginning time.

A time window only states when a vehicle can arrive at an order; it doesn’t state when the service time must be completed. To account for service time and leave before the time window is over, subtract ServiceTime from the TimeWindowEnd1 field.

The time window fields (TimeWindowStart1, TimeWindowEnd1, TimeWindowStart2, and TimeWindowEnd2) can contain a time-only value or a date and time value. If a time field such as TimeWindowStart1 has a time-only value (for example, 8:00 AM), the date is assumed to be the date specified by the Default Date parameter. Using date and time values (for example, 7/11/2010 8:00 AM) allows you to set time windows that span multiple days.

When solving a problem that spans multiple time zones, each order’s time-window values refer to the time zone in which the order is located.

• TimeWindowEnd1: The ending time of the first window for the network location. This field can contain a null value; a null value indicates no ending time.

• TimeWindowStart2: The beginning time of the second time window for the network location. This field can contain a null value; a null value indicates that there is no second time window.

If the first time window is null, as specified by the TimeWindowStart1 and TimeWindowEnd1 fields, the second time window must also be null.

If both time windows are non null, they can’t overlap. Also, the second time window must occur after the first.

• TimeWindowEnd2: The ending time of the second time window for the network location. This field can contain a null value.

When TimeWindowStart2 and TimeWindowEnd2 are both null, there is no second time window.

When TimeWindowStart2 is not null but TimeWindowEnd2 is null, there is a second time window that has a starting time but no ending time. This is valid.

• MaxViolationTime1: A time window is considered violated if the arrival time occurs after the time window has ended. This field specifies the maximum allowable violation time for the first time window of the order. It can contain a zero value but can’t contain negative values. A zero value indicates that a time window violation at the first time window of the order is unacceptable; that is, the first time window is hard. On the other hand, a null value indicates that there is no limit on the allowable violation time. A nonzero value specifies the maximum amount of lateness; for example, a route can arrive at an order up to 30 minutes beyond the end of its first time window.

The unit for this field value is specified by the Time Field Units parameter

Time window violations can be tracked and weighted by the solver. Because of this, you can direct the VRP solver to take one of three approaches:

• Minimize the overall violation time, regardless of the increase in travel cost for the fleet.

• Find a solution that balances overall violation time and travel cost.

• Ignore the overall violation time; instead, minimize the travel cost for the fleet.

By assigning an importance level for the Time Window Violation Importance parameter, you are essentially choosing one of these three approaches. In any case, however, the solver will return an error if the value set for MaxViolationTime1 is surpassed.

• MaxViolationTime2: The maximum allowable violation time for the second time window of the order. This field is analogous to the MaxViolationTime1 field.

• InboundArriveTime: Defines when the item to be delivered to the order will be ready at the starting depot. The order can be assigned to a route only if the inbound arrive time the route’s latest start time value; this way, the route cannot leave the depot before the item is ready to be loaded onto it.

This field can help model scenarios involving inbound-wave transshipments. For example, a job at an order requires special materials that are not currently available at the depot. The materials are being shipped from another location and will arrive at the depot at 11:00 a.m. To ensure a route that leaves before the shipment arrives isn’t assigned to the order, the order’s inbound arrive time is set to 11:00 a.m. The special materials arrive at 11:00 a.m., they are loaded onto the vehicle, and the vehicle departs from the depot to visit its assigned orders.

Note

• The route’s start time, which includes service times, must occur after the inbound arrive time. If a route begins before an order’s inbound arrive time, the order cannot be assigned to the route. The assignment is invalid even if the route has a start-depot service time that lasts until after the inbound arrive time.

• This time field can contain a time-only value or a date and time value. If a time-only value is set (for example, 11:00 AM), the date is assumed to be the date specified by the Default Date parameter. The default date is ignored, however, when any time field in the Depots, Routes, Orders, or Breaks includes a date with the time. In that case, specify all such fields with a date and time (for example, 7/11/2015 11:00 AM).

• The VRP solver honors InboundArriveTime regardless of the DeliveryQuantities value.

• If an outbound depart time is also specified, its time value must occur after the inbound arrive time.

• OutboundDepartTime: Defines when the item to be picked up at the order must arrive at the ending depot. The order can be assigned to a route only if the route can visit the order and reach its end depot before the specified outbound depart time.

This field can help model scenarios involving outbound-wave transshipments. For instance, a shipping company sends out delivery trucks to pick up packages from orders and bring them into a depot where they are forwarded on to other facilities, en route to their final destination. At 3:00 p.m. every day, a semitrailer stops at the depot to pick up the high-priority packages and take them directly to a central processing station. To avoid delaying the high-priority packages until the next day’s 3:00 p.m. trip, the shipping company tries to have delivery trucks pick up the high-priority packages from orders and bring them to the depot before the 3:00 p.m. deadline. This is done by setting the outbound depart time to 3:00 p.m.

Note

• The route’s end time, including service times, must occur before the outbound depart time. If a route reaches a depot but doesn’t complete its end-depot service time prior to the order’s outbound depart time, the order cannot be assigned to the route.

• This time field can contain a time-only value or a date and time value. If a time-only value is set (for example, 11:00 AM), the date is assumed to be the date specified by the Default Date parameter. The default date is ignored, however, when any time field in Depots, Routes, Orders, or Breaks includes a date with the time. In that case, specify all such fields with a date and time (for example, 7/11/2015 11:00 AM).

• The VRP solver honors OutboundDepartTime regardless of the PickupQuantities value.

• If an inbound arrive time is also specified, its time value must occur before the outbound depart time.

• DeliveryQuantities: The size of the delivery. You can specify size in any dimension you want, such as weight, volume, or quantity. You can even specify multiple dimensions, for example, weight and volume.

Enter delivery quantities without indicating units. For example, if a 300-pound object needs to be delivered to an order, enter 300. You will need to remember that the value is in pounds.

If you are tracking multiple dimensions, separate the numeric values with a space. For instance, if you are recording the weight and volume of a delivery that weighs 2,000 pounds and has a volume of 100 cubic feet, enter 2000 100. Again, you need to remember the units-in this case, pounds and cubic feet. You also need to remember the sequence in which the values and their corresponding units are entered.

Make sure that Capacities for Routes and DeliveryQuantities and PickupQuantities for Orders are specified in the same manner; that is, the values need to be in the same units, and if you are using multiple dimensions, the dimensions need to be listed in the same sequence for all parameters. So if you specify weight in pounds, followed by volume in cubic feet for DeliveryQuantities, the capacity of your routes and the pickup quantities of your orders need to be specified the same way: weight in pounds, then volume in cubic feet. If you mix units or change the sequence, you will get unwanted results without receiving any warning messages.

An empty string or null value is equivalent to all dimensions being zero. If the string has an insufficient number of values in relation to the capacity count, or dimensions being tracked, the remaining values are treated as zeros. Delivery quantities can’t be negative.

• PickupQuantities: The size of the pickup. You can specify size in any dimension you want, such as weight, volume, or quantity. You can even specify multiple dimensions, for example, weight and volume. You cannot, however, use negative values. This field is analogous to the DeliveryQuantities field of Orders.

In the case of an exchange visit, an order can have both delivery and pickup quantities.

• Revenue: The income generated if the order is included in a solution. This field can contain a null value-a null value indicates zero revenue-but it can’t have a negative value.

Revenue is included in optimizing the objective function value but is not part of the solution’s operating cost; that is, the TotalCost field in the route class never includes revenue in its output. However, revenue weights the relative importance of servicing orders.

• SpecialtyNames: A space-separated string containing the names of the specialties required by the order. A null value indicates that the order doesn’t require specialties.

The spelling of any specialties listed in the Orders and Routes classes must match exactly so that the VRP solver can link them together.

To illustrate what specialties are and how they work, assume a lawn care and tree trimming company has a portion of its orders that requires a bucket truck to trim tall trees. The company would enter BucketTruck in the SpecialtyNames field for these orders to indicate their special need. SpecialtyNames would be left as null for the other orders. Similarly, the company would also enter BucketTruck in the SpecialtyNames field of routes that are driven by trucks with hydraulic booms. It would leave the field null for the other routes. At solve time, the VRP solver assigns orders without special needs to any route, but it only assigns orders that need bucket trucks to routes that have them.

• AssignmentRule: This field specifies the rule for assigning the order to a route. It is constrained by a domain of values, which are listed below (use the numeric code, not the name in parentheses).

• 0 (Exclude) - The order is to be excluded from the subsequent solve operation.

• 1 (Preserve route and relative sequence) - The solver must always assign the order to the preassigned route and at the preassigned relative sequence during the solve operation. If this assignment rule can’t be followed, it results in an order violation. With this setting, only the relative sequence is maintained, not the absolute sequence. To illustrate what this means, imagine there are two orders: A and B. They have sequence values of 2 and 3, respectively. If you set their AssignmentRule field values to Preserve route and relative sequence, A and B’s actual sequence values may change after solving because other orders, breaks, and depot visits could still be sequenced before, between, or after A and B. However, B cannot be sequenced before A.

• 2 (Preserve route) - The solver must always assign the order to the preassigned route during the solve operation. A valid sequence must also be set even though the sequence may or may not be preserved. If the order can’t be assigned to the specified route, it results in an order violation.

• 3 (Override) - The solver tries to preserve the route and sequence preassignment for the order during the solve operation. However, a new route or sequence for the order may be assigned if it helps minimize the overall value of the objective function. This is the default value.

• 4 (Anchor first) - The solver ignores the route and sequence preassignment (if any) for the order during the solve operation. It assigns a route to the order and makes it the first order on that route to minimize the overall value of the objective function.

• 5 (Anchor last) - The solver ignores the route and sequence preassignment (if any) for the order during the solve operation. It assigns a route to the order and makes it the last order on that route to minimize the overall value of the objective function. This field can’t contain a null value.

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

 Setting Description Either side of vehicle The vehicle can approach and depart the order in either direction, so a U-turn is allowed at the order. This setting can be chosen if it is possible and desirable for your vehicle to turn around at the order. This decision may depend on the width of the road and the amount of traffic or whether the order has a parking lot where vehicles can pull in and turn around. right side of vehicle When the vehicle approaches and departs the order, the order must be on the right side of the vehicle. A U-turn is prohibited. This is typically used for vehicles like buses that must arrive with the bus stop on the right side. left side of vehicle When the vehicle approaches and departs the order, the curb must be on the left side of the vehicle. A U-turn is prohibited. This is typically used for vehicles like buses that must arrive with the bus stop on the left-hand side. No U-Turn When the vehicle approaches the order, the curb can be on either side of the vehicle; however, the vehicle must depart without turning around.

The CurbApproach property is designed to work with both kinds of national driving standards: right-hand traffic (United States) and left-hand traffic (United Kingdom). First, consider an order 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 order 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 order and not have a lane of traffic between the vehicle and the order, you would choose 1 (Right side of vehicle) in the United States but 2 (Left side of vehicle) in the United Kingdom.

• RouteName: The name of the route to which the order is assigned. As an input field, this field is used to preassign an order to a specific route. (A maximum of 200 orders can be preassigned to one route name.) It can contain a null value, indicating that the order is not preassigned to any route, and the solver determines the best possible route assignment for the order. If this is set to null, the sequence field must also be set to null.

After a solve operation, if the order is routed, the RouteName field contains the name of the route to which the order is assigned.

• Sequence: This indicates the sequence of the order on its assigned route.

As an input field, this field is used to specify the relative sequence for an order on the route. This field can contain a null value specifying that the order can be placed anywhere along the route. A null value can only occur together with a null RouteName value.

The input sequence values are positive and unique for each route (shared across renewal depot visits, orders, and breaks) but do not need to start from 1 or be contiguous.

After a solve operation, the Sequence field contains the sequence value of the order on its assigned route. Output sequence values for a route are shared across depot visits, orders, and breaks; start from 1 (at the starting depot); and are consecutive. So the smallest possible output sequence value for a routed order is 2, since a route always begins at a depot.

• 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 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 ArcGIS Network Analyst extension 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 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 time 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 time units of NavLatency are the same as the units specified by the timeUnits property of the analysis object.

depots

Required FeatureSet. Specify one or more depots for the given vehicle routing problem. A depot is a location that a vehicle departs from at the beginning of its workday and returns to at the end of the workday. Vehicles are loaded (for deliveries) or unloaded (for pickups) at depots at the start of the route. In some cases, a depot can also act as a renewal location whereby the vehicle can unload or reload and continue performing deliveries and pickups. A depot has open and close times, as specified by a hard time window. Vehicles can’t arrive at a depot outside of this time window. When specifying the orders, you can set properties for each one, such as its name or service time, by using attributes.

The orders can be specified with the following attributes:

• ObjectID: The system-managed ID field.

• Name: The name of the depot. The StartDepotName and EndDepotName fields of the Routes record set reference the names you specify here. It is also referenced by the Route Renewals record set, when used.

Depot names are case insensitive and have to be nonempty and unique.

• Description : The descriptive information about the depot location. This can contain any textual information and has no restrictions for uniqueness.

For example, if you want to note which region a depot is in or the depot’s address and telephone number, you can enter the information here rather than in the Name field.

• TimeWindowStart1: The beginning time of the first time window for the network location. This field can contain a null value; a null value indicates no beginning time.

Time window fields can contain a time-only value or a date and time value. If a time field has a time-only value (for example, 8:00 AM), the date is assumed to be the date specified by the Default Date parameter of the analysis layer. Using date and time values (for example, 7/11/2010 8:00 AM) allows you to set time windows that span multiple days.

When solving a problem that spans multiple time zones, each depot’s time-window values refer to the time zone in which the depot is located.

• TimeWindowEnd1: The ending time of the first window for the network location. This field can contain a null value; a null value indicates no ending time.

• TimeWindowStart2: The beginning time of the second time window for the network location. This field can contain a null value; a null value indicates that there is no second time window.

If the first time window is null, as specified by the TimeWindowStart1 and TimeWindowEnd1 fields, the second time window must also be null.

If both time windows are nonnull, they can’t overlap. Also, the second time window must occur after the first.

• TimeWindowEnd2: The ending time of the second time window for the network location. This field can contain a null value.

When TimeWindowStart2 and TimeWindowEnd2 are both null, there is no second time window.

When TimeWindowStart2 is not null but TimeWindowEnd2 is null, there is a second time window that has a starting time but no ending time. This is valid.

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

 Setting Description Either side of vehicle The vehicle can approach and depart the order in either direction, so a U-turn is allowed at the order. This setting can be chosen if it is possible and desirable for your vehicle to turn around at the order. This decision may depend on the width of the road and the amount of traffic or whether the order has a parking lot where vehicles can pull in and turn around. right side of vehicle When the vehicle approaches and departs the order, the order must be on the right side of the vehicle. A U-turn is prohibited. This is typically used for vehicles like buses that must arrive with the bus stop on the right side. left side of vehicle When the vehicle approaches and departs the order, the curb must be on the left side of the vehicle. A U-turn is prohibited. This is typically used for vehicles like buses that must arrive with the bus stop on the left side. No U-Turn When the vehicle approaches the order, the curb can be on either side of the vehicle; however, the vehicle must depart without turning around.

The CurbApproach property 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 depot 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 depot 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 depot and not have a lane of traffic between the vehicle and the depot, you would choose 1 (Right side of vehicle) in the United States but 2 (Left side of vehicle) in the United Kingdom.

• Bearing: The direction in which a point is moving. The units are degrees and measured in a clockwise fashion 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 order 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. For more information, see the Bearing and Bearing Tolerance Help topic (http://links.esri.com/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 zero 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. For more information, see the Bearing and Bearing Tolerance topic in the ArcGIS help system (http://links.esri.com/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 time 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 time units of NavLatency are the same as the units of the cost attribute specified by the parameter Time Attribute.

routes

Required FeatureSet. Specify one or more routes (up to 100). A route specifies vehicle and driver characteristics; after solving, it also represents the path between depots and orders.

A route can have start and end depot service times, a fixed or flexible starting time, time-based operating costs, distance-based operating costs, multiple capacities, various constraints on a driver’s workday, and so on. When specifying the routes, you can set properties for each one by using attributes. The routes can be specified with the following attributes:

• Name: The name of the route. The name must be unique.

The tool generates a unique name at solve time if the field value is null; therefore, entering a value is optional in most cases. However, you must enter a name if your analysis includes breaks, route renewals, route zones, or orders that are preassigned to a route because the route name is used as a foreign key in these cases. Note that route names are case insensitive.

• StartDepotName: The name of the starting depot for the route. This field is a foreign key to the Name field in Depots.

If the StartDepotName value is null, the route will begin from the first order assigned. Omitting the start depot is useful when the vehicle’s starting location is unknown or irrelevant to your problem. However, when StartDepotName is null, EndDepotName cannot also be null.

If the route is making deliveries and StartDepotName is null, it is assumed the cargo is loaded on the vehicle at a virtual depot before the route begins. For a route that has no renewal visits, its delivery orders (those with nonzero DeliveryQuantities values in the Orders class) are loaded at the start depot or virtual depot. For a route that has renewal visits, only the delivery orders before the first renewal visit are loaded at the start depot or virtual depot.

• EndDepotName: The name of the ending depot for the route. This field is a foreign key to the Name field in the Depots class.

• StartDepotServiceTime: The service time at the starting depot. This can be used to model the time spent for loading the vehicle. This field can contain a null value; a null value indicates zero service time.

The unit for this field value is specified by the Time Field Units parameter.

The service times at the start and end depots are fixed values (given by the StartDepotServiceTime and EndDepotServiceTime field values) and do not take into account the actual load for a route. For example, the time taken to load a vehicle at the starting depot may depend on the size of the orders. As such, the depot service times could be given values corresponding to a full truckload or an average truckload, or you could make your own time estimate.

• EndDepotServiceTime: The service time at the ending depot. This can be used to model the time spent for unloading the vehicle. This field can contain a null value; a null value indicates zero service time.

The unit for this field value is specified by the Time Field Units parameter.

The service times at the start and end depots are fixed values (given by the StartDepotServiceTime and EndDepotServiceTime field values) and do not take into account the actual load for a route. For example, the time taken to load a vehicle at the starting depot may depend on the size of the orders. As such, the depot service times could be given values corresponding to a full truckload or an average truckload, or you could make your own time estimate.

• EarliestStartTime: The earliest allowable starting time for the route. This is used by the solver in conjunction with the time window of the starting depot for determining feasible route start times.

This field can’t contain null values and has a default time-only value of 8:00 AM; the default value is interpreted as 8:00 a.m. on the date given by the Default Date parameter.

When solving a problem that spans multiple time zones, the time zone for EarliestStartTime is the same as the time zone in which the starting depot is located.

• LatestStartTime: The latest allowable starting time for the route. This field can’t contain null values and has a default time-only value of 10:00 AM; the default value is interpreted as 10:00 a.m. on the date given by the Default Date property of the analysis layer.

When solving a problem that spans multiple time zones, the time zone for LatestStartTime is the same as the time zone in which the starting depot is located.

• ArriveDepartDelay: This field stores the amount of travel time needed to accelerate the vehicle to normal travel speeds, decelerate it to a stop, and move it off and on the network (for example, in and out of parking). By including an ArriveDepartDelay value, the VRP solver is deterred from sending many routes to service physically coincident orders.

The cost for this property is incurred between visits to noncoincident orders, depots, and route renewals. For example, when a route starts from a depot and visits the first order, the total arrive/depart delay is added to the travel time. The same is true when traveling from the first order to the second order. If the second and third orders are coincident, the ArriveDepartDelay value is not added between them since the vehicle doesn’t need to move. If the route travels to a route renewal, the value is added to the travel time again.

Although a vehicle needs to slow down and stop for a break and accelerate afterwards, the VRP solver cannot add the ArriveDepartDelay value for breaks. This means that if a route leaves an order, stops for a break, and continues to the next order, the arrive/depart delay is added only once, not twice.

To illustrate, assume there are five coincident orders in a high-rise building, and they are serviced by three different routes. This means three arrive/depart delays would be incurred; that is, three drivers would need to separately find parking places and enter the same building. However, if the orders could be serviced by just one route instead, only one driver would need to park and enter the building-only one arrive/depart delay would be incurred. Since the VRP solver tries to minimize cost, it will try to limit the arrive/depart delays and thus choose the single-route option. (Note that multiple routes may need to be sent when other constraints-such as specialties, time windows, or capacities-require it.) The unit for this field value is specified by the time_units parameter.

• Capacities: The maximum capacity of the vehicle. You can specify capacity in any dimension you want, such as weight, volume, or quantity. You can even specify multiple dimensions, for example, weight and volume.

Enter capacities without indicating units. For example, assume your vehicle can carry a maximum of 40,000 pounds; you would enter 40000. You need to remember for future reference that the value is in pounds.

If you are tracking multiple dimensions, separate the numeric values with a space. For instance, if you are recording both weight and volume and your vehicle can carry a maximum weight of 40,000 pounds and a maximum volume of 2,000 cubic feet, Capacities should be entered as 40000 2000. Again, you need to remember the units. You also need to remember the sequence in which the values and their corresponding units are entered (pounds followed by cubic feet in this case).

Remembering the units and the unit sequence is important for a couple of reasons: one, so you can reinterpret the information later; two, so you can properly enter values for the DeliveryQuantities and PickupQuantities fields for the orders. To elaborate on the second point, note that the VRP solver simultaneously refers to Capacities, DeliveryQuantities, and PickupQuantities to make sure that a route doesn’t become overloaded. Since units can’t be entered in the field, the VRP tool can’t make unit conversions, so you need to enter the values for the three fields using the same units and the same unit sequence to ensure the values are correctly interpreted. If you mix units or change the sequence in any of the three fields, you will get unwanted results without receiving any warning messages. Thus, it is a good idea to set up a unit and unit-sequence standard beforehand and continually refer to it whenever entering values for these three fields.

An empty string or null value is equivalent to all values being zero. Capacity values can’t be negative.

If the Capacities string has an insufficient number of values in relation to the DeliveryQuantities or PickupQuantities fields for orders, the remaining values are treated as zero.

• FixedCost: A fixed monetary cost that is incurred only if the route is used in a solution (that is, it has orders assigned to it). This field can contain null values; a null value indicates zero fixed cost. This cost is part of the total route operating cost.

• CostPerUnitTime: The monetary cost incurred-per unit of work time-for the total route duration, including travel times as well as service times and wait times at orders, depots, and breaks. This field can’t contain a null value and has a default value of 1.0. The unit for this field value is specified by the time_units parameter.

• CostPerUnitDistance: The monetary cost incurred-per unit of distance traveled-for the route length (total travel distance). This field can contain null values; a null value indicates zero cost. The unit for this field value is specified by the distance_units parameter.

• OvertimeStartTime: The duration of regular work time before overtime computation begins. This field can contain null values; a null value indicates that overtime does not apply. The unit for this field value is specified by the time_units parameter. For example, if the driver is to be paid overtime pay when the total route duration extends beyond eight hours, OvertimeStartTime is specified as 480 (8 hours * 60 minutes/hour), given the time_units parameter is set to Minutes.

• CostPerUnitOvertime: The monetary cost incurred per time unit of overtime work. This field can contain null values; a null value indicates that the CostPerUnitOvertime value is the same as the CostPerUnitTime value.

• MaxOrderCount: The maximum allowable number of orders on the route. This field can’t contain null values and has a default value of 30. This value cannot exceed 200.

• MaxTotalTime: The maximum allowable route duration. The route duration includes travel times as well as service and wait times at orders, depots, and breaks. This field can contain null values; a null value indicates that there is no constraint on the route duration. The unit for this field value is specified by the time_units parameter.

• MaxTotalTravelTime: The maximum allowable travel time for the route. The travel time includes only the time spent driving on the network and does not include service or wait times.

This field can contain null values; a null value indicates there is no constraint on the maximum allowable travel time. This field value can’t be larger than the MaxTotalTime field value. The unit for this field value is specified by the time_units parameter.

• MaxTotalDistance: The maximum allowable travel distance for the route. The unit for this field value is specified by the distance_units parameter. This field can contain null values; a null value indicates that there is no constraint on the maximum allowable travel distance.

• SpecialtyNames: A space-separated string containing the names of the specialties supported by the route. A null value indicates that the route does not support any specialties.

This field is a foreign key to the SpecialtyNames field in the orders class.

To illustrate what specialties are and how they work, assume a lawn care and tree trimming company has a portion of its orders that requires a bucket truck to trim tall trees. The company would enter BucketTruck in the SpecialtyNames field for these orders to indicate their special need. SpecialtyNames would be left as null for the other orders. Similarly, the company would also enter BucketTruck in the SpecialtyNames field of routes that are driven by trucks with hydraulic booms. It would leave the field null for the other routes. At solve time, the VRP solver assigns orders without special needs to any route, but it only assigns orders that need bucket trucks to routes that have them.

• AssignmentRule: This specifies whether the route can be used or not when solving the problem. This field is constrained by a domain of values, which are listed below (use the numeric code, not the name in parentheses).

• 1 (Include) - The route is included in the solve operation. This is the default value.

• 2 (Exclude) - The route is excluded from the solve operation.

breaks

Optional FeatureSet. These are the rest periods, or breaks, for the routes in a given vehicle routing problem. A break is associated with exactly one route, and it can be taken after completing an order, while en route to an order, or prior to servicing an order. It has a start time and a duration, for which the driver may or may not be paid. There are three options for establishing when a break begins: using a time window, a maximum travel time, or a maximum work time. When specifying the breaks, you can set properties for each one, such as its name or service time, by using attributes. The breaks parameter can be specified with the following attributes:

• RouteName: The name of the route that the break applies to. Although a break is assigned to exactly one route, many breaks can be assigned to the same route.

This field is a foreign key to the Name field in the routes parameter, so it can’t have a null value.

• Precedence: Precedence values sequence the breaks of a given route. Breaks with a precedence value of 1 occur before those with a value of 2, and so on.

All breaks must have a precedence value, regardless of whether they are time-window, maximum-travel-time, or maximum-work-time breaks.

• ServiceTime: The duration of the break. This field can contain null values; a null value indicates no service time. The unit for this field value is specified by the time_units parameter.

• TimeWindowStart: The starting time of the break’s time window.

If this field is null and TimeWindowEnd has a valid time-of-day value, the break is allowed to start any time before the TimeWindowEnd value.

If this field has a value, the MaxTravelTimeBetweenBreaks and MaxCumulWorkTime field values must be null; moreover, all other breaks in the analysis layer must have null values for MaxTravelTimeBetweenBreaks and MaxCumulWorkTime.

An error will occur at solve time if a route has multiple breaks with overlapping time windows.

The time window fields in breaks can contain a time-only value or a date and time value. If a time field, such as TimeWindowStart, has a time-only value (for example, 12:00 PM), the date is assumed to be the date specified by the default_date parameter. Using date and time values (for example, 7/11/2012 12:00 PM) allows you to specify time windows that span two or more days. This is especially beneficial when a break should be taken sometime before and after midnight. When solving a problem that spans multiple time zones, each break’s time-window values refer to the time zone in which the associated route, as specified by the RouteName field, is located.

• TimeWindowEnd: The ending time of the break’s time window.

If this field is null and TimeWindowStart has a valid time-of-day value, the break is allowed to start any time after the TimeWindowStart value.

If this field has a value, MaxTravelTimeBetweenBreaks and MaxCumulWorkTime must be null; moreover, all other breaks in the analysis layer must have null values for MaxTravelTimeBetweenBreaks and MaxCumulWorkTime.

• MaxViolationTime: This field specifies the maximum allowable violation time for a time-window break. A time window is considered violated if the arrival time falls outside the time range.

A zero value indicates the time window cannot be violated; that is, the time window is hard. A nonzero value specifies the maximum amount of lateness; for example, the break can begin up to 30 minutes beyond the end of its time window, but the lateness is penalized as per the Time Window Violation Importance parameter.

This property can be null; a null value with TimeWindowStart and TimeWindowEnd values indicates that there is no limit on the allowable violation time. If MaxTravelTimeBetweenBreaks or MaxCumulWorkTime has a value, MaxViolationTime must be null. The unit for this field value is specified by the time_units parameter.

• MaxTravelTimeBetweenBreaks: The maximum amount of travel time that can be accumulated before the break is taken. The travel time is accumulated either from the end of the previous break or, if a break has not yet been taken, from the start of the route.

If this is the route’s final break, MaxTravelTimeBetweenBreaks also indicates the maximum travel time that can be accumulated from the final break to the end depot.

This field is designed to limit how long a person can drive until a break is required. For instance, if the Time Field Units parameter (time_units for Python) of the analysis is set to Minutes, and MaxTravelTimeBetweenBreaks has a value of 120, the driver will get a break after two hours of driving. To assign a second break after two more hours of driving, the second break’s MaxTravelTimeBetweenBreaks property should be 120.

If this field has a value, TimeWindowStart, TimeWindowEnd, MaxViolationTime, and MaxCumulWorkTime must be null for an analysis to solve successfully. The unit for this field value is specified by the time_units parameter.

• MaxCumulWorkTime: The maximum amount of work time that can be accumulated before the break is taken. Work time is always accumulated from the beginning of the route.

Work time is the sum of travel time and service times at orders, depots, and breaks. Note, however, that this excludes wait time, which is the time a route (or driver) spends waiting at an order or depot for a time window to begin.

This field is designed to limit how long a person can work until a break is required. For instance, if the time_units parameter is set to Minutes, MaxCumulWorkTime has a value of 120, and ServiceTime has a value of 15, the driver will get a 15-minute break after two hours of work.

Continuing with the last example, assume a second break is needed after three more hours of work. To specify this break, you would enter 315 (five hours and 15 minutes) as the second break’s MaxCumulWorkTime value. This number includes the MaxCumulWorkTime and ServiceTime values of the preceding break, along with the three additional hours of work time before granting the second break. To avoid taking maximum-work-time breaks prematurely, remember that they accumulate work time from the beginning of the route and that work time includes the service time at previously visited depots, orders, and breaks.

If this field has a value, TimeWindowStart, TimeWindowEnd, MaxViolationTime, and MaxTravelTimeBetweenBreaks must be null for an analysis to solve successfully. The unit for this field value is specified by the time_units parameter.

• IsPaid: A Boolean value indicating whether the break is paid or unpaid. A True value indicates that the time spent at the break is included in the route cost computation and overtime determination. A False value indicates otherwise. The default value is True.

• Sequence: As an input field, this indicates the sequence of the break on its route. This field can contain null values. The input sequence values are positive and unique for each route (shared across renewal depot visits, orders, and breaks) but need not start from 1 or be contiguous.

The solver modifies the sequence field. After solving, this field contains the sequence value of the break on its route. Output sequence values for a route are shared across depot visits, orders, and breaks; start from 1 (at the starting depot); and are consecutive.

• ArriveTimeUTC: The date and time value indicating the arrival time in UTC time.

• DepartTimeUTC: The date and time value indicating the departure time in UTC time.

time_units

Optional string. The time units for all time-based field values in the analysis. Many features and records in a VRP analysis have fields for storing time values, such as ServiceTime for orders and CostPerUnitTime for routes. To minimize data entry requirements, these field values don’t include units. Instead, all distance-based field values must be entered in the same units, and this parameter is used to specify the units of those values.

Note that output time-based fields use the same units specified by this parameter.

Choice list:[‘Seconds’, ‘Minutes’, ‘Hours’, ‘Days’]

distance_units

Optional string. The distance units for all distance-based field values in the analysis. Many features and records in a VRP analysis have fields for storing distance values, such as MaxTotalDistance and CostPerUnitDistance for Routes. To minimize data entry requirements, these field values don’t include units. Instead, all distance-based field values must be entered in the same units, and this parameter is used to specify the units of those values.

Note that output distance-based fields use the same units specified by this parameter.

Choice list:[‘Meters’, ‘Kilometers’, ‘Feet’, ‘Yards’, ‘Miles’, ‘NauticalMiles’]

analysis_region

Optional string. Specify the region in which to perform the analysis. 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 recommended to speed up the tool execution. To specify a region, use one of the following values: Europe Greece India Japan Korea MiddleEastAndAfrica NorthAmerica Oceania SouthAmerica SouthEastAsia Taiwan Thailand

Choice list:[‘NorthAmerica’, ‘SouthAmerica’, ‘Europe’, ‘MiddleEastAndAfrica’, ‘India’, ‘SouthAsia’, ‘SouthEastAsia’, ‘Thailand’, ‘Taiwan’, ‘Japan’, ‘Oceania’, ‘Greece’, ‘Korea’]

default_date

Optional datetime. The default date for time field values that specify a time of day without including a date. You can find these time fields in various input parameters, such as the ServiceTime attributes in the orders and breaks parameters.

uturn_policy

Optional string. Use this parameter to restrict or permit the service area to make U-turns at junctions. In order to understand the parameter values, consider for a moment the following terminology: a junction is a point where a street segment ends and potentially connects to one or more other segments; a pseudo-junction is a point where exactly two streets connect to one another; an intersection is a point where three or more streets connect; and a dead-end is where one street segment ends without connecting to another. Given this information, the parameter can have the following values:

 Parameter Description ALLOW_UTURNS U-turns are permitted everywhere. Allowing U-turns implies that the vehicle can turn around at a junction or intersection and double back on the same street. ALLOW_DEAD_ENDS_AND _INTERSECTIONS_ONLY U-turns are prohibited at junctions where exactly two adjacent streets meet. ALLOW_DEAD_ENDS_ONLY U-turns are prohibited at all junctions and interesections nd are permitted only at dead ends. NO_UTURNS U-turns are prohibited at all junctions, intersections, and dead-ends. Note that even when this parameter value is chosen, a route can still make U-turns at stops. If you wish to prohibit U-turns at a stop, you can set its CurbApproach property to the appropriate value (3). The default value for this parameter is ‘ALLOW_UTURNS’.

time_window_factor

Optional string. Rates the importance of honoring time windows. There are three options described below.

Choice list:[‘High’, ‘Medium’, ‘Low’]

• High - Places more importance on arriving at stops on time than on minimizing drive times. Organizations that make time-critical deliveries or that are very concerned with customer service would choose High.

• Medium - This is the default value. Balances the importance of minimizing drive times and arriving within time windows.

• Low - Places more importance on minimizing drive times and less on arriving at stops on time. You may want to use this setting if you have a growing backlog of service requests. For the purpose of servicing more orders in a day and reducing the backlog, you can choose Low even though customers might be inconvenienced with your late arrivals.

The default value is ‘Medium’.

spatially_cluster_routes

Optional boolean.

CLUSTER (True) - Dynamic seed points are automatically created for all routes and the orders assigned to an individual route are spatially clustered. Clustering orders tends to keep routes in smaller areas and reduce how often different route lines intersect one another; yet, clustering also tends to increase overall travel times.

NO_CLUSTER (False) - Dynamic seed points aren’t created. Choose this option if route zones are specified.

The default value is ‘True’.

route_zones

Optional FeatureSet. Delineates work territories for given routes. A route zone is a polygon feature and is used to constrain routes to servicing only those orders that fall within or near the specified area. Here are some examples of when route zones may be useful:

• Some of your employees don’t have the required permits to perform work in certain states or communities. You can create a hard route zone so they only visit orders in areas where they meet the requirements.

• One of your vehicles breaks down frequently so you want to minimize response time by having it only visit orders that are close to your maintenance garage. You can create a soft or hard route zone to keep the vehicle nearby.

When specifying the route zones, you need to set properties for each one, such as its associated route, by using attributes. The route zones can be specified with the following attributes:

• RouteName: The name of the route to which this zone applies. A route zone can have a maximum of one associated route. This field can’t contain null values, and it is a foreign key to the Name field in the feature in the routes parameter.

• IsHardZone: A Boolean value indicating a hard or soft route zone. A True value indicates that the route zone is hard; that is, an order that falls outside the route zone polygon can’t be assigned to the route. The default value is 1 (True). A False value (0) indicates that such orders can still be assigned, but the cost of servicing the order is weighted by a function that is based on the Euclidean distance from the route zone. Basically, this means that as the straight-line distance from the soft zone to the order increases, the likelihood of the order being assigned to the route decreases.

route_renewals

Optional FeatureSet. Specifies the intermediate depots that routes can visit to reload or unload the cargo they are delivering or picking up. Specifically, a route renewal links a route to a depot. The relationship indicates the route can renew (reload or unload while en route) at the associated depot.

Route renewals can be used to model scenarios in which a vehicle picks up a full load of deliveries at the starting depot, services the orders, returns to the depot to renew its load of deliveries, and continues servicing more orders. For example, in propane gas delivery, the vehicle may make several deliveries until its tank is nearly or completely depleted, visit a refueling point, and make more deliveries.

Here are a few rules and options to consider when also working with route seed points:

• The reload/unload point, or renewal location, can be different from the start or end depot.

• Each route can have one or many predetermined renewal locations.

• A renewal location may be used more than once by a single route.

• In some cases where there may be several potential renewal locations for a route, the closest available renewal location is chosen by the solver.

When specifying the route renewals, you need to set properties for each one, such as the name of the depot where the route renewal can occur, by using attributes. The route renewals can be specified with the following attributes: * ObjectID: The system-managed ID field. * DepotName: The name of the depot where this renewal takes place. This

field can’t contain a null value and is a foreign key to the Name field in the depots parameter.

• RouteName: The name of the route to which this renewal applies. This field can’t contain a null value and is a foreign key to the Name field in the routes parameter.

• ServiceTime: The service time for the renewal. This field can contain a null value; a null value indicates zero service time. The unit for this field value is specified by the time_units parameter. The time taken to load a vehicle at a renewal depot may depend on the size of the vehicle and how full or empty the vehicle is. However, the service time for a route renewal is a fixed value and does not take into account the actual load. As such, the renewal service time should be given a value corresponding to a full truckload, an average truckload, or another time estimate of your choice.

order_pairs

Optional FeatureSet. This parameter pairs pickup and delivery orders so they are serviced by the same route.

Sometimes it is required that the pickup and delivery for orders be paired. For example, a courier company might need to have a route pick up a high-priority package from one order and deliver it to another without returning to a depot, or sorting station, to minimize delivery time. These related orders can be assigned to the same route with the appropriate sequence by using order pairs. Moreover, restrictions on how long the package can stay in the vehicle can also be assigned; for example, the package might be a blood sample that has to be transported from the doctor’s office to the lab within two hours. When specifying the order pairs, you need to set properties for each one, such as the names of the two orders, by using attributes. The order pairs can be specified with the following attributes: * ObjectID: The system-managed ID field. * FirstOrderName: The name of the first order of the pair. This field is a

foreign key to the Name field in the orders parameter. SecondOrderName: The name of the second order of the pair. This field is a foreign key to the name field in the orders parameter.

The first order in the pair must be a pickup order; that is, the value for its DeliveryQuantities field is null. The second order in the pair must be a delivery order; that is, the value for its PickupQuantities field is null. The quantity picked up at the first order must agree with the quantity delivered at the second order. As a special case, both orders may have zero quantities for scenarios where capacities are not used.

• MaxTransitTime: The maximum transit time for the pair. The transit time is the duration from the departure time of the first order to the arrival time at the second order. This constraint limits the time-on-vehicle, or ride time, between the two orders. When a vehicle is carrying people or perishable goods, the ride time is typically shorter than that of a vehicle carrying packages or nonperishable goods. This field can contain null values; a null value indicates that there is no constraint on the ride time. The unit for this field value is specified by the time_units parameter. Excess transit time (measured with respect to the direct travel time between order pairs) can be tracked and weighted by the solver. Because of this, you can direct the VRP solver to take one of three approaches:

• Minimize the overall excess transit time, regardless of the increase in travel cost for the fleet.

• Find a solution that balances overall violation time and travel cost.

• Ignore the overall excess transit time and, instead, minimize the travel cost for the fleet.

By assigning an importance level for the excess_transit_factor parameter, you are in effect choosing one of these three approaches. Regardless of the importance level, the solver will always return an error if the MaxTransitTime value is surpassed.

excess_transit_factor

Optional string. Rates the importance of reducing excess transit time of order pairs. Excess transit time is the amount of time exceeding the time required to travel directly between the paired orders. Excess time can be caused by driver breaks or travel to intermediate orders and depots. Listed below are the three values you can choose from.

Choice list:[‘High’, ‘Medium’, ‘Low’]

• High - The solver tries to find a solution with the least excess transit time between paired orders at the expense of increasing the overall travel costs. It makes sense to use this setting if you are transporting people between paired orders and you want to shorten their ride time. This is characteristic of taxi services.

• Medium - This is the default setting. The solver looks for a balance between reducing excess transit time and reducing the overall solution cost.

• Low - The solver tries to find a solution that minimizes overall solution cost, regardless of excess transit time. This setting is commonly used with courier services. Since couriers transport packages as opposed to people, they don’t need to worry about ride time. Using Low allows the couriers to service paired orders in the proper sequence and minimize the overall solution cost.

The default value is ‘Medium’.

point_barriers

Optional FeatureSet. Specify one or more points to 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 time delay spent at a railroad crossing.

The tool imposes a limit of 250 points that can be added as barriers. When specifying the point barriers, you can set properties for each one, such as its name or barrier type, by using attributes. The point barriers can be specified with 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 or Additional_Distance field. This barrier type is referred to as an added-cost point barrier.

• Additional_Time: Indicates how much travel time is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the measurement units are time based. 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: Indicates how much distance is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the measurement units are distance based. 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: Indicates how much cost is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the travel mode used for the analysis uses an impedance attribute that is neither time-based or distance-based.

• FullEdge: Specify 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.

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

The CurbApproach property was designed to work with both kinds 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, you would choose Right side of vehicle (1) in the United States but Left side of vehicle (2) 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 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 ArcGIS Network Analyst extension 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 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 time 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 time units of NavLatency are the same as the units specified by the timeUnits property of the analysis object.

line_barriers

Optional FeatureSet. 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 on 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 a name property for each one by using the following attribute:

• Name: The name of the barrier.

polygon_barriers

Optional FeatureSet. 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 on the number of polygons you can specify as the polygon barriers, the combined number of streets intersected by all the polygons should not exceed 2,000. When specifying the polygon barriers, you can set properties for each one, such as its name or barrier type, by using attributes. The polygon barriers can be specified with the following attributes:

• Name: The name of the barrier.

• BarrierType: Specifies whether the barrier restricts travel completely or scales the 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 time or distance required to travel the underlying streets by a factor specified using the ScaledTimeFactor or ScaledDistanceFactor fields. If the streets are partially covered by the barrier, the travel time or distance is apportioned and then scaled. For example, a factor 0.25 would mean that travel on underlying streets is expected to be four times faster than normal. A factor of 3.0 would mean 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 might be used to model storms that reduce travel speeds in specific regions.

• ScaledTimeFactor: This is the factor by which the travel time of the streets intersected by the barrier is multiplied. This field is applicable only for scaled-cost barriers and only if the measurement units are time based. The field value must be greater than zero.

• ScaledDistanceFactor: This is the factor by which the distance of the streets intersected by the barrier is multiplied. This attribute is applicable only for scaled-cost barriers and only if the measurement units are distance based. The attribute value must be greater than zero.

use_hierarchy_in_analysis

Optional boolean. Specify whether hierarchy should be used when finding the best routes.

Checked (True) - Use hierarchy when finding routes. When hierarchy is used, the tool prefers higher-order streets, such as freeways, to 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 true when finding routes to faraway locations, 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 has to select the best route from a relatively smaller subset of streets.

Unchecked (False) - Do not use hierarchy when finding routes. If hierarchy is not used, the tool considers all the streets and doesn’t prefer higher-order streets when finding the route. This is often used when finding short-distance routes within a city.

The tool automatically reverts to using hierarchy if the straight-line distance between orders, depots, or orders and depots is greater than 50 miles, even if you have set this parameter to not use hierarchy. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value.

restrictions

Optional string. Specify which restrictions should be honored by the tool when finding the best routes. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value. A restriction represents a driving preference or requirement. In most cases, restrictions cause roads to be prohibited. For instance, using an Avoid Toll Roads restriction will result in a route that will include roads only when it is absolutely required to travel on toll roads in order 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 as illegal to do so.

Below is a list of available restrictions and a short description. Some restrictions require an additional value to be specified for their desired use. This value needs to 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 under 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.

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 check whether the restriction is available in a particular country by looking at the table in the Country List section of the Data coverage for network analysis services web page. 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 whose Restriction Usage parameter value is between 0 and 1 (see the Attribute Parameter Value parameter). It prohibits all restrictions whose Restriction Usage parameter value is greater than 0.

Choice list:[‘Any Hazmat Prohibited’, ‘Avoid Carpool Roads’, ‘Avoid Express Lanes’, ‘Avoid Ferries’, ‘Avoid Gates’, ‘Avoid Limited Access Roads’, ‘Avoid Private Roads’, ‘Avoid Roads Unsuitable for Pedestrians’, ‘Avoid Stairways’, ‘Avoid Toll Roads’, ‘Avoid Toll Roads for Trucks’, ‘Avoid Truck Restricted Roads’, ‘Avoid Unpaved Roads’, ‘Axle Count Restriction’, ‘Driving a Bus’, ‘Driving a Delivery Vehicle’, ‘Driving a Taxi’, ‘Driving a Truck’, ‘Driving an Automobile’, ‘Driving an Emergency Vehicle’, ‘Height Restriction’, ‘Kingpin to Rear Axle Length Restriction’, ‘Length Restriction’, ‘Preferred for Pedestrians’, ‘Riding a Motorcycle’, ‘Roads Under Construction Prohibited’, ‘Semi or Tractor with One or More Trailers Prohibited’, ‘Single Axle Vehicles Prohibited’, ‘Tandem Axle Vehicles Prohibited’, ‘Through Traffic Prohibited’, ‘Truck with Trailers Restriction’, ‘Use Preferred Hazmat Routes’, ‘Use Preferred Truck Routes’, ‘Walking’, ‘Weight Restriction’, ‘Weight per Axle Restriction’, ‘Width Restriction’]

The service supports the restriction names listed in the following table:

attribute_parameter_values

Optional FeatureSet. Specify additional values required by some restrictions, such as the weight of a vehicle for Weight Restriction. You can also use the attribute parameter to specify whether any restriction prohibits, avoids, or prefers travel on roads that use the restriction. 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 even highly prefer them. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value. If you specify the Attribute Parameter Values parameter from a feature class, the field names on the feature class must match the fields as described below:

• AttributeName: Lists the name of the restriction.

• ParameterName: Lists 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.

Attribute Parameter Values 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 and 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 within the parentheses:

• PROHIBITED (-1) - Travel on the roads using the restriction is completely prohibited.

• AVOID_HIGH (5) - It is highly unlikely for the tool to include in the route the roads that are associated with the restriction.

• AVOID_MEDIUM (2) - It is unlikely for the tool to include in the route the roads that are associated with the restriction.

• AVOID_LOW (1.3) - It is somewhat unlikely for the tool to include in the route the roads that are associated with the restriction.

• PREFER_LOW (0.8) - It is somewhat likely for the tool to include in the route the roads that are associated with the restriction.

• PREFER_MEDIUM (0.5) - It is likely for the tool to include in the route the roads that are associated with the restriction.

• PREFER_HIGH (0.2) - It is highly likely for the tool to include in the route the roads that are associated with the restriction.

In most cases, you can use the default value, PROHIBITED, for the Restriction Usage if the restriction is dependent on a vehicle-characteristic such as vehicle height. However, in some cases, the value for Restriction Usage depends on your routing preferences. For example, the Avoid Toll Roads restriction has the default value of AVOID_MEDIUM for the Restriction Usage parameter. 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 would put lower importance on avoiding tolls; choosing AVOID_HIGH instead would give it a higher importance and thus make it more acceptable for the service to generate longer routes to avoid tolls. Choosing PROHIBITED would entirely disallow 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, you would 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.

 AttributeName ParameterName ParameterValue Any Hazmat Prohibited Restriction Usage PROHIBITED Avoid Carpool Roads Restriction Usage PROHIBITED Avoid Express Lanes Restriction Usage PROHIBITED Avoid Ferries Restriction Usage AVOID_MEDIUM Avoid Gates Restriction Usage AVOID_MEDIUM Avoid Limited Access Roads Restriction Usage AVOID_MEDIUM Avoid Private Roads Restriction Usage AVOID_MEDIUM Avoid Roads Unsuitable for Pedestrians Restriction Usage AVOID_HIGH Avoid Stairways Restriction Usage AVOID_HIGH Avoid Toll Roads Restriction Usage AVOID_MEDIUM Avoid Toll Roads for Trucks Restriction Usage AVOID_MEDIUM Avoid Truck Restricted Roads Restriction Usage AVOID_HIGH Avoid Unpaved Roads Restriction Usage AVOID_HIGH Axle Count Restriction Number of Axles Restriction Usage 0 PROHIBITED Driving a Bus Restriction Usage PROHIBITED Driving a Taxi Restriction Usage PROHIBITED Driving a Truck Restriction Usage PROHIBITED Driving an Automobile Restriction Usage PROHIBITED Driving an Emergency Vehicle Restriction Usage PROHIBITED Height Restriction Restriction Usage Vehicle Height (meters) PROHIBITED 0 Kingpin to Rear Axle Restriction Usage PROHIBITED Length Restriction Vehicle Kingpin to Rear Axle Length (meters) 0 Length Restriction Restriction Usage Vehicle Length (meters) PROHIBITED 0 Preferred for Pedestrians Restriction Usage PREFER_LOW Riding a Motorcycle Restriction Usage PROHIBITED Roads Under Construction Prohibited Restriction Usage PROHIBITED Semi or Tractor with One Restriction Usage PROHIBITED or more trailers prohibited Single Axle Vehicles Prohibited Restriction Usage PROHIBITED Tandem Axle Vehicles Prohibited Restriction Usage PROHIBITED Through Traffic Prohibited Restriction Usage AVOID_HIGH Truck with Trailers Restriction Restriction Usage Number of Trailers on Truck PROHIBITED 0 Use Preferred Hazmat Routes Restriction Usage PREFER_MEDIUM Use Preferred Truck Routes Restriction Usage PREFER_HIGH Walking Restriction Usage PROHIBITED WalkTime Walking Speed (km/h) 5 Weight Restriction Restriction Usage Vehicle Weight (kilograms) PROHIBITED 0 Weight per Axle Restriction Restriction Usage Vehicle Weight per Axle (kilograms) PROHIBITED 0 Width Restriction Restriction Usage Vehicle Width (meters) PROHIBITED 0

populate_route_lines

Optional boolean.

Checked (True) - The output routes will have the exact shape of the underlying streets.

Unchecked (False) - No shape is generated for the output routes, yet the routes will still contain tabular information about the solution. You won’t be able to generate driving directions if route lines aren’t created.

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

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

route_line_simplifi cation_tolerance

Optional LinearUnit. Specify by how much you want to simplify the geometry of the output lines for routes and directions. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value. The tool also ignores this parameter if the populate_route_lines parameter is unchecked (False). 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.

populate_directions

Optional boolean. Specify whether the tool should generate driving directions for each route. Checked (True): Indicates that the directions will be generated and configured based on the values for the Directions Language, Directions Style Name, and Directions Distance Units parameters. Unchecked (False): Directions are not generated, and the tool returns an empty Directions layer.

directions_language

Optional string. Specify the language that should be used when generating driving directions. This parameter is used only when the populate_directions parameter is checked, or set to True. The parameter value can be specified using one of the following two- or five-character language codes: ar-Arabic cs-Czech de-German el-Greek en-English es-Spanish et-Estonian fr-French he-Hebrew it-Italian ja-Japanese ko-Korean lt-Lithuanian lv-Latvian nl-Dutch pl-Polish pt-BR-Brazilian Portuguese pt-PT-European Portuguese ru-Russian sv-Swedish th-Thai tr-Turkish zh-CN-Simplified Chinese

If an unsupported language code is specified, the tool returns the directions using the default language, English.

directions_style_name

Optional string. Specify the name of the formatting style for the directions. This parameter is used only when the Populate Directions parameter is checked, or set to True. The parameter can be specified using the following values:

NA Desktop: Generates turn-by-turn directions suitable for printing. NA Navigation: Generates turn-by-turn directions designed for an in-vehicle navigation device.

travel_mode

Optional string. Specify 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 better reflect your organization’s workflows. You need to specify the name of a travel mode supported by your organization.

To get a list of supported travel mode names, run the GetTravelModes tool from the Utilities toolbox available under the same GIS Server connection you used to access the tool. The GetTravelModes 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 Travel Mode Settings field as input. This speeds up the tool execution as the tool does not have to lookup 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 travelling by car. You may want to 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 may choose to do this to try out different settings to get desired analysis results. Once you have identified the analysis settings, you should work with your organization’s administrator and save these settings as part of new or existing travel mode so that everyone in your organization can rerun the analysis with the same settings.

impedance

Optional string. Specify 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 taking one minute to travel a mile along an empty road is an example of impedance. 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. Choose from the following impedance values: Drive Time-Models travel times for a car. These travel times are static for each road and don’t fluctuate with traffic. Truck Time-Models travel times for a truck. These travel times are static for each road and don’t fluctuate with traffic. Walk Time-Models travel times for a pedestrian. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value.

Choice list:[‘Drive Time’, ‘Truck Time’, ‘Walk Time’]

The default value is ‘Drive Time’.

gis

Optional GIS. The GIS on which this tool runs. If not specified, the active GIS is used.

time_zone_usage_ for_time_fields

Optional string. Specifies the time zone for the input date-time fields supported by the tool. This parameter specifies the time zone for the following fields: TimeWindowStart1, TimeWindowEnd1, TimeWindowStart2, TimeWindowEnd2, InboundArriveTime, and OutboundDepartTime on orders. TimeWindowStart1, TimeWindowEnd1, TimeWindowStart2, and TimeWindowEnd2 on depots. EarliestStartTime and LatestStartTime on routes. TimeWindowStart and TimeWindowEnd on breaks.

Choice list:[‘UTC’, ‘GEO_LOCAL’]

GEO_LOCAL: The date-time values associated with the orders or depots are in the time zone in which the orders and depots are located. For routes, the date-time values are based on the time zone in which the starting depot for the route is located. If a route does not have a starting depot, all orders and depots across all the routes must be in a single time zone. For breaks, the date-time values are based on the time zone of the routes. For example, if your depot is located in an area that follows eastern standard time and has the first time window values (specified as TimeWindowStart1 and TimeWindowEnd1) of 8 AM and 5 PM, the time window values will be treated as 8:00 a.m. and 5:00 p.m. eastern standard time.

UTC: The date-time values associated with the orders or depots are in the in coordinated universal time (UTC) and are not based on the time zone in which the orders or depots are located. For example, if your depot is located in an area that follows eastern standard time and has the first time window values (specified as TimeWindowStart1 and TimeWindowEnd1) of 8 AM and 5 PM, the time window values will be treated as 12:00 p.m. and 9:00 p.m. eastern standard time assuming the eastern standard time is obeying the daylight saving time. Specifying the date-time values in UTC is useful if you do not know the time zone in which the orders or depots are located or when you have orders and depots in multiple time zones, and you want all the date-time values to start simultaneously. The UTC option is applicable only when your network dataset defines a time zone attribute. Otherwise, all the date-time values are always treated as GEO_LOCAL.

save_output_layer

Optional boolean. Specify if the tool should save the analysis settings as a network analysis layer file. You cannot directly work with this file even when you open the file in an ArcGIS Desktop application like ArcMap. It is meant to be sent to Esri Technical Support to diagnose the quality of results returned from the tool. True: Save the network analysis layer file. The file is downloaded in 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 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 Network Analysis Layer parameter in the entry corresponding to the tool execution in the Geoprocessing Results window. False: Do not save the network analysis layer file. This is the default.

overrides

Optional string. Specify additional settings that can influence the behavior of the solver when finding solutions for the network analysis problems. The value for this parameter needs to be specified in dict. For example, a valid value is of the following form {“overrideSetting1” : “value1”, “overrideSetting2” : “value2”}. The override setting name is always enclosed in double quotes. 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. A list of supported override settings for each solver and their acceptable values can be obtained by contacting Esri Technical Support.

save_route_data

Optional boolean. Choose whether the output includes a zip file that contains a file geodatabase holding 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. True: Save the route data as a zip file. The file is downloaded in 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 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 Route Data parameter in the entry corresponding to the tool execution in the Geoprocessing Results window. False: Do not save the route data. This is the default.

time_impedance

Optional string. Specify the time-based impedance.

distance_impedence

Optional string. Specify the distance-based impedance.

populate_stop_shapes

Optional boolean. Specify if the tool should create the shapes for the output assigned and unassigned stops.

output_format

Optional. Specify the format in which the output features are created.

Choose from the following formats:
• Feature Set - The output features are returned as feature classes and tables. This is the default.

• JSON File - The output features are 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 File - The output features are 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.

future

Optional boolean. If True, a GPJob is returned instead of results. The GPJob can be queried on the status of the execution.

ignore_invalid_order_locations

Specifies whether invalid orders will be ignored when solving the vehicle routing problem.

True - The solve operation will ignore any invalid orders and return a solution, given it didn’t encounter any other errors. If you need to generate routes and deliver them to drivers immediately, you may be able to ignore invalid orders, solve, and distribute the routes to your drivers. Next, resolve any invalid orders from the last solve and include them in the VRP analysis for the next workday or work shift. False - The solve operation will fail when any invalid orders are encountered. An invalid order is an order that the VRP solver can’t reach. An order may be unreachable for a variety of reasons, including if it’s located on a prohibited network element, it isn’t located on the network at all, or it’s located on a disconnected portion of the network.

: returns: the following as a named tuple:
• out_unassigned_stops - Output Unassigned Stops as a FeatureSet

• out_stops - Output Stops as a FeatureSet

• out_routes - Output Routes as a FeatureSet

• out_directions - Output Directions as a FeatureSet

• solve_succeeded - Solve Succeeded as a bool

• out_network_analysis_layer - Output Network Analysis Layer as a file

• out_route_data - Output Route Data as a file

find_closest_facilities¶

arcgis.network.analysis.find_closest_facilities(incidents: arcgis.features.feature.FeatureSet, facilities: arcgis.features.feature.FeatureSet, measurement_units: str = 'Minutes', analysis_region: str = None, number_of_facilities_to_find: int = 1, cutoff: float = None, travel_direction: str = 'Incident to Facility', use_hierarchy: bool = True, time_of_day: datetime.datetime = None, time_of_day_usage: str = 'Start Time', uturn_at_junctions: str = 'Allowed Only at Intersections and Dead Ends', point_barriers: arcgis.features.feature.FeatureSet = None, line_barriers: arcgis.features.feature.FeatureSet = None, polygon_barriers: arcgis.features.feature.FeatureSet = None, restrictions: str = None, attribute_parameter_values: arcgis.features.feature.FeatureSet = None, route_shape: str = 'True Shape', route_line_simplification_tolerance: arcgis.geoprocessing._types.LinearUnit = None, populate_directions: bool = False, directions_language: str = 'en', directions_distance_units: str = 'Miles', directions_style_name: str = 'NA Desktop', time_zone_for_time_of_day: str = 'Geographically Local', travel_mode: str = 'Custom', impedance: str = 'Drive Time', save_output_network_analysis_layer=False, overrides=None, save_route_data=False, time_impedance='TravelTime', distance_impedance='Kilometers', output_format='Feature Set', gis=None, future=False) → tuple

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.

Argument

Description

incidents

Required FeatureSet. Specify one or more incidents (up to 1,000). These are the locations from which the tool searches for the nearby locations. When specifying the incidents, you can set properties for each one, such as its name or service time, by using attributes. The incidents can be specified with 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 autogenerates 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 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. The default value is 0. If you are finding the closest fire stations from fire incidents to estimate response times, 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 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. The default value is 0. Generally, the location of an incident, such as a home, isn’t exactly on the streets; it is set back somewhat from the road. This attribute value can be used to model the distance between the actual incident location and its location on the street, if it is important to include that distance in the total travel distance.

• 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):

 Setting Description Either side of vehicle The vehicle can approach and depart the order in either direction, so a U-turn is allowed at the order. This setting can be chosen if it is possible and desirable for your vehicle to turn around at the order. This decision may depend on the width of the road and the amount of traffic or whether the order has a parking lot where vehicles can pull in and turn around. right side of vehicle When the vehicle approaches and departs the order, the order must be on the right side of the vehicle. A U-turn is prohibited. This is typically used for vehicles like buses that must arrive with the bus stop on the right side. left side of vehicle When the vehicle approaches and departs the order, the curb must be on the left side of the vehicle. A U-turn is prohibited. This is typically used for vehicles like buses that must arrive with the bus stop on the left-hand side. No U-Turn When the vehicle approaches the order, the curb can be on either side of the vehicle; however, the vehicle must depart without turning around.

The CurbApproach property is designed to work with both kinds 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, you would choose Right side of vehicle (1) in the United States but Left side of vehicle (2) in the United Kingdom.

• Attr_TravelTime: Specifies the amount of time for cars, in minutes, that will be added to the total travel time of the route between the incident and the closest facility. The attribute value can be used to model the time spent at the incident. For example, if you are finding the three closest fire stations from a fire incident, the attribute can store the amount of time spent at the fire incident. This could be the time it takes for firefighters to hook up their equipment and begin fighting the fire. The value for this attribute is included in the total travel time for the route and is also displayed in driving directions as service time. A zero or null value indicates that the incident requires no service time. The default value is 0.

• Attr_TruckTravelTime: Specifies the amount of time for trucks, in minutes, that will be added to the total travel time of the route between the incident and the closest facility. The attribute value can be used to model the time spent at the incident. The value for this attribute is included in the total travel time for the route and is also displayed in driving directions as service time. A zero or null value indicates that the incident requires no service time. The default value is 0.

• Attr_WalkTime: Specifies the amount of time for pedestrians, in minutes, that will be added to the total travel time of the route between the incident and the closest facility. The attribute value can be used to model the time spent at the incident. The value for this attribute is included in the total travel time for the route and is also displayed in walking directions as service time. A zero or null value indicates that the incident requires no service time. The default value is 0.

• Attr_Miles: Specifies the distance in miles that will be added to the total distance of the route between the incident and the closest facility. Generally the locations of the incidents are not exactly on the streets but are set back somewhat from the road. This attribute value can be used to model the distance between the actual incident location and its location on the street if it is important to include that distance in the total travel distance. The default value is 0.

• Attr_Kilometers: Specifies the distance in kilometers that will added to the total distance of the route between the incident and the closest facility. Generally the locations of the incidents are not exactly on the streets but are set back somewhat from the road. This attribute value can be used to model the distance between the actual incident location and its location on the street if it is important to include that distance in the total travel distance. The default value is 0.

• Cutoff_TravelTime: Specify the travel time for cars, in minutes, at which to stop searching for facilities for a given incident. Any incident beyond the cutoff value will not be searched. If Cutoff_TravelTime is not set for an incident, the service will use the value specified as the defaultCutoff parameter. The value for the Cutoff_TravelTime attribute allows the ability to overwrite the defaultCutoff value on a per incident basis. The default value for this attribute is null which indicates not to use any cutoff.

• Cutoff_TruckTravelTime: Specify the travel time for trucks, in minutes, at which to stop searching for facilities for a given incident. Any incident beyond the cutoff value will not be searched. If Cutoff_TruckTravelTime is not set for an incident, the service will use the value specified as the defaultCutoff parameter. The value for the Cutoff_TruckTravelTime attribute allows the ability to overwrite the defaultCutoff value on a per incident basis. The default value for this attribute is null which indicates not to use any cutoff.

• Cutoff_WalkTime: Specify the travel time for pedestrians, in minutes, at which to stop searching for facilities for a given incident. Any incident beyond the cutoff value will not be searched. If Cutoff_WalkTime is not set for an incident, the service will use the value specified as the defaultCutoff parameter. The value for the Cutoff_WalkTime attribute allows the ability to overwrite the defaultCutoff value on a per incident basis. The default value for this attribute is null which indicates not to use any cutoff.

• Cutoff_Miles: Specify the travel distance in miles at which to stop searching for facilities for a given incident. Any incident beyond the cutoff value will not be searched. If Cutoff_Miles is not set for an incident, the service will use the value specified as the defaultCutoff parameter. The value for the Cutoff_Miles attribute allows the ability to overwrite the defaultCutoff value on a per incident basis. The default value for this attribute is null which indicates not to use any cutoff.

• Cutoff_Kilometers: Specify the travel distance in kilometers at which to stop searching for facilities for a given incident. Any incident beyond the cutoff value will not be searched. If Cutoff_Kilometers is not set for an incident, the service will use the value specified as the defaultCutoff parameter. The value for the Cutoff_Kilometers attribute allows the ability to overwrite the defaultCutoff value on a per incident basis. The default value for this attribute is null which indicates not to use any cutoff.

• TargetFacilityCount: Specify the number of facilities that need to be found for the incident. If TargetFacilityCount is not set for an incident, the service will use the value specified as the defaultTargetFacilityCount parameter. The value for the TargetFacilityCount attribute allows the ability to overwrite the defaultTargetFacilityCount value on a per incident basis. The default value for this attribute is null which causes the service to use the value set for the defaultTargetFacilityCount parameter. If the TargetFacilityCount attribute is set to a value other than null, the defaultTargetFacilityCount value is overwritten.

• Bearing: Specify the direction the vehicle or person is moving in. Bearing is measured clockwise from true north and must be in degrees. Typically, values are between 0 and 360; however, negative values are interpreted by subtracting them from 360 degrees.

• BearingTol: Short for bearing tolerance, this field specifies the maximum acceptable difference between the heading of a vehicle and a tangent line from the point on a street where Network Analyst attempts to locate the vehicle. The bearing tolerance is used to determine whether the direction in which a vehicle is moving generally aligns with the underlying road. If they align within the given tolerance, the vehicle is located on that edge; if not, the next nearest eligible edge is evaluated.

facilities

Required FeatureSet. Specify one or more facilities (up to 1,000). These are the locations that are searched for when finding the closest location. mWhen specifying the facilities, you can set properties for each one, such as its name or service time, by using attributes. The facilities can be specified with 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 (as the FacilityID field) 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 autogenerates 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 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. The default value is 0. If you are finding the closest fire stations to fire incidents, AdditionalTime can store the time it tends to 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 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. The default value is 0. Generally the location of a facility, such as a fire station, isn’t exactly on a street; it is set back somewhat from the road. AdditionalDistance can model the distance between the actual facility location and its location on the street, if it is important to include that distance in the total travel distance.

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

 Setting Description Either side of vehicle The vehicle can approach and depart the order in either direction, so a U-turn is allowed at the order. This setting can be chosen if it is possible and desirable for your vehicle to turn around at the order. This decision may depend on the width of the road and the amount of traffic or whether the order has a parking lot where vehicles can pull in and turn around. right side of vehicle When the vehicle approaches and departs the order, the order must be on the right side of the vehicle. A U-turn is prohibited. This is typically used for vehicles like buses that must arrive with the bus stop on the right side. left side of vehicle When the vehicle approaches and departs the order, the curb must be on the left side of the vehicle. A U-turn is prohibited. This is typically used for vehicles like buses that must arrive with the bus stop on the left-hand side. No U-Turn When the vehicle approaches the order, the curb can be on either side of the vehicle; however, the vehicle must depart without turning around.

The CurbApproach property was designed to work with both kinds 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, you would choose Right side of vehicle (1) in the United States but Left side of vehicle (2) in the United Kingdom.

• Attr_TravelTime: Specifies the amount of time for cars, in minutes, that will be added to the total travel time of the route between the incident and the closest facility. The attribute value can be used to specify the turnout time for the facility. For example, when finding the three closest fire stations from a fire incident, this attribute can be used to store the time it takes a crew to don the appropriate protective equipment and exit the fire station. The value for this attribute is included in the total travel time for the route and is also displayed in driving directions as service time. A zero or null value indicates that the facility requires no service time. The default value is 0.

• Attr_TruckTravelTime: Specifies the amount of time for trucks, in minutes, that will be added to the total travel time of the route between the incident and the closest facility. The value for this attribute is included in the total travel time for the route and is also displayed in driving directions as service time. A zero or null value indicates that the facility requires no service time. The default value is 0.

• Attr_WalkTime: Specifies the amount of time for pedestrians, in minutes, that will be added to the total travel time of the route between the incident and the closest facility. The value for this attribute is included in the total travel time for the route and is also displayed in walking directions as service time. A zero or null value indicates that the facility requires no service time. The default value is 0.

• Attr_Miles: Specifies the distance in miles that will added to the total distance of the route between the incident and the closest facility. Generally the locations of the facilities are not exactly on the streets but are set back somewhat from the road. This attribute value can be used to model the distance between the actual facility location and its location on the street if it is important to include that distance in the total travel distance. The default value is 0.

• Attr_Kilometers: Specifies the distance in kilometers that will added to the total distance of the route between the incident and the closest facility. Generally the locations of the facilities are not exactly on the streets but are set back somewhat from the road. This attribute value can be used to model the distance between the actual facility location and its location on the street if it is important to include that distance in the total travel distance. The default value is 0.

• Cutoff_TravelTime: Specify the travel time for cars, in minutes, at which to stop searching for facilities for a given incident. Any incident beyond the cutoff value will not be searched. If Cutoff_TravelTime is not set for a facility, the service will use the value specified as the defaultCutoff parameter. The value for the Cutoff_TravelTime attribute allows the ability to overwrite the defaultCutoff value on a per facility basis. The default value for this attribute is null which indicates not to use any cutoff.

• Cutoff_TruckTravelTime: Specify the travel time for trucks, in minutes, at which to stop searching for facilities for a given incident. Any incident beyond the cutoff value will not be searched. If Cutoff_TruckTravelTime is not set for a facility, the service will use the value specified as the defaultCutoff parameter. The value for the Cutoff_TruckTravelTime attribute allows the ability to overwrite the defaultCutoff value on a per facility basis. The default value for this attribute is null which indicates not to use any cutoff.

• Cutoff_WalkTime: Specify the travel time for trucks, in minutes, at which to stop searching for facilities for a given incident. Any incident beyond the cutoff value will not be searched. Cutoff_WalkTime is not set for a facility, the service will use the value specified as the defaultCutoff parameter. The value for the Cutoff_WalkTime attribute allows the ability to overwrite the defaultCutoff value on a per facility basis. The default value for this attribute is null which indicates not to use any cutoff.

• Cutoff_Miles: Specify the travel distance in miles at which to stop searching for facilities for a given incident. Any incident beyond the cutoff value will not be searched. If Cutoff_Miles is not set for a facility, the service will use the value specified as the defaultCutoff parameter. The value for the Cutoff_Miles attribute allows the ability to overwrite the defaultCutoff value on a per facility basis. The default value for this attribute is null which indicates not to use any cutoff.

• Cutoff_Kilometers: Specify the travel distance in kilometers at which to stop searching for facilities for a given incident. Any incident beyond the cutoff value will not be searched. If Cutoff_Kilometers is not set for a facility, the service will use the value specified as the defaultCutoff parameter. The value for the Cutoff_Kilometers attribute allows the ability to overwrite the defaultCutoff value on a per facility basis. The default value for this attribute is null which indicates not to use any cutoff.

• Bearing: Specify the direction the vehicle or person is moving in. Bearing is measured clockwise from true north and must be in degrees. Typically, values are between 0 and 360; however, negative values are interpreted by subtracting them from 360 degrees.

• BearingTol: Short for bearing tolerance, this field specifies the maximum acceptable difference between the heading of a vehicle and a tangent line from the point on a street where Network Analyst attempts to locate the vehicle. The bearing tolerance is used to determine whether the direction in which a vehicle is moving generally aligns with the underlying road. If they align within the given tolerance, the vehicle is located on that edge; if not, the next nearest eligible edge is evaluated.

measurement_units

Required parameter. Specify the units that should 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 streets. The units you choose 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 in which units the tool will report total driving time or distance in the results.

Choice list:[‘Meters’, ‘Kilometers’, ‘Feet’, ‘Yards’, ‘Miles’, ‘Nautical Miles’, ‘Seconds’, ‘Minutes’, ‘Hours’, ‘Days’]

analysis_region

Optional string. Specify the region in which to perform the analysis. 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 recommended to speed up the tool execution.

Choice list:[‘NorthAmerica’, ‘SouthAmerica’, ‘Europe’, ‘MiddleEastAndAfrica’, ‘India’, ‘SouthAsia’, ‘SouthEastAsia’, ‘Thailand’, ‘Taiwan’, ‘Japan’, ‘Oceania’, ‘Greece’, ‘Korea’]

number_of_facilities_to_find

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

cutoff

Optional float. Specify the travel time or travel distance value at which to stop searching for facilities for a given incident. For instance, while finding the closest hospitals from the site of an accident, a cutoff value of 15 minutes would mean that the tool would 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.

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

travel_direction

Optional string. Specify whether you want to search for the closest facility as measured from the incident to the facility or from the facility to the incident.

• Facility to Incident - Direction of travel is from facilities to incidents.

• Incident to Facility - Direction of travel is from incidents to facilities.

Using one of the parameter values can 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 journey because of different travel time in that direction. If you are setting a value for Time of Day, 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). A retail store (facility) is more concerned with the time it takes the shoppers (incidents) to reach the store; therefore, stores commonly choose Incident to Facility.

Choice list: [‘Incident to Facility’, ‘Facility to Incident’]

use_hierarchy

Optional boolean. Specify whether hierarchy should be used when finding the best route between the facility and the incident.

• Checked (True) - Use hierarchy when finding routes. When hierarchy is used, the tool prefers higher-order streets (such as freeways) to 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 true 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 has to select the best route from a relatively smaller subset of streets.

• Unchecked (False) - Do not use hierarchy when finding routes. If hierarchy is not used, the tool considers all the streets and doesn’t prefer higher-order streets when finding the route. This is often used when 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 you have set this parameter to not use hierarchy.

time_of_day

Optional datetime. Specifies the time and date at which the routes should 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 facilities and the total travel time will be based on traffic conditions.

Specifying a time of day results in more accurate estimation of travel time between the incident and facility 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 facility or incident is located.

time_of_day_usage

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

• Start Time - When this option is chosen, the tool finds the best route considering the Time of Day parameter value as the departure time from the facility or incident.

• End Time - When this option is chosen, the tool considers the Time of Day parameter value as the arrival time at the facility or incident. This option is useful if you want to know what time to depart from a location so you arrive at the destination at the time specified in Time of Day.

Choice list: [‘Start Time’, ‘End Time’]

uturn_at_junctions

Optional string. 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.

Choice list: [‘Allowed’, ‘Not Allowed’, ‘Allowed Only at Dead Ends’, ‘Allowed Only at Intersections and Dead Ends’]

point_barriers

Optional FeatureSet. Specify one or more points to 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 time delay spent at a railroad crossing.

The tool imposes a limit of 250 points that can be added as barriers. When specifying the point barriers, you can set properties for each one, such as its name or barrier type, by using attributes. The point barriers can be specified with 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 or Additional_Distance field. This barrier type is referred to as an added-cost point barrier.

• Additional_Time: Indicates how much travel time is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the measurement units are time based. 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: Indicates how much distance is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the measurement units are distance based. 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.

line_barriers

Optional FeatureSet. 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 on 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 a name property for each one by using the following attribute:

• Name: The name of the barrier.

polygon_barriers

Optional FeatureSet. 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 on the number of polygons you can specify as the polygon barriers, the combined number of streets intersected by all the polygons should not exceed 2,000. When specifying the polygon barriers, you can set properties for each one, such as its name or barrier type, by using attributes. The polygon barriers can be specified with the following attributes:

• Name: The name of the barrier.

• BarrierType: Specifies whether the barrier restricts travel completely or scales the 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 time or distance required to travel the underlying streets by a factor specified using the ScaledTimeFactor or ScaledDistanceFactor fields. If the streets are partially covered by the barrier, the travel time or distance is apportioned and then scaled. For example, a factor 0.25 would mean that travel on underlying streets is expected to be four times faster than normal. A factor of 3.0 would mean 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 might be used to model storms that reduce travel speeds in specific regions.

• ScaledTimeFactor: This is the factor by which the travel time of the streets intersected by the barrier is multiplied. This field is applicable only for scaled-cost barriers and only if the measurement units are time based. The field value must be greater than zero.

• ScaledDistanceFactor: This is the factor by which the distance of the streets intersected by the barrier is multiplied. This attribute is applicable only for scaled-cost barriers and only if the measurement units are distance based. The attribute value must be greater than zero.

restrictions

Optional string. Specify which restrictions should be honored by the tool when finding the best routes between incidents and facilities. A restriction represents a driving preference or requirement. In most cases, restrictions cause roads to be prohibited, but they can also cause them to be avoided or preferred. For instance, using an Avoid Toll Roads restriction will result in a route that will include toll roads only when it is absolutely required to travel on toll roads in order 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 as illegal to do so. Below is a list of available restrictions and a short description. Some restrictions require an additional value to be specified for their desired use. This value needs to 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 under 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. 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 check whether the restriction is available in a particular country by looking at the table in the Country List section of the Data coverage for network analysis services web page. 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 whose Restriction Usage parameter value is between 0 and 1 (see the Attribute Parameter Value parameter). It prohibits all restrictions whose Restriction Usage parameter value is greater than 0. The tool supports the following restrictions:

Choice list:[‘Any Hazmat Prohibited’, ‘Avoid Carpool Roads’, ‘Avoid Express Lanes’, ‘Avoid Ferries’, ‘Avoid Gates’, ‘Avoid Limited Access Roads’, ‘Avoid Private Roads’, ‘Avoid Roads Unsuitable for Pedestrians’, ‘Avoid Stairways’, ‘Avoid Toll Roads’, ‘Avoid Toll Roads for Trucks’, ‘Avoid Truck Restricted Roads’, ‘Avoid Unpaved Roads’, ‘Axle Count Restriction’, ‘Driving a Bus’, ‘Driving a Delivery Vehicle’, ‘Driving a Taxi’, ‘Driving a Truck’, ‘Driving an Automobile’, ‘Driving an Emergency Vehicle’, ‘Height Restriction’, ‘Kingpin to Rear Axle Length Restriction’, ‘Length Restriction’, ‘Preferred for Pedestrians’, ‘Riding a Motorcycle’, ‘Roads Under Construction Prohibited’, ‘Semi or Tractor with One or More Trailers Prohibited’, ‘Single Axle Vehicles Prohibited’, ‘Tandem Axle Vehicles Prohibited’, ‘Through Traffic Prohibited’, ‘Truck with Trailers Restriction’, ‘Use Preferred Hazmat Routes’, ‘Use Preferred Truck Routes’, ‘Walking’, ‘Weight Restriction’, ‘Weight per Axle Restriction’, ‘Width Restriction’]

attribute_parameter_values

Optional FeatureSet. Specify additional values required by some restrictions, such as the weight of a vehicle for Weight Restriction. You can also use the attribute parameter to specify whether any restriction prohibits, avoids, or prefers travel on roads that use the restriction. 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 even highly prefer them. 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 described below:

• AttributeName: Lists the name of the restriction.

• ParameterName: Lists 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.

Attribute Parameter Values 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 and 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 within the parentheses:

PROHIBITED (-1)-Travel on the roads using the restriction is completely prohibited.

AVOID_HIGH (5) - It is highly unlikely for the tool to include in the route the roads that are associated with the restriction.

AVOID_MEDIUM (2) - It is unlikely for the tool to include in the route the roads that are associated with the restriction.

AVOID_LOW (1.3) - It is somewhat unlikely for the tool to include in the route the roads that are associated with the restriction.

PREFER_LOW (0.8) -It is somewhat likely for the tool to include in the route the roads that are associated with the restriction.

PREFER_MEDIUM (0.5) - It is likely for the tool to include in the route the roads that are associated with the restriction.

PREFER_HIGH (0.2) - It is highly likely for the tool to include in the route the roads that are associated with the restriction.

In most cases, you can use the default value, PROHIBITED, for the Restriction Usage if the restriction is dependent on a vehicle-characteristic such as vehicle height. However, in some cases, the value for Restriction Usage depends on your routing preferences. For example, the Avoid Toll Roads restriction has the default value of AVOID_MEDIUM for the Restriction Usage parameter. 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 would put lower importance on avoiding tolls; choosing AVOID_HIGH instead would give it a higher importance and thus make it more acceptable for the service to generate longer routes to avoid tolls. Choosing PROHIBITED would entirely disallow 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, you would 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.

route_shape

Optional string. Specify the type of route features that are output by the tool. The parameter can be specified using one of the following values:

• True Shape - Return the exact shape of the resulting route that is based on the underlying streets.

• Straight Line - Return a straight line between the incident and the facility.

• None - Do not return any shapes for the routes. This value can be useful in cases where you are only interested in determining the total travel time or travel distance between the closest facility and the incident.

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

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 incidents and facilities. This means that only the route shapes are different, not the underlying streets that are searched when finding the route.

Choice list:[‘True Shape’, ‘Straight Line’, ‘None’]

route_line_simplification_tolerance

Optional LinearUnit. Specify by how much you want 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 execution time.

populate_directions

Optional boolean. Specify whether the tool should generate driving directions for each route. Checked (True): Indicates that the directions will be generated and configured based on the values for the Directions Language, Directions Style Name, and Directions Distance Units parameters. Unchecked (False): Directions are not generated, and the tool returns an empty Directions layer.

directions_language

Optional string. Specify the language that should be used when generating driving directions.

This parameter is used only when the Populate Directions parameter is checked, or set to True.

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

Choice list: [‘ar-Arabic’, ‘cs-Czech’, ‘de-German’, ‘el-Greek’, ‘en-English’, ‘es-Spanish’, ‘et-Estonian’, ‘fr-French’, ‘he-Hebrew’, ‘it-Italian’, ‘ja-Japanese’, ‘ko-Korean’, ‘lt-Lithuanian’, ‘lv-Latvian’, ‘nl-Dutch’, ‘pl-Polish’, ‘pt-BR-Brazilian’, ‘Portuguese’, ‘pt-PT-European’, ‘Portuguese’, ‘ru-Russian’, ‘sv-Swedish’, ‘th-Thai’, ‘tr-Turkish’, ‘zh-CN-Simplified’, ‘Chinese’]

If an unsupported language code is specified, the tool returns the directions using the default language, English.

directions_distance_units

Optional string. Specify the units for displaying travel distance in the driving directions. This parameter is used only when the Populate Directions parameter is checked, or set to True. Miles Kilometers Meters Feet Yards NauticalMiles

Choice list: [‘Miles’, ‘Kilometers’, ‘Meters’, ‘Feet’, ‘Yards’, ‘NauticalMiles’]

directions_style_name

Optional string. Specify the name of the formatting style for the directions. This parameter is used only when the Populate Directions parameter is checked, or set to True. The parameter can be specified using the following values:

NA Desktop: Generates turn-by-turn directions suitable for printing. NA Navigation: Generates turn-by-turn directions designed for an in-vehicle navigation device.

Choice list: [‘NA Desktop’, ‘NA Navigation’]

time_zone_for_time_of_day

Optional string. Specifies the time zone of the Time of Day parameter. Geographically Local: The 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. UTC: The 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. Irrespective 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 must be in the same time zone

when: Specifying a start time and traveling from incident to facility. Specifying an end time and traveling from facility to incident.

All facilities must be in the same time zone

when: Specifying a start time and traveling from facility to incident. Specifying an end time and traveling from incident to facility.

Choice list:[‘Geographically Local’, ‘UTC’]

travel_mode

Optional string. Specify 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 better reflect your organization’s workflows. You need to specify the name of a travel mode supported by your organization.

To get a list of supported travel mode names, run the GetTravelModes tool from the Utilities toolbox available under the same GIS Server connection you used to access the tool. The GetTravelModes 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 Travel Mode Settings field as input. This speeds up the tool execution as the tool does not have to lookup 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 travelling by car. You may want to 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 may choose to do this to try out different settings to get desired analysis results. Once you have identified the analysis settings, you should work with your organization’s administrator and save these settings as part of new or existing travel mode so that everyone in your organization can rerun the analysis with the same settings.

impedance

Optional string. Specify 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 distance is 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.) Travel time can also be an impedance; a car may take one 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. Choose from the following impedance values: Drive Time-Models travel times for a car. These travel times are dynamic and fluctuate according to traffic flows in areas where traffic data is available. This is the default value. Truck Time-Models travel times for a truck. These travel times are static for each road and don’t fluctuate with traffic. Walk Time-Models travel times for a pedestrian. Travel Distance-Stores length measurements along roads and paths. To model walk distance, choose this option and ensure Walking is set in the Restriction parameter. Similarly, to model drive or truck distance, choose Travel Distance here and set the appropriate restrictions so your vehicle travels only on roads where it is permitted to do so. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value. If you choose Drive Time, Truck Time, or Walk Time, the Measurement Units parameter must be set to a time-based value; if you choose Travel Distance for Impedance, Measurement Units must be distance-based.

Choice list:[‘Drive Time’, ‘Truck Time’, ‘Walk Time’, ‘Travel Distance’]

gis

Optional, the GIS on which this tool runs. If not specified, the active GIS is used.

..:: Returns the following as a named tuple:

• output_routes - Output Routes as a FeatureSet

• output_directions - Output Directions as a FeatureSet

• solve_succeeded - Solve Succeeded as a bool

• output_closest_facilities - Output Closest Facilities as a FeatureSet

solve_location_allocation¶

arcgis.network.analysis.solve_location_allocation(facilities: arcgis.features.feature.FeatureSet, demand_points: arcgis.features.feature.FeatureSet, measurement_units: str = None, analysis_region: str = None, problem_type: str = None, number_of_facilities_to_find: int = None, default_measurement_cutoff: float = None, default_capacity: float = None, target_market_share: float = None, measurement_transformation_model: str = None, measurement_transformation_factor: float = None, travel_direction: str = None, time_of_day: datetime.datetime = None, time_zone_for_time_of_day: str = None, uturn_at_junctions: str = None, point_barriers: arcgis.features.feature.FeatureSet = None, line_barriers: arcgis.features.feature.FeatureSet = None, polygon_barriers: arcgis.features.feature.FeatureSet = None, use_hierarchy: bool = True, restrictions: str = None, attribute_parameter_values: arcgis.features.feature.FeatureSet = None, allocation_line_shape: str = None, travel_mode: str = None, impedance: str = None, save_output_network_analysis_layer=False, overrides=None, time_impedance=None, distance_impedance=None, output_format=None, gis=None, future=False) → tuple

The solve_location_allocation tool chooses the best location or locations from a set of input locations. Input to this tool includes facilities, which provide goods or services, and demand points, which consume the goods and services. The objective is to find the facilities that supply the demand points most efficiently. The tool solves this problem by analyzing various ways the demand points can be assigned to the different facilities. The solution is the scenario that allocates the most demand to facilities and minimizes overall travel. The output includes the solution facilities, demand points associated with their assigned facilities, and lines connecting demand points to their facilities. The location-allocation tool can be configured to solve specific problem types. Examples include the following: A retail store wants to see which potential store locations would need to be developed to capture 10 percent of the retail market in the area. A fire department wants to determine where it should locate fire stations to reach 90 percent of the community within a four-minute response time. A police department wants to preposition personnel given past criminal activity at night. After a storm, a disaster response agency wants to find the best locations to set up triage facilities, with limited patient capacities, to tend to the affected population.

Argument

Description

facilities

Required FeatureSet. Specify one or more facilities (up to 1,000). The tool chooses the best locations from the set of facilities you specify here. In a competitive analysis, in which you try to find the best locations in the face of competition, the facilities of the competitors are specified here as well. When defining the facilities, you can set properties for each one, such as the facility name or type, by using attributes. Facilities can be specified with the following fields: Name-The name of the facility. The name is included in the name of output allocation lines if the facility is part of the solution.

• FacilityType - Specifies whether the facility is a candidate, required, or competitor facility. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):

• 0 (Candidate) - A facility that may be part of the solution.

• 1 (Required) - A facility that must be part of the solution.

• 2 (Competitor) - A rival facility that potentially removes demand from your facilities. Competitor facilities are specific to the Maximize Market Share and Target Market Share problem types; they are ignored in other problem types. Weight-The relative weighting of the facility, which is used to rate the attractiveness, desirability, or bias of one facility compared to another. For example, a value of 2.0 could capture the preference of customers who prefer, at a ratio of 2 to 1, shopping in one facility over another facility. Factors that potentially affect facility weight include square footage, neighborhood, and age of the building. Weight values other than one are only honored by the maximize market share and target market share problem types; they are ignored in other problem types.

• Capacity - The Capacity field is specific to the Maximize Capacitated Coverage problem type; the other problem types ignore this field. Capacity specifies how much weighted demand the facility is capable of supplying. Excess demand won’t be allocated to a facility even if that demand is within the facility’s default measurement cutoff. Any value assigned to the Capacity field overrides the Default Capacity parameter (Default_Capacity in Python) for the given facility.

• CurbApproach - Specifies the direction a vehicle may arrive at or depart from the facility. 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 facility can be visited from either the right or left side of the vehicle.

• 1 (Right side of vehicle)-Arrive at or depart the facility so that it is on the right side of the vehicle. This is typically used for vehicles such as buses that must arrive with the bus stop on the right-hand side so that passengers can disembark at the curb.

• 2 (Left side of vehicle)-Arrive at or depart the facility so that it is on the left side of the vehicle. When the vehicle approaches and departs the facility, the curb must be on the left side of the vehicle. This is typically used for vehicles such as buses that must arrive with the bus stop on the left-hand side so that passengers can disembark at the curb.

The CurbApproach property 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 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 incident, you would choose Right side of vehicle (1) in the United States but Left side of vehicle (2) in the United Kingdom.

demand_points

Required FeatureSet. Specify one or more demand points (up to 10,000). The tool chooses the best facilities based in large part on how they serve the demand points specified here. When defining the demand points, you can set properties for each one, such as the demand-point name or weight, by using attributes. Demand points can be specified with the following fields: Name-The name of the demand point. The name is included in the name of an output allocation line or lines if the demand point is part of the solution. GroupName-The name of the group the demand point is part of. This property is ignored for the maximize capacitated coverage, target market share, and maximize market share problem types. If demand points share a group name, the solver allocates all members of the group to the same facility. (If constraints, such as a cutoff distance, prevent any of the demand points in the group from reaching the same facility, none of the demand points are allocated.) Weight-The relative weighting of the demand point. A value of 2.0 means the demand point is twice as important as one with a weight of 1.0. If demand points represent households, weight could indicate the number of people in each household. Cutoff_Time-The demand point can’t be allocated to a facility that is beyond the travel time indicated here. This field value overrides the value of the Default Measurement Cutoff parameter. The units for this attribute value are specified by the Measurement Units parameter. The attribute value is referenced during the analysis only when the measurement units are time based. The default value is null, which means there isn’t an override cutoff. Cutoff_Distance-The demand point can’t be allocated to a facility that is beyond the travel distance indicated here. This field value overrides the value of the Default Measurement Cutoff parameter. The units for this attribute value are specified by the Measurement Units parameter. The attribute value is referenced during the analysis only when the measurement units are distance based. The default value is null, which means there isn’t an override cutoff.

• CurbApproach - Specifies the direction a vehicle may arrive at or depart from the demand point. 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 demand point can be visited from either the right or left side of the vehicle.

• 1 (Right side of vehicle)-Arrive at or depart the demand point so that it is on the right side of the vehicle. This is typically used for vehicles such as buses that must arrive with the bus stop on the right-hand side so that passengers can disembark at the curb.

• 2 (Left side of vehicle)-Arrive at or depart the demand point so that it is on the left side of the vehicle. When the vehicle approaches and departs the demand point, the curb must be on the left side of the vehicle. This is typically used for vehicles such as buses that must arrive with the bus stop on the left-hand side so that passengers can disembark at the curb.

The CurbApproach property 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 demand point 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 demand point 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 demand point and not have a lane of traffic between the vehicle and the demand point, you would choose Right side of vehicle (1) in the United States but Left side of vehicle (2) in the United Kingdom.

measurement_units

Required string. Specify the units that should be used to measure the travel times or travel distances between demand points and facilities. The tool chooses the best facilities based on which ones can reach, or be reached by, the most amount of weighted demand with the least amount travel. The output allocation lines report travel distance or travel time in different units, including the units you specify for this parameter.

Choice list: [‘Meters’, ‘Kilometers’, ‘Feet’, ‘Yards’, ‘Miles’, ‘NauticalMiles’, ‘Seconds’, ‘Minutes’, ‘Hours’, ‘Days’]

analysis_region

Optional string. Specify the region in which to perform the analysis. 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 recommended to speed up the tool execution.

Choice list: [‘NorthAmerica’, ‘SouthAmerica’, ‘Europe’, ‘MiddleEastAndAfrica’, ‘India’, ‘SouthAsia’, ‘SouthEastAsia’, ‘Thailand’, ‘Taiwan’, ‘Japan’, ‘Oceania’, ‘Greece’, ‘Korea’]

problem_type

Optional string. Specifies the objective of the location-allocation analysis. The default objective is to minimize impedance.

• Minimize Impedance: This is also known as the P-Median problem type. Facilities are located such that the sum of all weighted travel time or distance between demand points and solution facilities is minimized. (Weighted travel is the amount of demand allocated to a facility multiplied by the travel distance or time to the facility.) This problem type is traditionally used to locate warehouses, because it can reduce the overall transportation costs of delivering goods to outlets. Since Minimize Impedance reduces the overall distance the public needs to travel to reach the chosen facilities, the minimize impedance problem without an impedance cutoff is ordinarily regarded as more equitable than other problem types for locating some public-sector facilities such as libraries, regional airports, museums, department of motor vehicles offices, and health clinics. The following list describes how the minimize impedance problem type handles demand:

• A demand point that cannot reach any facilities, due to setting a cutoff distance or time, is not allocated.

• A demand point that can only reach one facility has all its demand weight allocated to that facility.

• A demand point that can reach two or more facilities has all its demand weight allocated to the nearest facility only.

• Maximize Coverage: Facilities are located such that as much demand as possible is allocated to solution facilities within the impedance cutoff. Maximize Coverage is frequently used to locate fire stations, police stations, and ERS centers, because emergency services are often required to arrive at all demand points within a specified response time. Note that it is important for all organizations, and critical for emergency services, to have accurate and precise data so that analysis results correctly model real-world results. Pizza delivery businesses, as opposed to eat-in pizzerias, try to locate stores where they can cover the most people within a certain drive time. People who order pizzas for delivery don’t typically worry about how far away the pizzeria is; they are mainly concerned with the pizza arriving within an advertised time window. Therefore, a pizza-delivery business would subtract pizza-preparation time from their advertised delivery time and solve a maximize coverage problem to choose the candidate facility that would capture the most potential customers in the coverage area. (Potential customers of eat-in pizzerias are more affected by distance, since they need to travel to the restaurant; thus, the attendance maximizing or market share problem types would better suit eat-in restaurants.) The following list describes how the Maximize Coverage problem handles demand:

• A demand point that cannot reach any facilities due to cutoff distance or time is not allocated.

• A demand point that can only reach one facility has all its demand weight allocated to that facility.

• A demand point that can reach two or more facilities has all its demand weight allocated to the nearest facility only.

• Maximize Capacitated Coverage: Facilities are located such that all or the greatest amount of demand can be served without exceeding the capacity of any facility. Maximize Capacitated Coverage behaves like either the Minimize Impedance or Maximize Coverage problem type but with the added constraint of capacity. You can specify a capacity for an individual facility by assigning a numeric value to its corresponding Capacity field on the input facilities. If the Capacity field value is null, the facility is assigned a capacity from the Default Capacity property. Use-cases for Maximize Capacitated Coverage include creating territories that encompass a given number of people or businesses, locating hospitals or other medical facilities with a limited number of beds or patients who can be treated, or locating warehouses whose inventory isn’t assumed to be unlimited. The following list describes how the Maximize Capacitated Coverage problem handles demand:

• Unlike Maximize Coverage, Maximize Capacitated Coverage doesn’t require a value for the Default Measurement

Cutoff; however, when an cutoff is specified, any demand point outside the cutoff time or distance of all facilities is not allocated. * An allocated demand point has all or none of its demand weight assigned to a facility; that is, demand isn’t apportioned with this problem type. * If the total demand that can reach a facility is greater than the capacity of the facility, only the demand points that maximize total captured demand and minimize total weighted travel are allocated.

Note

You may notice an apparent inefficiency when a demand point is allocated to a facility that isn’t the nearest solution facility. This may occur when demand points have varying weights and when the demand point in question can reach more than one facility. This kind of result indicates the nearest solution facility didn’t have adequate capacity for the weighted demand, or the most efficient solution for the entire problem required one or more local inefficiencies. In either case, the solution is correct.

• Minimize Facilities: Facilities are chosen such that as much weighted demand as possible are allocated to solution facilities within the travel time or distance cutoff; additionally, the number of facilities required to cover demand is minimized. Minimize Facilities is the same as Maximize Coverage but with the exception of the number of facilities to locate, which in this case is determined by the solver. When the cost of building facilities is not a limiting factor, the same kinds of organizations that use Maximize Coverage (emergency response, for instance) use Minimize Facilities so that all possible demand points will be covered. The following list describes how the Minimize Facilities problem handles demand:

• A demand point that cannot reach any facilities due to a cutoff distance or time is not allocated.

• A demand point that can only reach one facility has all its demand weight allocated to that facility.

• A demand point that can reach two or more facilities has all its demand weight allocated to the nearest facility only.

• Maximize Attendance: Facilities are chosen such that as much demand weight as possible is allocated to facilities while assuming the demand weight decreases in relation to the distance between the facility and the demand point. Specialty stores that have little or no competition benefit from this problem type, but it may also be beneficial to general retailers and restaurants that don’t have the data on competitors necessary to perform market share problem types. Some businesses that might benefit from this problem type include coffee shops, fitness centers, dental and medical offices, and electronics stores. Public transit bus stops are often chosen with the help of Maximize Attendance. Maximize Attendance assumes that the farther people have to travel to reach your facility, the less likely they are to use it. This is reflected in how the amount of demand allocated to facilities diminishes with distance. The following list describes how the Maximize Attendance problem handles demand:

• A demand point that cannot reach any facilities due to a cutoff distance or time is not allocated.

• When a demand point can reach a facility, its demand weight is only partially allocated to the facility. The amount allocated decreases as a function of the maximum cutoff distance (or time) and the travel distance (or time) between the facility and the demand point.

• The weight of a demand point that can reach more than one facility is proportionately allocated to the nearest facility only.

• Maximize Market Share: A specific number of facilities are chosen such that the allocated demand is maximized in the presence of competitors. The goal is to capture as much of the total market share as possible with a given number of facilities, which you specify. The total market share is the sum of all demand weight for valid demand points. The market share problem types require the most data because, along with knowing your own facilities’ weight, you also need to know that of your competitors’ facilities. The same types of facilities that use the Maximize Attendance problem type can also use market share problem types given that they have comprehensive information that includes competitor data. Large discount stores typically use Maximize Market Share to locate a finite set of new stores. The market share problem types use a Huff model, which is also known as a gravity model or spatial interaction. The following list describes how the Maximize Market Share problem handles demand:

• A demand point that cannot reach any facilities due to a cutoff distance or time is not allocated.

• A demand point that can only reach one facility has all its demand weight allocated to that facility.

• A demand point that can reach two or more facilities has all its demand weight allocated to them; furthermore, the weight is split among the facilities proportionally to the facilities’ attractiveness (facility weight) and inversely proportional to the distance between the facility and demand point. Given equal facility weights, this means more demand weight is assigned to near facilities than far facilities.

• The total market share, which can be used to calculate the captured market share, is the sum of the weight of all valid demand points.

• Target Market Share: Target Market Share chooses the minimum number of facilities necessary to capture a specific percentage of the total market share in the presence of competitors. The total market share is the sum of all demand weight for valid demand points. You set the percent of the market share you want to reach and let the solver choose the fewest number of facilities necessary to meet that threshold. The market share problem types require the most data because, along with knowing your own facilities’ weight, you also need to know that of your competitors’ facilities. The same types of facilities that use the Maximize Attendance problem type can also use market share problem types given that they have comprehensive information that includes competitor data. Large discount stores typically use the Target Market Share problem type when they want to know how much expansion would be required to reach a certain level of the market share or see what strategy would be needed just to maintain their current market share given the introduction of new competing facilities. The results often represent what stores would like to do if budgets weren’t a concern. In other cases where budget is a concern, stores revert to the Maximize Market Share problem and simply capture as much of the market share as possible with a limited number of facilities. The following list describes how the target market share problem handles demand:

• The total market share, which is used in calculating the captured market share, is the sum of the weight of all valid demand points.

• A demand point that cannot reach any facilities due to a cutoff distance or time is not allocated.

• A demand point that can only reach one facility has all its demand weight allocated to that facility.

• A demand point that can reach two or more facilities has all its demand weight allocated to them; furthermore, the weight is split among the facilities proportionally to the facilities’ attractiveness (facility weight) and inversely proportional to the distance between the facility and demand point. Given equal facility weights, this means more demand weight is assigned to near facilities than far facilities.

Choice list:[‘Maximize Attendance’, ‘Maximize Capacitated Coverage’, ‘Maximize Coverage’, ‘Maximize Market Share’, ‘Minimize Facilities’, ‘Minimize Impedance’, ‘Target Market Share’]

number_of_facilities_to_find

Optional integer. Specify the number of facilities the solver should choose. The default value is 1. The facilities with a FacilityType field value of 1 (Required) are always chosen first. Any excess facilities to choose are picked from candidate facilities, which have a FacilityType field value of 2. Any facilities that have a FacilityType value of 3 (Chosen) before solving are treated as candidate facilities at solve time. If the number of facilities to find is less than the number of required facilities, an error occurs. Number of Facilities to Find is disabled for the Minimize Facilities and Target Market Share problem types since the solver determines the minimum number of facilities needed to meet the objectives.

default_measurement_cutoff

Optional float. Specifies the maximum travel time or distance allowed between a demand point and the facility it is allocated to. If a demand point is outside the cutoff of a facility, it cannot be allocated to that facility. The default value is none, which means the cutoff limit doesn’t apply. The units for this parameter are the same as those specified by the Measurement Units parameter. The travel time or distance cutoff is measured by the shortest path along roads. This property might be used to model the maximum distance that people are willing to travel to visit stores or the maximum time that is permitted for a fire department to reach anyone in the community. Note that demand points have Cutoff_Time and Cutoff_Distance fields, which, if set accordingly, overrides the Default Measurement Cutoff parameter. You might find that people in rural areas are willing to travel up to 10 miles to reach a facility while urbanites are only willing to travel up to two miles. Assuming Measurement Units is set to Miles, you can model this behavior by setting the default measurement cutoff to 10 and the Cutoff_Distance field value of the demand points in urban areas to 2.

default_capacity

Optional float. This property is specific to the Maximize Capacitated Coverage problem type. It is the default capacity assigned to all facilities in the analysis. You can override the default capacity for a facility by specifying a value in the facility’s Capacity field. The default value is 1.

target_market_share

Optional float. This parameter is specific to the Target Market Share problem type. It is the percentage of the total demand weight that you want the chosen and required facilities to capture. The solver chooses the minimum number of facilities needed to capture the target market share specified here. The default value is 10 percent.

measurement_transformation_model

Optional string. This sets the equation for transforming the network cost between facilities and demand points. This property, coupled with the Impedance Parameter, specifies how severely the network impedance between facilities and demand points influences the solver’s choice of facilities. In the following list of transformation options, d refers to demand points and f, facilities. “Impedance” refers to the shortest travel distance or time between two locations. So impedancedf is the shortest-path (time or distance) between demand point d and facility f, and costdf is the transformed travel time or distance between the facility and demand point. Lambda (λ) denotes the impedance parameter. The Measurement Units setting determines whether travel time or distance is analyzed.

• Linear: costdf = λ * impedancedf The transformed

travel time or distance between the facility and the demand point is the same as the time or distance of the shortest path between the two locations. With this option, the impedance parameter (λ) is always set to one. This is the default. * Power: costdf = impedancedfλ The transformed travel time or distance between the facility and the demand point is equal to the time or distance of the shortest path raised to the power specified by the impedance parameter (λ). Use the Power option with a positive impedance parameter to specify higher weight to nearby facilities.

• Exponential: costdf = e(λ * impedancedf) The transformed travel time or distance between the

facility and the demand point is equal to the mathematical constant e raised to the power specified by the shortest-path network impedance multiplied with the impedance parameter (λ). Use the Exponential option with a positive impedance parameter to specify a high weight to nearby facilities.

Choice list: [‘Linear’, ‘Power’, ‘Exponential’]

measurement_transformation_factor

Optional float. Provides a parameter value to the equations specified in the Measurement Transformation Model parameter. The parameter value is ignored when the impedance transformation is of type linear. For power and exponential impedance transformations, the value should be nonzero.

The default value is 1.

travel_direction

Optional string. Specify whether to measure travel times or distances from facilities to demand points or from demand points to facilities. The default value is to measure from facilities to demand points.

• Facility to Demand: Direction of travel is from facilities to demand points. This is the default.

• Demand to Facility: Direction of travel is from demand points to facilities.

Travel times and distances may change based on direction of travel. If going from point A to point B, you may encounter less traffic or have a shorter path, due to one-way streets and turn restrictions, than if you were traveling in the opposite direction. For instance, going from point A to point B may only take 10 minutes, but going the other direction may take 15 minutes. These differing measurements may affect whether demand points can be assigned to certain facilities because of cutoffs or, in problem types where demand is apportioned, affect how much demand is captured. Fire departments commonly measure from facilities to demand points since they are concerned with the time it takes to travel from the fire station to the location of the emergency. A retail store is more concerned with the time it takes shoppers to reach the store; therefore, stores commonly measure from demand points to facilities. Travel Direction also determines the meaning of any start time that is provided. See the Time of Day parameter for more information.

Choice list:[‘Demand to Facility’, ‘Facility to Demand’]

time_of_day

Optional datetime. Specify the time at which travel begins. This property is ignored unless Measurement Units are time based. The default is no time or date. When Time of Day isn’t specified, the solver uses generic speeds-typically those from posted speed limits. Traffic constantly changes in reality, and as it changes, travel times between facilities and demand points also fluctuate. Therefore, indicating different time and date values over several analyses may affect how demand is allocated to facilities and which facilities are chosen in the results. The time of day always indicates a start time. However, travel may start from facilities or demand points; it depends on what you choose for the Travel Direction parameter. 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 demand point is located.

time_zone_for_time_of_day

Optional string. Specifies the time zone of the Time of Day parameter. The default is geographically local.

• Geographically Local: The Time of Day parameter refers to the time zone in which the facilities or demand points are located. If Travel Direction is facilities to demand points, this is the time zone of the facilities. If Travel Direction is demand points to facilities, this is the time zone of the demand points.

• UTC: The Time of Day parameter refers to Coordinated Universal Time (UTC). Choose this option if you want to choose the best location for a specific time, such as now, but aren’t certain in which time zone the facilities or demand points will be located. Irrespective of the Time Zone for Time of Day setting, the following rules are enforced by the tool if your facilities and demand points are in multiple time zones: All facilities must be in the same time zone when specifying a time of day and travel is from facility to demand. All demand points must be in the same time zone when specifying a time of day and travel is from demand to facility.

Choice list:[‘Geographically Local’, ‘UTC’]

uturn_at_junctions

Optional string. 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, the U-turn policy parameter is implicitly specified by how many edges, or streets, 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.

• Allowed: U-turns are permitted at junctions with any number of connected edges, or streets. This is the default value.

• Not Allowed: U-turns are prohibited at all junctions, regardless of junction valency.

• Allowed only at Dead Ends: U-turns are prohibited at all junctions, except those that have only one adjacent edge (a dead end).

• Allowed only at Intersections and Dead Ends: U-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). Oftentimes, networks modeling streets 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.

Choice list: [‘Allowed’, ‘Not Allowed’, ‘Allowed Only at Dead Ends’, ‘Allowed Only at Intersections and Dead Ends’]

point_barriers

Optional FeatureSet. Specify one or more points to 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 time delay spent at a railroad crossing.

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

as barriers. When specifying the point barriers, you can set properties for each one, such as its name or barrier type, by using attributes. The point barriers can be specified with 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 or Additional_Distance field. This barrier type is referred to as an added-cost point barrier.

• Additional_Time: Indicates how much travel time is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the measurement units are time based. 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: Indicates how much distance is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the measurement units are distance based. 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.

line_barriers

Optional FeatureSet. 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 on 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 a name property for each one by using the following attribute: Name: The name of the barrier.

polygon_barriers

Optional FeatureSet. 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 on the number of polygons you can specify as the polygon barriers, the combined number of streets intersected by all the polygons should not exceed 2,000. When specifying the polygon barriers, you can set properties for each one, such as its name or barrier type, by using attributes. The polygon barriers can be specified with the following attributes: * Name: The name of the barrier. * BarrierType: Specifies whether the barrier restricts travel completely

or scales the 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 time or distance required to travel the

underlying streets by a factor specified using the ScaledTimeFactor or ScaledDistanceFactor fields. If the streets are partially covered by the barrier, the travel time or distance is apportioned and then scaled. For example, a factor 0.25 would mean that travel on underlying streets is expected to be four times faster than normal. A factor of 3.0 would mean 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 might be used to model storms that reduce travel speeds in specific regions.

ScaledTimeFactor: This is the factor by which the travel time of the streets intersected by the barrier is multiplied. This field is applicable only for scaled-cost barriers and only if the measurement units are time based. The field value must be greater than zero.

• ScaledDistanceFactor: This is the factor by which the distance of the streets intersected by the barrier is multiplied. This attribute is applicable only for scaled-cost barriers and only if the measurement units are distance based. The attribute value must be greater than zero.

use_hierarchy

Optional boolean. Specify whether hierarchy should be used when finding the shortest path between the facilities and demand points. Checked (True): Use hierarchy when measuring between facilities and demand points. When hierarchy is used, the tool prefers higher-order streets (such as freeways) to 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 true when finding routes to faraway locations, 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, since the tool can determine the best route from a relatively smaller subset of streets. Unchecked (False): Do not use hierarchy when measuring between facilities and demand points. If hierarchy is not used, the tool considers all the streets and doesn’t prefer higher-order streets when finding the route. This is often used when finding short-distance routes within a city. The tool automatically reverts to using hierarchy if the straight-line distance between facilities and demand points is greater than 50 miles, even if you have set this parameter to not use hierarchy.

restrictions

Optional string. Specify which restrictions should be honored by the tool when finding the best routes between facilities and demand points. A restriction represents a driving preference or requirement. In most cases, restrictions cause roads to be prohibited. For instance, using an Avoid Toll Roads restriction will result in a route that will include toll roads only when it is absolutely required to travel on toll roads in order 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 as illegal to do so. Below is a list of available restrictions and a short description. Some restrictions require an additional value to be specified for their desired use. This value needs to 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 under 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. 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 check whether the restriction is available in a particular country by looking at the table in the Country List section of the Data coverage for network analysis services web page. 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 whose Restriction Usage parameter value is between 0 and 1 (see the Attribute Parameter Value parameter). It prohibits all restrictions whose Restriction Usage parameter value is greater than 0. The service supports the restriction names listed in the following table:

Choice list:[‘Any Hazmat Prohibited’, ‘Avoid Carpool Roads’, ‘Avoid Express Lanes’, ‘Avoid Ferries’, ‘Avoid Gates’, ‘Avoid Limited Access Roads’, ‘Avoid Private Roads’, ‘Avoid Roads Unsuitable for Pedestrians’, ‘Avoid Stairways’, ‘Avoid Toll Roads’, ‘Avoid Toll Roads for Trucks’, ‘Avoid Truck Restricted Roads’, ‘Avoid Unpaved Roads’, ‘Axle Count Restriction’, ‘Driving a Bus’, ‘Driving a Delivery Vehicle’, ‘Driving a Taxi’, ‘Driving a Truck’, ‘Driving an Automobile’, ‘Driving an Emergency Vehicle’, ‘Height Restriction’, ‘Kingpin to Rear Axle Length Restriction’, ‘Length Restriction’, ‘Preferred for Pedestrians’, ‘Riding a Motorcycle’, ‘Roads Under Construction Prohibited’, ‘Semi or Tractor with One or More Trailers Prohibited’, ‘Single Axle Vehicles Prohibited’, ‘Tandem Axle Vehicles Prohibited’, ‘Through Traffic Prohibited’, ‘Truck with Trailers Restriction’, ‘Use Preferred Hazmat Routes’, ‘Use Preferred Truck Routes’, ‘Walking’, ‘Weight Restriction’, ‘Weight per Axle Restriction’, ‘Width Restriction’]

attribute_parameter_values

Optional FeatureSet. Specify additional values required by some restrictions, such as the weight of a vehicle for Weight Restriction. You can also use the attribute parameter to specify whether any restriction prohibits, avoids, or prefers travel on roads that use the restriction. 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 even highly prefer them. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value. If you specify the Attribute Parameter Values parameter from a feature class, the field names on the feature class must match the fields as described below:

• AttributeName: Lists the name of the restriction.

• ParameterName: Lists 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. Attribute Parameter Values 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 and 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 within the parentheses:

• PROHIBITED (-1) - Travel on the roads using the restriction is completely

prohibited.

• AVOID_HIGH (5) - It

is highly unlikely for the tool to include in the route the roads that are associated with the restriction.

• AVOID_MEDIUM (2) - It

is unlikely for the tool to include in the route the roads that are associated with the restriction.

• AVOID_LOW (1.3) - It is somewhat unlikely for the tool to include in the route the roads

that are associated with the restriction.

• PREFER_LOW (0.8) - It

is somewhat likely for the tool to include in the route the roads that are associated with the restriction.

• PREFER_MEDIUM (0.5) - It is likely for the tool to include in the route the roads that

are associated with the restriction.

• PREFER_HIGH (0.2) - It is highly likely for the tool to include in the route the roads

that are associated with the restriction.

In most cases, you can use the default value, PROHIBITED, for the Restriction Usage if the restriction is dependent on a vehicle-characteristic such as vehicle height. However, in some cases, the value for Restriction Usage depends on your routing preferences. For example, the Avoid Toll Roads restriction has the default value of AVOID_MEDIUM for the Restriction Usage parameter. 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 would put lower importance on avoiding tolls; choosing AVOID_HIGH instead would give it a higher importance and thus make it more acceptable for the service to generate longer routes to avoid tolls. Choosing PROHIBITED would entirely disallow 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, you would 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.

allocation_line_shape

Optional string. The default is to output straight lines.

Specify the type of line features that are output by the tool. The parameter accepts one of the following values: Straight Line: Return straight lines between solution facilities and the demand points allocated to them. This is the default. Drawing straight lines on a map helps you visualize how demand is allocated. None: Return a table containing data about the shortest paths between solution facilities and the demand points allocated to them, but don’t return lines. No matter which value you choose for the Allocation Line Shape parameter, the shortest route is always determined by minimizing the travel time or the travel distance, never using the straight-line distance between demand points and facilities. That is, this parameter only changes the output line shapes; it doesn’t change the measurement method.

Choice list:[‘None’, ‘Straight Line’]

travel_mode

Optional string. Specify 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 better reflect your organization’s workflows. You need to specify the name of a travel mode supported by your organization.

To get a list of supported travel mode names, run the GetTravelModes tool from the Utilities toolbox available under the same GIS Server connection you used to access the tool. The GetTravelModes 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 Travel Mode Settings field as input. This speeds up the tool execution as the tool does not have to lookup 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 travelling by car. You may want to 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 may choose to do this to try out different settings to get desired analysis results. Once you have identified the analysis settings, you should work with your organization’s administrator and save these settings as part of new or existing travel mode so that everyone in your organization can rerun the analysis with the same settings.

impedance

Optional string. Specify 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 taking one minute to travel a mile along an empty road is an example of impedance. 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. Choose from the following impedance values: Drive Time-Models travel times for a car. These travel times are static for each road and don’t fluctuate with traffic. Truck Time-Models travel times for a truck. These travel times are static for each road and don’t fluctuate with traffic. Walk Time-Models travel times for a pedestrian. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value.

Choice list:[‘Drive Time’, ‘Truck Time’, ‘Walk Time’]

gis

Optional, the GIS on which this tool runs. If not specified, the active GIS is used.

: returns the following as a named tuple:
• solve_succeeded - Solve Succeeded as a bool

• output_allocation_lines - Output Allocation Lines as a FeatureSet

• output_facilities - Output Facilities as a FeatureSet

• output_demand_points - Output Demand Points as a FeatureSet

generate_origin_destination_cost_matrix¶

arcgis.network.analysis.generate_origin_destination_cost_matrix(origins: arcgis.features.feature.FeatureSet, destinations: arcgis.features.feature.FeatureSet, travel_mode: str = 'Custom', time_units: str = 'Minutes', distance_units: str = 'Kilometers', analysis_region: str = None, number_of_destinations_to_find: int = None, cutoff: float = None, time_of_day: datetime.datetime = None, time_zone_for_time_of_day: str = 'Geographically Local', point_barriers: arcgis.features.feature.FeatureSet = None, line_barriers: arcgis.features.feature.FeatureSet = None, polygon_barriers: arcgis.features.feature.FeatureSet = None, uturn_at_junctions: str = 'Allowed Only at Intersections and Dead Ends', use_hierarchy: bool = True, restrictions: str = None, attribute_parameter_values: arcgis.features.feature.FeatureSet = None, impedance: str = 'Drive Time', origin_destination_line_shape: str = 'None', save_output_network_analysis_layer=False, overrides=None, time_impedance=None, distance_impedance=None, output_format=None, gis=None, future=False) → tuple

The generate_origin_destination_cost_matrix tool creates an origin-destination (OD) cost matrix from multiple origins to multiple destinations. An OD cost matrix is a table that contains the travel time and travel distance from each origin to each destination. Additionally, it ranks the destinations that each origin connects to in ascending order based on the minimum time or distance required to travel from that origin to each destination. The best path on the street network is discovered for each origin-destination pair, and the travel times and travel distances are stored as attributes of the output lines. Even though the lines are straight for performance reasons, they always store the travel time and travel distance along the street network, not straight-line distance.

Argument

Description

origins

Required FeatureSet. Specify locations that function as starting points in generating the paths to destinations. You can add up to 200 origins. When specifying the origins, you can set properties for each one, such as its name or the number of destinations to find from the origin, by using attributes. The origins can be specified with the following attributes

• Name - The name of the origin. The name can be an unique identifier for the origin. The name is included in the output lines (as the OriginName field) and in the output origins (as the Name field) and can be used to join additional information from the tool outputs to the attributes of your origins. If the name is not specified, a unique name prefixed with Location is automatically generated in the output origins. An auto-generated origin name is not included in the output lines.

• TargetDestinationCount-The maximum number of destinations that must be found for the origin. If a value is not specified, the value from the Number of Destinations to Find parameter is used. Cutoff-Specify the travel time or travel distance value at which to stop searching for destinations from the origin. Any destination beyond the cutoff value will not be considered. The value needs to be in the units specified by the Time Units parameter if the impedance attribute in your travel mode is time based or in the units specified by the Distance Units parameter if the impedance attribute in your travel mode is distance based. If a value is not specified, the value from the Cutoff parameter is used.

• CurbApproach - Specifies the direction a vehicle may depart from the origin. 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 depart the origin in either direction, so a U-turn is allowed at the origin. This setting can be chosen if it is possible and practical for your vehicle to turn around at the origin. This decision may depend on the width of the road and the amount of traffic or whether the origin has a parking lot where vehicles can enter and turn around.

• 1 ( Right side of vehicle)-When the vehicle departs the origin, the origin 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 depart from the bus stop on the right-hand side.

• 2 (Left side of vehicle)-When the vehicle departs the origin, 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 depart from the bus stop on the left-hand side.

• 3 (No U-Turn)-For this tool, the No U-turn (3) value functions the same as Either side of vehicle. The CurbApproach property is designed to work with both kinds of national driving standards: right-hand traffic (United States) and left-hand traffic (United Kingdom). First, consider an origin 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 depart the origin 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 depart from an origin and not have a lane of traffic between the vehicle and the origin, you would choose Right side of vehicle (1) in the United States but Left side of vehicle (2) in the United Kingdom.

destinations

Required FeatureSet. Specify locations that function as ending points in generating the paths from origins. You can add up to 200 destinations. When specifying the destinations, you can set properties for each one, such as its name, by using attributes. The destinations can be specified with the following attributes:

• Name - The name of the destination. The name can be an unique identifier for the destination. The name is included in the output lines (as the DestinationName field) and in the output destinations (as the Name field) and can be used to join additional information from the tool outputs to the attributes of your destinations. If the name is not specified, a unique name prefixed with Location is automatically generated in the output destinations. An auto-generated destination name is not included in the output lines.

• CurbApproach - Specifies the direction a vehicle may arrive at the destination. 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 arrive the destination in either direction, so a U-turn is allowed at the destination. This setting can be chosen if it is possible and practical for your vehicle to turn around at the destination. This decision may depend on the width of the road and the amount of traffic or whether the destination has a parking lot where vehicles can enter and turn around.

• 1 ( Right side of vehicle)-When the vehicle arrives at the destination, the destination 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 at the bus stop on the right-hand side.

• 2 (Left side of vehicle)-When the vehicle arrives at the destination, 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 at the bus stop on the left-hand side.

• 3 (No U-Turn)-For this tool, the No U-turn (3) value functions the same as Either side of vehicle. The CurbApproach property 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 destination 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 arrive at the destination 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 the destination and not have a lane of traffic between the vehicle and the destination, you would choose Right side of vehicle (1) in the United States but Left side of vehicle (2) in the United Kingdom.

travel_mode

Optional string. Specify 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 better reflect your organization’s workflows. You need to specify the name of a travel mode supported by your organization.

To get a list of supported travel mode names, run the GetTravelModes tool from the Utilities toolbox available under the same GIS Server connection you used to access the tool. The GetTravelModes 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 Travel Mode Settings field as input. This speeds up the tool execution as the tool does not have to lookup 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 travelling by car. You may want to 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 may choose to do this to try out different settings to get desired analysis results. Once you have identified the analysis settings, you should work with your organization’s administrator and save these settings as part of new or existing travel mode so that everyone in your organization can rerun the analysis with the same settings.

time_units

Optional string. Specify the units that should be used to measure and report the total travel time between each origin-destination pair.

Choice list:[‘Seconds’, ‘Minutes’, ‘Hours’, ‘Days’]

distance_units

Optional string. Specify the units that should be used to measure and report the total travel distance between each origin-destination pair.

Choice list:[‘Meters’, ‘Kilometers’, ‘Feet’, ‘Yards’, ‘Miles’, ‘NauticalMiles’]

analysis_region

Optional string. Specify the region in which to perform the analysis. 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 recommended to speed up the tool execution.

Choice list:[‘NorthAmerica’, ‘SouthAmerica’, ‘Europe’, ‘MiddleEastAndAfrica’, ‘India’, ‘SouthAsia’, ‘SouthEastAsia’, ‘Thailand’, ‘Taiwan’, ‘Japan’, ‘Oceania’, ‘Greece’, ‘Korea’]

number_of_destinations_to_find

Optional integer. Specify the maximum number of destinations to find per origin. If a value for this parameter is not specified, the output matrix includes travel costs from each origin to every destination. Individual origins can have their own values (specified as the TargetDestinationCount field) that override the Number of Destinations to Find parameter value.

cutoff

Optional float. Specify the travel time or travel distance value at which to stop searching for destinations from a given origin. Any destination beyond the cutoff value will not be considered. Individual origins can have their own values (specified as the Cutoff field) that override the Cutoff parameter value.

The value needs to be in the units specified by the Time Units parameter if the impedance attribute of your travel mode is time based or in the units specified by the Distance Units parameter if the impedance attribute of your travel mode is distance based. If a value is not specified, the tool will not enforce any travel time or travel distance limit when searching for destinations.

time_of_day

Optional datetime. Specifies the time and date at which the routes should 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.

time_zone_for_time_of_day

Optional string. Specifies the time zone of the Time of Day parameter.

• Geographically Local: The Time of Day parameter refers to the time zone in which the first stop of a route is located. If you are generating many routes that start in multiple times zones, the start times are staggered in Coordinated Universal Time (UTC). For example, a Time of Day value of 10:00 a.m., 2 January, would mean a start time of 10:00 a.m. Eastern Standard Time (3:00 p.m. UTC) for routes beginning in the Eastern Time Zone and 10:00 a.m. Central Standard Time (4:00 p.m. UTC) for routes beginning in the Central Time Zone. The start times are offset by one hour in UTC. The arrive and depart times and dates recorded in the output Stops feature class will refer to the local time zone of the first stop for each route.

• UTC: The Time of Day parameter refers to Coordinated Universal Time (UTC). Choose this option if you want to generate a route for a specific time, such as now, but aren’t certain in which time zone the first stop will be located. If you are generating many routes spanning multiple times zones, the start times in UTC are simultaneous. For example, a Time of Day value of 10:00 a.m., 2 January, would mean a start time of 5:00 a.m. Eastern Standard Time (UTC-5:00) for routes beginning in the Eastern Time Zone and 4:00 a.m. Central Standard Time (UTC-6:00) for routes beginning in the Central Time Zone. Both routes would start at 10:00 a.m. UTC. The arrive and depart times and dates recorded in the output Stops feature class will refer to UTC.

Choice list:[‘Geographically Local’, ‘UTC’]

point_barriers

Optional FeatureSet. Specify one or more points to 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 time delay spent at a railroad crossing.

The tool imposes a limit of 250 points that can be added as barriers. When specifying the point barriers, you can set properties for each one, such as its name or barrier type, by using attributes. The point barriers can be specified with 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 or Additional_Distance field. This barrier type is referred to as an added-cost point barrier.

• Additional_Time: Indicates how much travel time is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the measurement units are time based. 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: Indicates how much distance is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the measurement units are distance based. 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.

line_barriers

Optional FeatureSet. 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 on 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 a name property for each one by using the following attribute:

• Name: The name of the barrier.

polygon_barriers

Optional FeatureSet. 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 on the number of polygons you can specify as the polygon barriers, the combined number of streets intersected by all the polygons should not exceed 2,000. When specifying the polygon barriers, you can set properties for each one, such as its name or barrier type, by using attributes. The polygon barriers can be specified with the following attributes:

• Name: The name of the barrier.

• BarrierType: Specifies whether the barrier restricts travel completely or scales the 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 time or distance required to travel the underlying streets by a factor specified using the ScaledTimeFactor or ScaledDistanceFactor fields. If the streets are partially covered by the barrier, the travel time or distance is apportioned and then scaled. For example, a factor 0.25 would mean that travel on underlying streets is expected to be four times faster than normal. A factor of 3.0 would mean 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 might be used to model storms that reduce travel speeds in specific regions.

• ScaledTimeFactor: This is the factor by which the travel time of the streets intersected by the barrier is multiplied. This field is applicable only for scaled-cost barriers and only if the measurement units are time based. The field value must be greater than zero.

• ScaledDistanceFactor: This is the factor by which the distance of the streets intersected by the barrier is multiplied. This attribute is applicable only for scaled-cost barriers and only if the measurement units are distance based. The attribute value must be greater than zero.

uturn_at_junctions

Optional string. 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, the U-turn policy parameter is implicitly specified by how many edges, or streets, 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.

Choice list:[‘Allowed’, ‘Not Allowed’, ‘Allowed Only at Dead Ends’, ‘Allowed Only at Intersections and Dead Ends’]

use_hierarchy

Optional boolean. Specify whether hierarchy should be used when finding the shortest paths between stops. Checked (True): Use hierarchy when finding routes. When hierarchy is used, the tool prefers higher-order streets (such as freeways) to 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 true when finding routes to faraway locations, 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, since the tool can determine the best route from a relatively smaller subset of streets. Unchecked (False): Do not use hierarchy when finding routes. If hierarchy is not used, the tool considers all the streets and doesn’t prefer higher-order streets when finding the route. This is often used when finding short routes within a city.

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 you have set this parameter to not use hierarchy. This parameter is ignored unless Travel Mode is set to Custom. When modeling a custom walking mode, it is recommended to turn off hierarchy since the hierarchy is designed for motorized vehicles.

restrictions

Optional string. Specify which restrictions should 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, but they can also cause them to be avoided or preferred. For instance, using an Avoid Toll Roads restriction will result in a route that will include toll roads only when it is absolutely required to travel on toll roads in order to visit a stop. 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 as illegal to do so. The values you provide for this parameter are ignored unless Travel Mode is set to Custom. Below is a list of available restrictions and a short description. Some restrictions require an additional value to be specified for their desired use. This value needs to 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 under 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. 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 check whether the restriction is available in a particular country by looking at the table in the Country List section of the Data coverage for network analysis services web page. 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 whose Restriction Usage parameter value is between 0 and 1 (see the Attribute Parameter Value parameter). It prohibits all restrictions whose Restriction Usage parameter value is greater than 0.

Choice list:[‘Any Hazmat Prohibited’, ‘Avoid Carpool Roads’, ‘Avoid Express Lanes’, ‘Avoid Ferries’, ‘Avoid Gates’, ‘Avoid Limited Access Roads’, ‘Avoid Private Roads’, ‘Avoid Roads Unsuitable for Pedestrians’, ‘Avoid Stairways’, ‘Avoid Toll Roads’, ‘Avoid Toll Roads for Trucks’, ‘Avoid Truck Restricted Roads’, ‘Avoid Unpaved Roads’, ‘Axle Count Restriction’, ‘Driving a Bus’, ‘Driving a Delivery Vehicle’, ‘Driving a Taxi’, ‘Driving a Truck’, ‘Driving an Automobile’, ‘Driving an Emergency Vehicle’, ‘Height Restriction’, ‘Kingpin to Rear Axle Length Restriction’, ‘Length Restriction’, ‘Preferred for Pedestrians’, ‘Riding a Motorcycle’, ‘Roads Under Construction Prohibited’, ‘Semi or Tractor with One or More Trailers Prohibited’, ‘Single Axle Vehicles Prohibited’, ‘Tandem Axle Vehicles Prohibited’, ‘Through Traffic Prohibited’, ‘Truck with Trailers Restriction’, ‘Use Preferred Hazmat Routes’, ‘Use Preferred Truck Routes’, ‘Walking’, ‘Weight Restriction’, ‘Weight per Axle Restriction’, ‘Width Restriction’]

attribute_parameter_values

Optional FeatureSet. Specify additional values required by some restrictions, such as the weight of a vehicle for Weight Restriction. You can also use the attribute parameter to specify whether any restriction prohibits, avoids, or prefers travel on roads that use the restriction. 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 even highly prefer them. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value. If you specify the Attribute Parameter Values parameter from a feature class, the field names on the feature class must match the fields as described below:

• AttributeName: Lists the name of the restriction.

• ParameterName: Lists 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. Attribute Parameter Values 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 and 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 within the parentheses:

• PROHIBITED (-1) - Travel on the roads using the restriction is completely prohibited.

• AVOID_HIGH (5) - It

is highly unlikely for the tool to include in the route the roads that are associated with the restriction.

• AVOID_MEDIUM (2) - It

is unlikely for the tool to include in the route the roads that are associated with the restriction.

• AVOID_LOW (1.3) - It

is somewhat unlikely for the tool to include in the route the roads that are associated with the restriction.

• PREFER_LOW (0.8) - It

is somewhat likely for the tool to include in the route the roads that are associated with the restriction.

• PREFER_MEDIUM (0.5) - It is likely for the tool to include in the route the roads that

are associated with the restriction.

• PREFER_HIGH (0.2) - It is highly likely for the tool to include in the route the roads

that are associated with the restriction.

In most cases, you can use the default value, PROHIBITED, for the Restriction Usage if the restriction is dependent on a vehicle-characteristic such as vehicle height. However, in some cases, the value for Restriction Usage depends on your routing preferences. For example, the Avoid Toll Roads restriction has the default value of AVOID_MEDIUM for the Restriction Usage parameter. 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 would put lower importance on avoiding tolls; choosing AVOID_HIGH instead would give it a higher importance and thus make it more acceptable for the service to generate longer routes to avoid tolls. Choosing PROHIBITED would entirely disallow 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, you would 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.

impedance

Optional string. Specify 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 distance is 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.) Travel time can also be an impedance; a car may take one 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. Choose from the following impedance values: Drive Time-Models travel times for a car. These travel times are dynamic and fluctuate according to traffic flows in areas where traffic data is available. Truck Time-Models travel times for a truck. These travel times are static for each road and don’t fluctuate with traffic. This is the default value. Walk Time-Models travel times for a pedestrian. Travel Distance-Stores length measurements along roads and paths. To model walk distance, choose this option and ensure Walking is set in the Restriction parameter. Similarly, to model drive or truck distance, choose Travel Distance here and set the appropriate restrictions so your vehicle travels only on roads where it is permitted to do so. The value you provide for this parameter is ignored unless Travel Mode is set to Custom. If you choose Drive Time, Truck Time, or Walk Time, the Measurement Units parameter must be set to a time-based value; if you choose Travel Distance for Impedance, Measurement Units must be distance-based.

Choice list:[‘Drive Time’, ‘Truck Time’, ‘Walk Time’, ‘Travel Distance’]

origin_destination_line_shape

Optional string. The resulting lines of an OD cost matrix can be represented with either straight-line geometry or no geometry at all. In both cases, the route is always computed along the street network by minimizing the travel time or the travel distance, never using the straight-line distance between origins and destinations. Straight Line: Straight lines connect origins and destinations. None: Do not return any shapes for the lines that connect origins and destinations. This is useful when you have a large number of origins and destinations and are interested only in the OD cost matrix table (and not the output line shapes).

list:[‘None’, ‘Straight Line’]

save_output_layer

Optional boolean. Specify if the tool should save the analysis settings as a network analysis layer file. You cannot directly work with this file even when you open the file in an ArcGIS Desktop application like ArcMap. It is meant to be sent to Esri Technical Support to diagnose the quality of results returned from the tool. True: Save the network analysis layer file. The file is downloaded in 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 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 Network Analysis Layer parameter in the entry corresponding to the tool execution in the Geoprocessing Results window. False: Do not save the network analysis layer file. This is the default.

overrides

Optional string. Specify additional settings that can influence the behavior of the solver when finding solutions for the network analysis problems. The value for this parameter needs to 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 quotes. 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. A list of supported override settings for each solver and their acceptable values can be obtained by contacting Esri Technical Support.

save_route_data

Optional boolean. Choose whether the output includes a zip file that contains a file geodatabase holding 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. True: Save the route data as a zip file. The file is downloaded in 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 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 Route Data parameter in the entry corresponding to the tool execution in the Geoprocessing Results window. False: Do not save the route data. This is the default.

time_impedance

Optional string. Specify the time-based impedance.

distance_impedence

Optional string. Specify the distance-based impedance.

output_format

Optional. Specify the format in which the output features are created.

Choose from the following formats:
• Feature Set - The output features are returned as feature classes and tables. This is the default.

• JSON File - The output features are 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 File - The output features are 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.

gis

Optional, the GIS on which this tool runs. If not specified, the active GIS is used.

future

Optional boolean. If True, a GPJob is returned instead of results. The GPJob can be queried on the status of the execution.

:: returns the following as a named tuple:

• solve_succeeded - Solve Succeeded as a bool

• output_origin_destination_lines - Output Origin Destination Lines as a FeatureSet

• output_origins - Output Origins as a FeatureSet

• output_destinations - Output Destinations as a FeatureSet

find_routes¶

arcgis.network.analysis.find_routes(stops: arcgis.features.feature.FeatureSet, measurement_units: str = 'Minutes', analysis_region: str = None, reorder_stops_to_find_optimal_routes: bool = False, preserve_terminal_stops: str = 'Preserve First', return_to_start: bool = False, use_time_windows: bool = False, time_of_day: datetime.datetime = None, time_zone_for_time_of_day: str = 'Geographically Local', uturn_at_junctions: str = 'Allowed Only at Intersections and Dead Ends', point_barriers: arcgis.features.feature.FeatureSet = None, line_barriers: arcgis.features.feature.FeatureSet = None, polygon_barriers: arcgis.features.feature.FeatureSet = None, use_hierarchy: bool = True, restrictions: str = None, attribute_parameter_values: arcgis.features.feature.FeatureSet = None, route_shape: str = 'True Shape', route_line_simplification_tolerance: arcgis.geoprocessing._types.LinearUnit = None, populate_route_edges: bool = False, populate_directions: bool = True, directions_language: str = 'en', directions_distance_units: str = 'Miles', directions_style_name: str = 'NA Desktop', travel_mode: str = 'Custom', impedance: str = 'Drive Time', overrides=None, time_impedance='TravelTime', save_route_data=False, distance_impedance='Kilometers', output_format='Feature Set', save_output_na_layer=False, time_zone_for_time_windows='Geographically Local', gis=None, future=False) → tuple

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.

Argument

Description

stops

Required FeatureSet. Specify the locations you want the output route or routes to 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 one, such as its name or service time, by using attributes. The stops can be specified with the following attributes:

• Name: The name of the stop. This name is used when generating driving directions. It is common to pass the name of a business, person, or street address at the stop. If a value is not specified, an automatically generated name such as Location 1 or Location 2 is assigned to each stop.

• TimeWindowStart: The earliest time the stop can be visited. Specify this attribute if you want to limit when a route can arrive at a stop; for instance, you may want to make deliveries to a restaurant between busy lunch and dinner hours (for example, sometime between 2:00 and 4:30 p.m.) to facilitate the work for you and the restaurant staff.

The value is specified as an integer that represents the number of milliseconds since epoch (January 1, 1970).

This value can be specified either in UTC or local time, depending on the value given for the timeWindowsAreUTC parameter.

If you specify this attribute, you also need to specify the TimeWindowEnd attribute.

• TimeWindowEnd: The latest time the stop can be visited. Together, the TimeWindowStart and TimeWindowEnd attributes make up the time window within which a route can visit the stop. As with TimeWindowStart, the TimeWindowEnd value is specified as an integer that represents the number of milliseconds since epoch (January 1, 1970) and is interpreted as UTC or local time, depending on the value specified for the timeWindowsAreUTC parameter.

The time window specified using the TimeWindowStart and TimeWindowEnd attributes is not considered a hard constraint by the service. That is, the service doesn’t fail if the stop cannot be visited during the time window; instead, the service tries to find a route that visits the stop during its time window, but if time window violations are inevitable, the service tries to find a solution that minimizes the time-window violation time for all stops in the problem.

If a route has to arrive early at the stop, a wait time is added to the total travel time of the route. Similarly, if the route arrives late at the stop, a violation time is added to the total travel time of the route. For example, If the time window on the stop is set as 10:00 AM to 11:00 AM and the earliest a route can reach the stop is 11:25 AM, a violation of 25 minutes is added to the total travel time.

• RouteName: The name of the route to which the stop belongs. Use this attribute to group stops into different routes and, therefore, solve multiple routes in a single request. For example, if you want to find two distinct routes - a route with 4 stops and another with 6 stops - set RouteName to Route1 for each of the four stops and Route2 for each of the 6 stops. The service will produce two distinct routes and driving directions for each group of stops in a single request.

If RouteName is not specified for any stops, all stops belong to the same route. If RouteName is not specified for some stops, those stops are treated as unassigned and are not included in any route.

• Sequence: The output routes will visit the stops in the order you specify with this attribute. Within 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.)

• CurbApproach: Specify the direction a vehicle may arrive at and depart from the stop. One of the integers listed in the Coded value column in the following table must be specified as a value of this attribute. The values in the Setting column are the descriptive names for the CurbApproach attribute values that you may have come across when using ArcGIS Network Analyst extension extension software.

 Setting Description Either side of vehicle The vehicle can approach and depart the stop in either direction, so a U-turn is allowed at the stop. This is the default value. This setting can be chosen if it is possible and desirable for your vehicle to turn around at the stop. This decision may depend on the width of the road and the amount of traffic or whether the stop has a parking lot where vehicles can pull in and turn around. right side of vehicle When the vehicle approaches and departs the stop, the stop must be on the right side of the vehicle. A U-turn is prohibited. This is typically used for vehicles like busses that must arrive with the bus stop on the right-hand side. left side of vehicle When the vehicle approaches and departs the stop, the stop must be on the left side of the vehicle. A U-turn is prohibited. This is typically used for vehicles like busses that must arrive with the bus stop on the left-hand side. No U-Turn When the vehicle approaches the stop, the stop can be on either side of the vehicle; however, when it departs, the vehicle must continue in the same direction it arrived in. A U-turn is prohibited.

The CurbApproach property 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 from the right or left side. For example, if you want to arrive at a stop and not have a lane of traffic between the vehicle and the stop, you would choose Right side of vehicle in the United States but Left side of vehicle in the United Kingdom.

• Attr_TravelTime: Specify the amount of time for cars, in minutes, that will be spent at the stop when the route visits it. This attribute can be used to model the time required to provide some kind of service while you are at the stop. It can also be used to specify some additional time required to reach the actual location on the street from where the route starts or time required to reach the actual destination location from the location on the street where the route ends. The value for this attribute is included in the total travel time for the route and is also displayed in driving directions as service time. A zero or null value indicates that the stop requires no service time.

For example, suppose you are finding the best route through three stops. Suppose it requires 2 minutes to walk to the street location from where the route starts, you need to spend 10 minutes at Stop 2, and it takes 5 minutes to walk from the street location to the destination. The Attr_TravelTime attribute should be given values of 2, 10, and 5 for Stop 1, Stop 2, and Stop 3, respectively. If it takes 10 minutes to travel from Stop 1 to Stop 2 and 10 minutes to travel from Stop 2 to Stop 3, the total travel time to reach Stop 3 is displayed as 37 minutes (2 + 10 + 10 + 10 + 5), even though there is only 20 minutes of traveling to reach Stop 3.

• Attr_TruckTravelTime: Specify the amount of time for trucks, in minutes, that will be added to the total travel time of the route at the stop. The attribute value can be used to model the time spent at the stop.

The value for this attribute is included in the total travel time for the route and is also displayed in driving directions as service time. A zero or null value indicates that the incident requires no service time. The default value is 0.

• Attr_WalkTime: Specify the amount of time for pedestrians, in minutes, that will be added to the total travel time of the route at the stop. The attribute value can be used to model the time spent at the incident. The value for this attribute is included in the total travel time for the route and is also displayed in driving directions as service time. A zero or null value indicates that the incident requires no service time. The default value is 0.

• Attr_Miles: Specify the distance in miles that will be added when calculating total distance of the route. Generally the locations of the stops are not exactly on the streets but are set back somewhat from the road. The Attr_Miles attribute 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.

• Attr_Kilometers: Specify the distance in kilometers that will be added when calculating total distance of the route. Generally the locations of the stops are not exactly on the streets but are set back somewhat from the road. The Attr_Kilometers attribute 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.

• LocationType: The stop type.

 Setting Coded value Description Stop 0 A location that the route should visit. This is the default. Waypoint 1 A location that the route should travel through without making a stop. Waypoints can be used to force the route to take a specific path (to go through the waypoint) without being considered an actual stop. Waypoints do not appear in driving directions. Break 2 A location where the route stops for the driver to take a break.
• Bearing: Specify the direction the vehicle or person is moving in. Bearing is measured clockwise from true north and must be in degrees. Typically, values are between 0 and 360; however, negative values are interpreted by subtracting them from 360 degrees.

• BearingTol: Short for bearing tolerance, this field specifies the maximum acceptable difference between the heading of a vehicle and a tangent line from the point on a street where Network Analyst attempts to locate the vehicle. The bearing tolerance is used to determine whether the direction in which a vehicle is moving generally aligns with the underlying road. If they align within the given tolerance, the vehicle is located on that edge; if not, the next nearest eligible edge is evaluated.

measurement_units

Required string. Specify the units that should 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.

Choice list:[‘Meters’, ‘Kilometers’, ‘Feet’, ‘Yards’, ‘Miles’, ‘NauticalMiles’, ‘Seconds’, ‘Minutes’, ‘Hours’, ‘Days’]

analysis_region

Optional string. Specify the region in which to perform the analysis. 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 auto-detection of the region name is not accurate for your inputs. To specify a region, use one of the following values: Europe,Japan,Korea,MiddleEast, and Africa. NorthAmerica, SouthAmerica, SouthAsia,Thailand; 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. Greece redirects to Europe. India redirects to South Asia. Oceania redirects to South Asia. South East Asia redirects to South Asia. Taiwan redirects to South Asia.

Choice list:[‘Europe’, ‘Japan’, ‘Korea’, ‘MiddleEastAndAfrica’, ‘NorthAmerica’, ‘SouthAmerica’, ‘SouthAsia’, ‘Thailand’]

reorder_stops_to_find

Optional boolean. Specify whether to visit the stops in the order you define or the order the tool determines will minimize overall travel.

• Checked (True) - The tool determines the sequence that will minimize overall travel distance or time. It can reorder stops and account for time windows at stops. Additional parameters allow you to preserve the first or last stops while allowing the tool to reorder the intermediary stops.

• Unchecked (False) - The stops are visited in the order you define. This is the default option. You can set the order of stops using a Sequence attribute in the input stops features or let the sequence be determined by the Object ID of the stops. Finding the optimal stop order and the best routes is commonly known as solving the traveling salesman problem (TSP).

preserve_terminal_stops

Optional string. When Reorder Stops to Find Optimal Routes is checked (or True), you have options to 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 First - The tool won’t reorder the first stop. Choose this option if you are starting from a known location, such as your home, headquarters, or current location.Preserve Last-The tool won’t reorder the last stop. The output routes may start from any stop feature but must end at the predetermined last stop. Preserve First and Last-The tool won’t reorder the first and last stops.

Preserve None - The tool may reorder any stop, including the first and last stops. The route may start or end at any of the stop features.Preserve Terminal Stops is ignored when Reorder Stops to Find Optimal Routes is unchecked (or False).

Choice list: [‘Preserve First’, ‘Preserve Last’, ‘Preserve First and Last’, ‘Preserve None’]

return_to_start

Optional boolean. Choose whether routes should 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.

Checked (True) - The route should start and end at the first stop feature. This is the default value. When Reorder Stops to Find Optimal Routes and Return to Start are both checked (or True), Preserve Terminal Stops must be set to Preserve First.

Unchecked (False) - The route won’t start and end at the first stop feature.

use_time_windows

Optional boolean. Check this option (or set it to True) if any input stops have time windows that specify when the route should reach the stop. You can add time windows to input stops by entering time values in the TimeWindowStart and TimeWindowEnd attributes.

Checked (True) - The input stops have time windows and you want the tool to try to honor them.

Unchecked (False) - The input stops don’t have time windows, or if they do, you don’t want the tool to try to honor them. This is the default value.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 to uncheck this option (set to False) if possible.

time_of_day

Optional datetime. Specifies the time and date at which the routes should 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.

time_zone_for_time_of_day

Optional string. Specifies the time zone of the Time of Day parameter.Geographically Local-The Time of Day parameter refers to the time zone in which the first stop of a route is located. If you are generating many routes that start in multiple times zones, the start times are staggered in Coordinated Universal Time (UTC). For example, a Time of Day value of 10:00 a.m., 2 January, would mean a start time of 10:00 a.m. Eastern Standard Time (UTC-3:00) for routes beginning in the Eastern Time Zone and 10:00 a.m. Central Standard Time (UTC-4:00) for routes beginning in the Central Time Zone. The start times are offset by one hour in UTC. The arrive and depart times and dates recorded in the output Stops feature class will refer to the local time zone of the first stop for each route.UTC-The Time of Day parameter refers to Coordinated Universal Time (UTC). Choose this option if you want to generate a route for a specific time, such as now, but aren’t certain in which time zone the first stop will be located. If you are generating many routes spanning multiple times zones, the start times in UTC are simultaneous. For example, a Time of Day value of 10:00 a.m., 2 January, would mean a start time of 5:00 a.m. Eastern Standard Time (UTC-5:00) for routes beginning in the Eastern Time Zone and 4:00 a.m. Central Standard Time (UTC-6:00) for routes beginning in the Central Time Zone. Both routes would start at 10:00 a.m. UTC. The arrive and depart times and dates recorded in the output Stops feature class will refer to UTC.

Choice list: [‘Geographically Local’, ‘UTC’]

uturn_at_junctions

Optional string. Use this parameter to restrict or permit the service area to make U-turns at junctions. In order to understand the parameter values, consider for a moment the following terminology: a junction is a point where a street segment ends and potentially connects to one or more other segments; a pseudo-junction is a point where exactly two streets connect to one another; an intersection is a point where three or more streets connect; and a dead-end is where one street segment ends without connecting to another. Given this information, the parameter can have the following values:

 Parameter Description ALLOW_UTURNS U-turns are permitted everywhere. Allowing U-turns implies that the vehicle can turn around at a junction or intersection and double back on the same street. ALLOW_DEAD_ENDS_AND _INTERSECTIONS_ONLY U-turns are prohibited at junctions where exactly two adjacent streets meet. ALLOW_DEAD_ENDS_ONLY U-turns are prohibited at all junctions and interesections nd are permitted only at dead ends. NO_UTURNS U-turns are prohibited at all junctions, intersections, and dead-ends. Note that even when this parameter value is chosen, a route can still make U-turns at stops. If you wish to prohibit U-turns at a stop, you can set its CurbApproach property to the appropriate value (3). The default value for this parameter is ‘ALLOW_UTURNS’.

point_barriers

Optional FeatureSet. Specify one or more points to 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 time delay spent at a railroad crossing.

The tool imposes a limit of 250 points that can be added as barriers. When specifying the point barriers, you can set properties for each one, such as its name or barrier type, by using attributes. The point barriers can be specified with 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 or Additional_Distance field. This barrier type is referred to as an added-cost point barrier.

• Additional_Time: Indicates how much travel time is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the measurement units are time based. 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: Indicates how much distance is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the measurement units are distance based. 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: Indicates how much cost is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the travel mode used for the analysis uses an impedance attribute that is neither time-based or distance-based.

• FullEdge: Specify 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.

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

The CurbApproach property was designed to work with both kinds 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, you would choose Right side of vehicle (1) in the United States but Left side of vehicle (2) 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 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 ArcGIS Network Analyst extension 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 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 time 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 time units of NavLatency are the same as the units specified by the timeUnits property of the analysis object.

line_barriers

Optional FeatureSet. 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 on 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 a name property for each one by using the following attribute:

• Name: The name of the barrier.

polygon_barriers

Optional FeatureSet. 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 on the number of polygons you can specify as the polygon barriers, the combined number of streets intersected by all the polygons should not exceed 2,000. When specifying the polygon barriers, you can set properties for each one, such as its name or barrier type, by using attributes. The polygon barriers can be specified with the following attributes:

• Name: The name of the barrier.

• BarrierType: Specifies whether the barrier restricts travel completely or scales the 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 time or distance required to travel the underlying streets by a factor specified using the ScaledTimeFactor or ScaledDistanceFactor fields. If the streets are partially covered by the barrier, the travel time or distance is apportioned and then scaled. For example, a factor 0.25 would mean that travel on underlying streets is expected to be four times faster than normal. A factor of 3.0 would mean 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 might be used to model storms that reduce travel speeds in specific regions.

• ScaledTimeFactor: This is the factor by which the travel time of the streets intersected by the barrier is multiplied. This field is applicable only for scaled-cost barriers and only if the measurement units are time based. The field value must be greater than zero.

• ScaledDistanceFactor: This is the factor by which the distance of the streets intersected by the barrier is multiplied. This attribute is applicable only for scaled-cost barriers and only if the measurement units are distance based. The attribute value must be greater than zero.

• 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 and only if the travel mode used for the analysis uses an impedance attribute that is neither time based nor distance based.

use_hierarchy

Optional boolean. Specify whether hierarchy should be used when finding the best routes.

Checked (True) - Use hierarchy when finding routes. When hierarchy is used, the tool prefers higher-order streets, such as freeways, to 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 true when finding routes to faraway locations, 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 has to select the best route from a relatively smaller subset of streets.

Unchecked (False) - Do not use hierarchy when finding routes. If hierarchy is not used, the tool considers all the streets and doesn’t prefer higher-order streets when finding the route. This is often used when finding short-distance routes within a city.

The tool automatically reverts to using hierarchy if the straight-line distance between orders, depots, or orders and depots is greater than 50 miles, even if you have set this parameter to not use hierarchy. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value.

restrictions

Optional string. Specify which restrictions should be honored by the tool when finding the best routes. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value. A restriction represents a driving preference or requirement. In most cases, restrictions cause roads to be prohibited. For instance, using an Avoid Toll Roads restriction will result in a route that will include roads only when it is absolutely required to travel on toll roads in order 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 as illegal to do so.

Below is a list of available restrictions and a short description. Some restrictions require an additional value to be specified for their desired use. This value needs to 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 under 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.

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 check whether the restriction is available in a particular country by looking at the table in the Country List section of the Data coverage for network analysis services web page. 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 whose Restriction Usage parameter value is between 0 and 1 (see the Attribute Parameter Value parameter). It prohibits all restrictions whose Restriction Usage parameter value is greater than 0.

Choice list:[‘Any Hazmat Prohibited’, ‘Avoid Carpool Roads’, ‘Avoid Express Lanes’, ‘Avoid Ferries’, ‘Avoid Gates’, ‘Avoid Limited Access Roads’, ‘Avoid Private Roads’, ‘Avoid Roads Unsuitable for Pedestrians’, ‘Avoid Stairways’, ‘Avoid Toll Roads’, ‘Avoid Toll Roads for Trucks’, ‘Avoid Truck Restricted Roads’, ‘Avoid Unpaved Roads’, ‘Axle Count Restriction’, ‘Driving a Bus’, ‘Driving a Delivery Vehicle’, ‘Driving a Taxi’, ‘Driving a Truck’, ‘Driving an Automobile’, ‘Driving an Emergency Vehicle’, ‘Height Restriction’, ‘Kingpin to Rear Axle Length Restriction’, ‘Length Restriction’, ‘Preferred for Pedestrians’, ‘Riding a Motorcycle’, ‘Roads Under Construction Prohibited’, ‘Semi or Tractor with One or More Trailers Prohibited’, ‘Single Axle Vehicles Prohibited’, ‘Tandem Axle Vehicles Prohibited’, ‘Through Traffic Prohibited’, ‘Truck with Trailers Restriction’, ‘Use Preferred Hazmat Routes’, ‘Use Preferred Truck Routes’, ‘Walking’, ‘Weight Restriction’, ‘Weight per Axle Restriction’, ‘Width Restriction’]

The service supports the restriction names listed in the following table:

attribute_parameter_values

Optional FeatureSet. Specify additional values required by some restrictions, such as the weight of a vehicle for Weight Restriction. You can also use the attribute parameter to specify whether any restriction prohibits, avoids, or prefers travel on roads that use the restriction. 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 even highly prefer them. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value. If you specify the Attribute Parameter Values parameter from a feature class, the field names on the feature class must match the fields as described below:

• AttributeName: Lists the name of the restriction.

• ParameterName: Lists 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.

Attribute Parameter Values 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 and 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 within the parentheses:

• PROHIBITED (-1) - Travel on the roads using the restriction is completely prohibited.

• AVOID_HIGH (5) - It is highly unlikely for the tool to include in the route the roads that are associated with the restriction.

• AVOID_MEDIUM (2) - It is unlikely for the tool to include in the route the roads that are associated with the restriction.

• AVOID_LOW (1.3) - It is somewhat unlikely for the tool to include in the route the roads that are associated with the restriction.

• PREFER_LOW (0.8) - It is somewhat likely for the tool to include in the route the roads that are associated with the restriction.

• PREFER_MEDIUM (0.5) - It is likely for the tool to include in the route the roads that are associated with the restriction.

• PREFER_HIGH (0.2) - It is highly likely for the tool to include in the route the roads that are associated with the restriction.

In most cases, you can use the default value, PROHIBITED, for the Restriction Usage if the restriction is dependent on a vehicle-characteristic such as vehicle height. However, in some cases, the value for Restriction Usage depends on your routing preferences. For example, the Avoid Toll Roads restriction has the default value of AVOID_MEDIUM for the Restriction Usage parameter. 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 would put lower importance on avoiding tolls; choosing AVOID_HIGH instead would give it a higher importance and thus make it more acceptable for the service to generate longer routes to avoid tolls. Choosing PROHIBITED would entirely disallow 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, you would 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.

 AttributeName ParameterName ParameterValue Any Hazmat Prohibited Restriction Usage PROHIBITED Avoid Carpool Roads Restriction Usage PROHIBITED Avoid Express Lanes Restriction Usage PROHIBITED Avoid Ferries Restriction Usage AVOID_MEDIUM Avoid Gates Restriction Usage AVOID_MEDIUM Avoid Limited Access Roads Restriction Usage AVOID_MEDIUM Avoid Private Roads Restriction Usage AVOID_MEDIUM Avoid Roads Unsuitable for Pedestrians Restriction Usage AVOID_HIGH Avoid Stairways Restriction Usage AVOID_HIGH Avoid Toll Roads Restriction Usage AVOID_MEDIUM Avoid Toll Roads for Trucks Restriction Usage AVOID_MEDIUM Avoid Truck Restricted Roads Restriction Usage AVOID_HIGH Avoid Unpaved Roads Restriction Usage AVOID_HIGH Axle Count Restriction Number of Axles Restriction Usage 0 PROHIBITED Driving a Bus Restriction Usage PROHIBITED Driving a Taxi Restriction Usage PROHIBITED Driving a Truck Restriction Usage PROHIBITED Driving an Automobile Restriction Usage PROHIBITED Driving an Emergency Vehicle Restriction Usage PROHIBITED Height Restriction Restriction Usage Vehicle Height (meters) PROHIBITED 0 Kingpin to Rear Axle Restriction Usage PROHIBITED Length Restriction Vehicle Kingpin to Rear Axle Length (meters) 0 Length Restriction Restriction Usage Vehicle Length (meters) PROHIBITED 0 Preferred for Pedestrians Restriction Usage PREFER_LOW Riding a Motorcycle Restriction Usage PROHIBITED Roads Under Construction Prohibited Restriction Usage PROHIBITED Semi or Tractor with One Restriction Usage PROHIBITED or more trailers prohibited Single Axle Vehicles Prohibited Restriction Usage PROHIBITED Tandem Axle Vehicles Prohibited Restriction Usage PROHIBITED Through Traffic Prohibited Restriction Usage AVOID_HIGH Truck with Trailers Restriction Restriction Usage Number of Trailers on Truck PROHIBITED 0 Use Preferred Hazmat Routes Restriction Usage PREFER_MEDIUM Use Preferred Truck Routes Restriction Usage PREFER_HIGH Walking Restriction Usage PROHIBITED WalkTime Walking Speed (km/h) 5 Weight Restriction Restriction Usage Vehicle Weight (kilograms) PROHIBITED 0 Weight per Axle Restriction Restriction Usage Vehicle Weight per Axle (kilograms) PROHIBITED 0 Width Restriction Restriction Usage Vehicle Width (meters) PROHIBITED 0

route_shape

Optional string. Specify the type of route features that are output by the tool. The parameter can be specified using one of the following values:

• True Shape - Return the exact shape of the resulting route that is based on the underlying streets.

• Straight Line - Return a straight line between the incident and the facility.

• None - Do not return any shapes for the routes. This value can be useful in cases where you are only interested in determining the total travel time or travel distance between the closest facility and the incident.

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

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 incidents and facilities. This means that only the route shapes are different, not the underlying streets that are searched when finding the route.

Choice list: [‘True Shape’, ‘Straight Line’, ‘None’]

route_line_simplif ication_tolerance

Optional LinearUnit. Specify by how much you want to simplify the geometry of the output lines for routes and directions. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value. The tool also ignores this parameter if the populate_route_lines parameter is unchecked (False). 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.

populate_route_edges

Optional boolean. Specify whether the tool should 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.

Checked (True) - Generate route edges. The output Route Edges layer is populated with line features.

Unchecked (False) - Don’t generate route edges. The output Route Edges layer is returned, but it is empty.

populate_directions

Optional boolean. Specify whether the tool should generate driving directions for each route. Checked (True): Indicates that the directions will be generated and configured based on the values for the Directions Language, Directions Style Name, and Directions Distance Units parameters. Unchecked (False): Directions are not generated, and the tool returns an empty Directions layer.

directions_language

Optional string. Specify the language that should be used when generating driving directions. This parameter is used only when the populate_directions parameter is checked, or set to True. The parameter value can be specified using one of the following two- or five-character language codes: ar-Arabic cs-Czech de-German el-Greek en-English es-Spanish et-Estonian fr-French he-Hebrew it-Italian ja-Japanese ko-Korean lt-Lithuanian lv-Latvian nl-Dutch pl-Polish pt-BR-Brazilian Portuguese pt-PT-European Portuguese ru-Russian sv-Swedish th-Thai tr-Turkish zh-CN-Simplified Chinese

If an unsupported language code is specified, the tool returns the directions using the default language, English.

directions_distance_units

Optional string. Specify the units for displaying travel distance in the driving directions. This parameter is used only when the Populate Directions parameter is checked, or set to True.

Choice list: [‘Meters’, ‘Kilometers’, ‘Feet’, ‘Yards’, ‘Miles’, ‘NauticalMiles’]

directions_style_name

Optional string. Specify the name of the formatting style for the directions. This parameter is used only when the Populate Directions parameter is checked, or set to True. The parameter can be specified using the following values:

NA Desktop: Generates turn-by-turn directions suitable for printing. NA Navigation: Generates turn-by-turn directions designed for an in-vehicle navigation device.

travel_mode

Optional string. Specify 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 better reflect your organization’s workflows. You need to specify the name of a travel mode supported by your organization.

To get a list of supported travel mode names, run the GetTravelModes tool from the Utilities toolbox available under the same GIS Server connection you used to access the tool. The GetTravelModes 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 Travel Mode Settings field as input. This speeds up the tool execution as the tool does not have to lookup 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 travelling by car. You may want to 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 may choose to do this to try out different settings to get desired analysis results. Once you have identified the analysis settings, you should work with your organization’s administrator and save these settings as part of new or existing travel mode so that everyone in your organization can rerun the analysis with the same settings.

impedance

Optional string. Specify 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 taking one minute to travel a mile along an empty road is an example of impedance. 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. Choose from the following impedance values: Drive Time-Models travel times for a car. These travel times are static for each road and don’t fluctuate with traffic. Truck Time-Models travel times for a truck. These travel times are static for each road and don’t fluctuate with traffic. Walk Time-Models travel times for a pedestrian. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value.

Choice list:[‘Drive Time’, ‘Truck Time’, ‘Walk Time’]

The default value is ‘Drive Time’.

gis

Optional GIS. The GIS on which this tool runs. If not specified, the active GIS is used.

time_zone_usage_for _time_windows

Optional string. Specifies the time zone for the input date-time fields supported by the tool. This parameter specifies the time zone for the following fields: TimeWindowStart1, TimeWindowEnd1, TimeWindowStart2, TimeWindowEnd2, InboundArriveTime, and OutboundDepartTime on orders. TimeWindowStart1, TimeWindowEnd1, TimeWindowStart2, and TimeWindowEnd2 on depots. EarliestStartTime and LatestStartTime on routes. TimeWindowStart and TimeWindowEnd on breaks.

Choice list:[‘UTC’, ‘GEO_LOCAL’]

GEO_LOCAL: The date-time values associated with the orders or depots are in the time zone in which the orders and depots are located. For routes, the date-time values are based on the time zone in which the starting depot for the route is located. If a route does not have a starting depot, all orders and depots across all the routes must be in a single time zone. For breaks, the date-time values are based on the time zone of the routes. For example, if your depot is located in an area that follows eastern standard time and has the first time window values (specified as TimeWindowStart1 and TimeWindowEnd1) of 8 AM and 5 PM, the time window values will be treated as 8:00 a.m. and 5:00 p.m. eastern standard time.

UTC: The date-time values associated with the orders or depots are in the in coordinated universal time (UTC) and are not based on the time zone in which the orders or depots are located. For example, if your depot is located in an area that follows eastern standard time and has the first time window values (specified as TimeWindowStart1 and TimeWindowEnd1) of 8 AM and 5 PM, the time window values will be treated as 12:00 p.m. and 9:00 p.m. eastern standard time assuming the eastern standard time is obeying the daylight saving time. Specifying the date-time values in UTC is useful if you do not know the time zone in which the orders or depots are located or when you have orders and depots in multiple time zones, and you want all the date-time values to start simultaneously. The UTC option is applicable only when your network dataset defines a time zone attribute. Otherwise, all the date-time values are always treated as GEO_LOCAL.

save_output_na_layer

Optional bolean. Specify if the tool should save the analysis settings as a network analysis layer file. You cannot directly work with this file even when you open the file in an ArcGIS Desktop application like ArcMap. It is meant to be sent to Esri Technical Support to diagnose the quality of results returned from the tool.

Checked (True) - Save the network analysis layer file. The file is downloaded in 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 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 Network Analysis Layer parameter in the entry corresponding to the tool execution in the Geoprocessing Results window.

Unchecked (False)-Do not save the network analysis layer file. This is the default.

overrides

Optional string. Specify additional settings that can influence the behavior of the solver when finding solutions for the network analysis problems. The value for this parameter needs to 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 a 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. A list of supported override settings for each solver and their acceptable values can be obtained by contacting Esri Technical Support.

save_route_data

Optional boolean. Choose whether the output includes a zip file that contains a file geodatabase holding 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. True: Save the route data as a zip file. The file is downloaded in 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 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 Route Data parameter in the entry corresponding to the tool execution in the Geoprocessing Results window. False: Do not save the route data. This is the default.

time_impedance

Optional string. Specify the time-based impedance, which is a value that represents the travel time along road segments or on other parts of the transportation network.If the impedance for the travel mode, as specified using the impedance parameter, is time-based, the value for time_impedance and impedance parameters should be identical. Otherwise the service will return an error.

Choice list:[‘Minutes’, ‘TravelTime’, ‘TimeAt1KPH’, ‘WalkTime’, ‘TruckMinutes’, ‘TruckTravelTime’]

distance_impedance

Optional string. Specify the distance-based impedance, which is a value that represents the travel distance along road segments or on other parts of the transportation network.If the impedance for the travel mode, as specified using the impedance parameter, is distance-based, the value for distance_impedance and impedance parameters should be identical. Otherwise the service will return an error.

Choice list:[‘Miles’, ‘Kilometers’]

output_format

Optional. Specify the format in which the output features are created.

Choose from the following formats:

• Feature Set - The output features are returned as feature classes and tables. This is the default.

• JSON File - The output features are 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 File - The output features are 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.

gis

Optional, the GIS on which this tool runs. If not specified, the active GIS is used.

future

Optional, If True, a future object will be returns and the process will not wait for the task to complete. The default is False, which means wait for results.

: returns: the following as a named tuple:

• solve_succeeded - Solve Succeeded as a bool

• output_routes - Output Routes as a FeatureSet

• output_route_edges - Output Route Edges as a FeatureSet

• output_directions - Output Directions as a FeatureSet

• output_stops - Output Stops as a FeatureSet

• output_network_analysis_layer - Output Network Analysis Layer as a DataFile

• output_route_data - Output Route Data as a DataFile

• output_result_file - Output Result File as a DataFile

generate_service_areas¶

arcgis.network.analysis.generate_service_areas(facilities: arcgis.features.feature.FeatureSet, break_values: str = '5 10 15', break_units: str = 'Minutes', analysis_region: str = None, travel_direction: str = 'Away From Facility', time_of_day: datetime.datetime = None, use_hierarchy: bool = False, uturn_at_junctions: str = 'Allowed Only at Intersections and Dead Ends', polygons_for_multiple_facilities: str = 'Overlapping', polygon_overlap_type: str = 'Rings', detailed_polygons: bool = False, polygon_trim_distance: arcgis.geoprocessing._types.LinearUnit = None, polygon_simplification_tolerance: arcgis.geoprocessing._types.LinearUnit = None, point_barriers: arcgis.features.feature.FeatureSet = None, line_barriers: arcgis.features.feature.FeatureSet = None, polygon_barriers: arcgis.features.feature.FeatureSet = None, restrictions: str = None, attribute_parameter_values: arcgis.features.feature.FeatureSet = None, time_zone_for_time_of_day: str = 'Geographically Local', travel_mode: str = 'Custom', impedance: str = 'Drive Time', save_output_network_analysis_layer=False, overrides=None, time_impedance=None, distance_impedance=None, polygon_detail=None, output_type=None, output_format=None, gis=None, future=False) → tuple

This generate_service_areas tool determines network service areas around facilities. A network service area is a region that encompasses all streets that can be accessed within a given distance or travel time from one or more facilities. For instance, the 10-minute service area for a facility includes all the streets that can be reached within 10 minutes from that facility. Service areas are commonly used to visualize and measure accessibility. For example, a three-minute drive-time polygon around a grocery store can determine which residents are able to reach the store within three minutes and are thus more likely to shop there.

Argument

Description

facilities

Required FeatureSet. The facilities around which service areas are generated. You can load up to 1,000 facilities. The facilities feature set has an associated attribute table. The fields in the attribute table are listed and described below:

• ObjectID: The system-managed ID field.

• Name: The name of the facility. If the name is not specified, a name is automatically generated at solve time.

All fields from the input facilities are included in the output polygons when the Polygons for Multiple Facilities parameter is set to Overlapping or Not Overlapping. The ObjectID field on the input facilities is transferred to the FacilityOID field on the output polygons.

break_values

Required string. Specifies the size and number of service area polygons to generate for each facility. The units are determined by the Break Units value.

Multiple polygon breaks can be set to create concentric service areas per facility. For instance, to find 2-, 3-, and 5-mile service areas for each facility, type 2 3 5, separating the values with a space, and set Break Units to Miles. There is no limit to the number of break values you specify.

The size of the maximum break value can’t exceed the equivalent of 300 minutes or 300 miles (482.80 kilometers). When generating detailed polygons, the maximum service-area size is limited to 15 minutes and 15 miles (24.14 kilometers).

break_units

Required string. The unit for the Break Values parameter. The units you choose for this parameter determine whether the tool will create service areas by measuring driving distance or driving time. Choose a time unit to measure driving time. To measure driving distance, choose a distance unit. Your choice also determines in which units the tool will report total driving time or distance in the results. The choices are: Meters Kilometers Feet Yards Miles Nautical Miles Seconds Minutes Hours Days

Choice list: [‘Meters’, ‘Kilometers’, ‘Feet’, ‘Yards’, ‘Miles’, ‘Nautical Miles’, ‘Seconds’, ‘Minutes’, ‘Hours’, ‘Days’]

analysis_region

Optional string. Specify the region in which to perform the analysis. 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 recommended to speed up the tool execution.

Choice list: [‘NorthAmerica’, ‘SouthAmerica’, ‘Europe’, ‘MiddleEastAndAfrica’, ‘India’, ‘SouthAsia’, ‘SouthEastAsia’, ‘Thailand’, ‘Taiwan’, ‘Japan’, ‘Oceania’, ‘Greece’, ‘Korea’]

travel_direction

Optional string. Specifies whether the direction of travel used to generate the service area polygons is toward or away from the facilities.

• Away From Facility - The service area is generated in the direction away from the facilities.

• Towards Facility - The service area is created in the direction towards the facilities.

The direction of travel may change the shape of the polygons because impedances on opposite sides of streets may differ or one-way restrictions may exist, such as one-way streets. The direction you should choose depends on the nature of your service area analysis. The service area for a pizza delivery store, for example, should be created away from the facility, whereas the service area of a hospital should be created toward the facility.

Choice list: [‘Away From Facility’, ‘Towards Facility’]

time_of_day

Optional datetime. The time to depart from or arrive at the facilities. The interpretation of this value depends on whether travel is toward or away from the facilities. It represents the departure time if Travel Direction is set to Away from Facility. It represents the arrival time if Travel Direction is set to Toward Facility.

You can use the Time Zone for Time of Day parameter to specify whether this time and date refers to UTC or the time zone in which the facility is located.

Repeatedly solving the same analysis, but using different Time of Day values, allows you to see how a facility’s reach changes over time. For instance, the five-minute service area around a fire station may start out large in the early morning, diminish during the morning rush hour, grow in the late morning, and so on, throughout the day.

use_hierarchy

Optional boolean. Specify whether hierarchy should be used when finding the best route between the facility and the incident.

Checked (True) - Use the hierarchy attribute for the analysis. Using a hierarchy results in the solver preferring higher-order edges to lower-order edges. Hierarchical solves are faster, and they can be used to simulate the preference of a driver who chooses to travel on freeways over local roads when possible-even if that means a longer trip.

Unchecked (False) - Do not use the hierarchy attribute for the analysis. Not using a hierarchy yields an accurate service area measured along all edges of the network dataset regardless of hierarchy level.

Regardless of whether the Use Hierarchy parameter is checked (True), hierarchy is always used when the largest break value exceeds 240 minutes or 240 miles (386.24 kilometers).

uturn_at_junctions

Optional string. Use this parameter to restrict or permit the service area to make U-turns at junctions. In order to understand the parameter values, consider for a moment the following terminology: a junction is a point where a street segment ends and potentially connects to one or more other segments; a pseudo-junction is a point where exactly two streets connect to one another; an intersection is a point where three or more streets connect; and a dead-end is where one street segment ends without connecting to another. Given this information, the parameter can have the following values:

 Parameter Description ALLOW_UTURNS U-turns are permitted everywhere. Allowing U-turns implies that the vehicle can turn around at a junction or intersection and double back on the same street. ALLOW_DEAD_ENDS_AND _INTERSECTIONS_ONLY U-turns are prohibited at junctions where exactly two adjacent streets meet. ALLOW_DEAD_ENDS_ONLY U-turns are prohibited at all junctions and interesections and are permitted only at dead ends. NO_UTURNS U-turns are prohibited at all junctions, intersections, and dead-ends. Note that even when this parameter value is chosen, a route can still make U-turns at stops. If you wish to prohibit U-turns at a stop, you can set its CurbApproach property to the appropriate value (3). The default value for this parameter is ‘ALLOW_UTURNS’.

Choice list: [‘Allowed’, ‘Not Allowed’, ‘Allowed Only at Dead Ends’, ‘Allowed Only at Intersections and Dead Ends’]

polygons_for_multiple_facilities

Optional string. Choose how service area polygons are generated when multiple facilities are present in the analysis.

• Overlapping - Creates individual polygons for each facility. The polygons can overlap each other. This is the default value.

• Not Overlapping - Creates individual polygons such that a polygon from one facility cannot overlap polygons from other facilities; furthermore, any portion of the network can only be covered by the service area of the nearest facility.

• Merge by Break Value - Creates and joins the polygons of different facilities that have the same break value.

When using Overlapping or Not Overlapping, all fields from the input facilities are included in the output polygons, with the exception that values from the input ObjectID field are transferred to the FacilityOID field of the output polygons. The FacilityOID field is null when merging by break value, and the input fields are not included in the output.

Choice list: [‘Overlapping’, ‘Not Overlapping’, ‘Merge by Break Value’]

polygon_overlap_type

Optional string. Specifies the option to create concentric service area polygons as disks or rings. This option is applicable only when multiple break values are specified for the facilities.

• Rings - The polygons representing larger breaks exclude the polygons of smaller breaks. This creates polygons going between consecutive breaks. Use this option if you want to find the area from one break to another. For instance, if you create 5- and 10-minute service areas, then the 10-minute service area polygon will exclude the area under the 5-minute service area polygon. This is the default value.

• Disks - Creates polygons going from the facility to the break. For instance, if you create 5- and 10-minute service areas, then the 10-minute service area polygon will include the area under the 5-minute service area polygon.

Choice list: [‘Rings’, ‘Disks’]

detailed_polygons

Optional boolean. Specifies the option to create detailed or generalized polygons.

Unchecked (False) - Creates generalized polygons, which are generated quickly and are fairly accurate. This is the default.

Checked (True) - Creates detailed polygons, which accurately model the service area lines and may contain islands of unreached areas. This option is much slower than generating generalized polygons. This option isn’t supported when using hierarchy. If your facilities are in an urban area with a grid-like street network, the difference between generalized and detailed service areas would be minimal. However, if your facilities are in a region containing mountain and rural roads, the detailed service areas may present significantly more accurate results than generalized service areas.

The tool supports generating detailed polygons only if the largest value specified in the Break Values parameter is less than or equal to 15 minutes or 15 miles (24.14 kilometers).

polygon_trim_distance

Optional LinearUnit. Specifies the distance within which the service area polygons are trimmed. This is useful when finding service areas in places that have a sparse street network and you don’t want the service area to cover large areas where there are no street features.

The default value is 100 meters. No value or a value of 0 for this parameter specifies that the service area polygons should not be trimmed. This parameter value is ignored when using hierarchy.

polygon_simplification_tolerance

Optional LinearUnit. Specify by how much you want to simplify the polygon geometry.

Simplification maintains critical vertices of a polygon to define its essential shape and removes other vertices. The simplification distance you specify is the maximum offset the simplified polygon boundaries can deviate from the original polygon boundaries. Simplifying a polygon reduces the number of vertices and tends to reduce drawing times.

point_barriers

Optional FeatureSet. Specify one or more points to 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 time delay spent at a railroad crossing.

The tool imposes a limit of 250 points that can be added as barriers. When specifying the point barriers, you can set properties for each one, such as its name or barrier type, by using attributes. The point barriers can be specified with 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 or Additional_Distance field. This barrier type is referred to as an added-cost point barrier.

• Additional_Time: Indicates how much travel time is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the Break Units value is time based. This field value must be greater than or equal to zero, and its units are the same as those specified in the Break Units parameter.

• Additional_Distance: Indicates how much distance is added when the barrier is traversed. This field is applicable only for added-cost barriers and only if the Break Units value is distance based. The field value must be greater than or equal to zero, and its units are the same as those specified in the Break Units parameter.

line_barriers

Optional FeatureSet. 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 on 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 a name property for each one by using the following attribute:

• Name: The name of the barrier.

polygon_barriers

Optional FeatureSet. 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 on the number of polygons you can specify as the polygon barriers, the combined number of streets intersected by all the polygons should not exceed 2,000. When specifying the polygon barriers, you can set properties for each one, such as its name or barrier type, by using attributes. The polygon barriers can be specified with the following attributes:

• Name: The name of the barrier.

• BarrierType: Specifies whether the barrier restricts travel completely or scales the 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 time or distance required to travel the underlying streets by a factor specified using the ScaledTimeFactor or ScaledDistanceFactor fields. If the streets are partially covered by the barrier, the travel time or distance is apportioned and then scaled. For example, a factor 0.25 would mean that travel on underlying streets is expected to be four times faster than normal. A factor of 3.0 would mean 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 might be used to model storms that reduce travel speeds in specific regions.

• ScaledTimeFactor: This is the factor by which the travel time of the streets intersected by the barrier is multiplied. This field is applicable only for scaled-cost barriers and only if the measurement units are time based. The field value must be greater than zero.

• ScaledDistanceFactor: This is the factor by which the distance of the streets intersected by the barrier is multiplied. This attribute is applicable only for scaled-cost barriers and only if the measurement units are distance based. The attribute value must be greater than zero.

restrictions

Optional string. Specify which restrictions should be honored by the tool when finding the best routes between facilities and demand points. A restriction represents a driving preference or requirement. In most cases, restrictions cause roads to be prohibited. For instance, using an Avoid Toll Roads restriction will result in a route that will include toll roads only when it is absolutely required to travel on toll roads in order 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 as illegal to do so. Below is a list of available restrictions and a short description. Some restrictions require an additional value to be specified for their desired use. This value needs to 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 under 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. 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 check whether the restriction is available in a particular country by looking at the table in the Country List section of the Data coverage for network analysis services web page. 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 whose Restriction Usage parameter value is between 0 and 1 (see the Attribute Parameter Value parameter). It prohibits all restrictions whose Restriction Usage parameter value is greater than 0. The service supports the restriction names listed in the following table:

Choice list: [‘Any Hazmat Prohibited’, ‘Avoid Carpool Roads’, ‘Avoid Express Lanes’, ‘Avoid Ferries’, ‘Avoid Gates’, ‘Avoid Limited Access Roads’, ‘Avoid Private Roads’, ‘Avoid Roads Unsuitable for Pedestrians’, ‘Avoid Stairways’, ‘Avoid Toll Roads’, ‘Avoid Toll Roads for Trucks’, ‘Avoid Truck Restricted Roads’, ‘Avoid Unpaved Roads’, ‘Axle Count Restriction’, ‘Driving a Bus’, ‘Driving a Delivery Vehicle’, ‘Driving a Taxi’, ‘Driving a Truck’, ‘Driving an Automobile’, ‘Driving an Emergency Vehicle’, ‘Height Restriction’, ‘Kingpin to Rear Axle Length Restriction’, ‘Length Restriction’, ‘Preferred for Pedestrians’, ‘Riding a Motorcycle’, ‘Roads Under Construction Prohibited’, ‘Semi or Tractor with One or More Trailers Prohibited’, ‘Single Axle Vehicles Prohibited’, ‘Tandem Axle Vehicles Prohibited’, ‘Through Traffic Prohibited’, ‘Truck with Trailers Restriction’, ‘Use Preferred Hazmat Routes’, ‘Use Preferred Truck Routes’, ‘Walking’, ‘Weight Restriction’, ‘Weight per Axle Restriction’, ‘Width Restriction’]

attribute_parameter_values

Optional FeatureSet. Specify additional values required by some restrictions, such as the weight of a vehicle for Weight Restriction. You can also use the attribute parameter to specify whether any restriction prohibits, avoids, or prefers travel on roads that use the restriction. 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 even highly prefer them.

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 described below:

• AttributeName: Lists the name of the restriction.

• ParameterName: Lists 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.

Attribute Parameter Values 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 and 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 within the parentheses:

PROHIBITED (-1) - Travel on the roads using the restriction is completely prohibited.

AVOID_HIGH (5) - It is highly unlikely for the tool to include in the route the roads that are associated with the restriction.

AVOID_MEDIUM (2) - It is unlikely for the tool to include in the route the roads that are associated with the restriction.

AVOID_LOW (1.3) - It is somewhat unlikely for the tool to include in the route the roads that are associated with the restriction.

PREFER_LOW (0.8) - It is somewhat likely for the tool to include in the route the roads that are associated with the restriction.

PREFER_MEDIUM (0.5) - It is likely for the tool to include in the route the roads that are associated with the restriction.

PREFER_HIGH (0.2) - It is highly likely for the tool to include in the route the roads that are associated with the restriction.

In most cases, you can use the default value, PROHIBITED, for the Restriction Usage if the restriction is dependent on a vehicle-characteristic such as vehicle height. However, in some cases, the value for Restriction Usage depends on your routing preferences. For example, the Avoid Toll Roads restriction has the default value of AVOID_MEDIUM for the Restriction Usage parameter. 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 would put lower importance on avoiding tolls; choosing AVOID_HIGH instead would give it a higher importance and thus make it more acceptable for the service to generate longer routes to avoid tolls. Choosing PROHIBITED would entirely disallow 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, you would 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.

time_zone_for_time_of_day

Optional string. Specifies the time zone or zones of the Time of Day parameter.

• Geographically Local: The Time of Day parameter refers to the time zone or zones in which the facilities are located. Therefore, the start or end times of the service areas are staggered by time zone. Setting Time of Day to 9:00 a.m., choosing geographically local for Time Zone for Time of Day, and solving causes service areas to be generated for 9:00 a.m. Eastern Time for any facilities in the Eastern Time Zone, 9:00 a.m. Central Time for facilities in the Central Time Zone, 9:00 a.m. Mountain Time for facilities in the Mountain Time Zone, and so on, for facilities in different time zones. If stores in a chain that span the U.S. open at 9:00 a.m. local time, this parameter value could be chosen to find market territories at opening time for all stores in one solve. First, the stores in the Eastern Time Zone open and a polygon is generated, then an hour later stores open in Central Time, and so on. Nine o’clock is always in local time but staggered in real time.

• UTC: The Time of Day parameter refers to Coordinated Universal Time (UTC). Therefore, all facilities are reached or departed from simultaneously, regardless of the time zone each is in. Setting Time of Day to 2:00 p.m., choosing UTC, then solving causes service areas to be generated for 9:00 a.m. Eastern Standard Time for any facilities in the Eastern Time Zone, 8:00 a.m. Central Standard Time for facilities in the Central Time Zone, 7:00 a.m. Mountain Standard Time for facilities in the Mountain Time Zone, and so on, for facilities in different time zones. The scenario above assumes standard time. During daylight saving time, the Eastern, Central, and Mountain Times would each be one hour ahead (that is, 10:00, 9:00, and 8:00 a.m., respectively). One of the cases in which the UTC option is useful is to visualize emergency-response coverage for a jurisdiction that is split into two time zones. The emergency vehicles are loaded as facilities. Time of Day is set to now in UTC. (You need to determine what the current time and date are in terms of UTC to correctly use this option.) Other properties are set and the analysis is solved. Even though a time-zone boundary divides the vehicles, the results show areas that can be reached given current traffic conditions. This same process can be used for other times as well, not just for now.

Irrespective of the Time Zone for Time of Day setting, all facilities must be in the same time zone when Time of Day has a nonnull value and Polygons for Multiple Facilities is set to create merged or nonoverlapping polygons.

Choice list: [‘Geographically Local’, ‘UTC’]

travel_mode

Optional string. Specify 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 better reflect your organization’s workflows. You need to specify the name of a travel mode supported by your organization.

To get a list of supported travel mode names, run the GetTravelModes tool from the Utilities toolbox available under the same GIS Server connection you used to access the tool. The GetTravelModes 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 Travel Mode Settings field as input. This speeds up the tool execution as the tool does not have to lookup 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 travelling by car. You may want to 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 may choose to do this to try out different settings to get desired analysis results. Once you have identified the analysis settings, you should work with your organization’s administrator and save these settings as part of new or existing travel mode so that everyone in your organization can rerun the analysis with the same settings.

impedance

Optional string. Specify 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 distance is 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.) Travel time can also be an impedance; a car may take one 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. Choose from the following impedance values: Drive Time-Models travel times for a car. These travel times are dynamic and fluctuate according to traffic flows in areas where traffic data is available. This is the default value. Truck Time-Models travel times for a truck. These travel times are static for each road and don’t fluctuate with traffic. Walk Time-Models travel times for a pedestrian. Travel Distance-Stores length measurements along roads and paths. To model walk distance, choose this option and ensure Walking is set in the Restriction parameter. Similarly, to model drive or truck distance, choose Travel Distance here and set the appropriate restrictions so your vehicle travels only on roads where it is permitted to do so. The value you provide for this parameter is ignored unless Travel Mode is set to Custom, which is the default value. If you choose Drive Time, Truck Time, or Walk Time, the Measurement Units parameter must be set to a time-based value; if you choose Travel Distance for Impedance, Measurement Units must be distance-based.

Choice list:[‘Drive Time’, ‘Truck Time’, ‘Walk Time’, ‘Travel Distance’]

save_output_network_analysis_layer

Optional boolean. Specify if the tool should save the analysis settings as a network analysis layer file. You cannot directly work with this file even when you open the file in an ArcGIS Desktop application like ArcMap. It is meant to be sent to Esri Technical Support to diagnose the quality of results returned from the tool. True: Save the network analysis layer file. The file is downloaded in 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 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 Network Analysis Layer parameter in the entry corresponding to the tool execution in the Geoprocessing Results window. False: Do not save the network analysis layer file. This is the default.

overrides

Optional string. Specify additional settings that can influence the behavior of the solver when finding solutions for the network analysis problems. The value for this parameter needs to be specified in dict. For example, a valid value is of the following form {“overrideSetting1” : “value1”, “overrideSetting2” : “value2”}. The override setting name is always enclosed in double quotes. 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. A list of supported override settings for each solver and their acceptable values can be obtained by contacting Esri Technical Support.

time_impedance

Optional string. Specify the time-based impedance.

distance_impedence

Optional string. Specify the distance-based impedance.

polygon_detail

Optional string. Specify the detail of the polygon you want to create.

Choice list: [“Generalized”, “Standard”, “High”]

output_format

Optional. Specify the format in which the output features are created.

Choose from the following formats:

• Feature Set - The output features are returned as feature classes and tables. This is the default.

• JSON File - The output features are 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 File - The output features are 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.

gis

Optional, the GIS on which this tool runs. If not specified, the active GIS is used.

future

Optional boolean. If True, a GPJob is returned instead of results. The GPJob can be queried on the status of the execution.

: returns: the following as a named tuple:

• service_areas - Service Areas as a FeatureSet

• solve_succeeded - Solve Succeeded as a boolean

# Usage Example: To determine network service areas around facilities at time breaks of 5, 10, 15 min of drive time.

agg_result = generate_service_areas(facilities=facilities,
break_values=[5, 10, 15],
break_units="Minutes",
time_of_day=current_time)


get_travel_modes¶

arcgis.network.analysis.get_travel_modes(gis=None) → tuple

Get a list of travel modes that can be used with directions and routing services available in your portal.

Parameters:

gis: Optional, the GIS on which this tool runs. If not specified, the active GIS is used.

Returns the following as a named tuple:

supported_travel_modes - Supported Travel Modes as a FeatureSet default_travel_mode - Default Travel Mode as a str