arcgis.features.use_proximity module

Parameter

Description

destinations_layer

Required layer. The routes end at points in the destinations layer. See Feature Input.

origins_layer_route_id_field

Optional string. Specify the field in the origins layer containing the IDs that pair origins with destinations.

• The ID values must uniquely identify points in the origins layer

• Each ID value must also correspond with exactly one route ID value in the destinations layer. Route IDs that match across the layers create origin-destination pairs, which the tool connects together.

• Specifying origins_layer_route_id_field is optional when there is exactly one point feature in the origins or destinations layer. The tool will connect all origins to the one destination or the one origin to all destinations, depending on which layer contains one point.

time_of_day

Optional datetime.datetime. Specify whether travel times should consider traffic conditions. To use traffic in the analysis, set measurement_type to a travel mode object whose impedance_attribute_name property is set to travel_time and assign a value to time_of_day. (A travel mode with other impedance_attribute_name values don’t support traffic.) The time_of_day value represents the time at which travel begins, or departs, from the origin points. The time is specified as datetime.datetime.

The service supports two kinds of traffic: typical and live. Typical traffic references travel speeds that are made up of historical averages for each five-minute interval spanning a week. Live traffic retrieves speeds from a traffic feed that processes phone probe records, sensors, and other data sources to record actual travel speeds and predict speeds for the near future.

The data coverage page shows the countries Esri currently provides traffic data for.

Typical Traffic:

To ensure the task uses typical traffic in locations where it is available, choose a time and day of the week, and then convert the day of the week to one of the following dates from 1990:

• Monday - 1/1/1990

• Tuesday - 1/2/1990

• Wednesday - 1/3/1990

• Thursday - 1/4/1990

• Friday - 1/5/1990

• Saturday - 1/6/1990

• Sunday - 1/7/1990

Set the time and date as datetime.datetime.

For example, to solve for 1:03 p.m. on Thursdays, set the time and date to 1:03 p.m., 4 January 1990; and convert to datetime eg. datetime.datetime(1990, 1, 4, 1, 3).

Live Traffic:

To use live traffic when and where it is available, choose a time and date and convert to datetime.

Esri saves live traffic data for 4 hours and references predictive data extending 4 hours into the future. If the time and date you specify for this parameter is outside the 24-hour time window, or the travel time in the analysis continues past the predictive data window, the task falls back to typical traffic speeds.

# Examples: from datetime import datetime

• “time_of_day”: datetime(1990, 1, 4, 1, 3) # 13:03, 4 January 1990. Typical traffic on Thursdays at 1:03 p.m.

• “time_of_day”: datetime(1990, 1, 7, 17, 0) # 17:00, 7 January 1990. Typical traffic on Sundays at 5:00 p.m.

• “time_of_day”: datetime(2014, 10, 22, 8, 0) # 8:00, 22 October 2014. If the current time is between 8:00 p.m., 21 Oct. 2014 and 8:00 p.m., 22 Oct. 2014, live traffic speeds are referenced in the analysis; otherwise, typical traffic speeds are referenced.

• “time_of_day”: datetime(2015, 3, 18, 10, 20) # 10:20, 18 March 2015. If the current time is between 10:20 p.m., 17 Mar. 2015 and 10:20 p.m., 18 Mar. 2015, live traffic speeds are referenced in the analysis; otherwise, typical traffic speeds are referenced.

include_route_layers

Optional Boolean. When include_route_layers is set to True, each route from the result is also saved as a route layer item. A route layer includes all the information for a particular route such as the stops assigned to the route as well as the travel directions. Creating route layers is useful if you want to share individual routes with other members in your organization. The route layers use the output feature service name provided in the output_name parameter as a prefix and the route name generated as part of the analysis is added to create a unique name for each route layer.

Caution: Route layers cannot be created when the output is a feature collection. The task will raise an error if output_name is not specified (which indicates feature collection output) and include_route_layers is True.

The maximum number of route layers that can be created is 1,000. If the result contains more than 1,000 routes and include_route_layers is True, the task will only create the output feature service.

context

Optional dict. Additional settings such as processing extent and output spatial reference. For connect_origins_to_destinations, there are three settings.

• extent - a bounding box that defines the analysis area. Only those features in the input_layer that intersect the bounding box will be analyzed.

• outSR - the output features will be projected into the output spatial reference referred to by the wkid.

• overwrite - if True, then the feature layer in output_name will be overwritten with new feature layer. Available for ArcGIS Online or Enterprise 10.9.1+

  # Example Usage
  context = {"extent": {"xmin": 3164569.408035,
                      "ymin": -9187921.892449,
                      "xmax": 3174104.927313,
                      "ymax": -9175500.875353,
                      "spatialReference":{"wkid":102100,"latestWkid":3857}},
              "outSR": {"wkid": 3857},
              "overwrite": True}
  

estimate

Optional Boolean. Is True, the number of credits needed to run the operation will be returned as a float.

line_barrier_layer

Optional layer. Specify one or more line features that prohibit travel anywhere the lines intersect the streets.

A line barrier prohibits travel anywhere the barrier intersects the streets. For example, a parade or protest that blocks traffic across several street segments can be modeled with a line barrier. See Feature Input.

future

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

Parameter

Description

distances

Optional list of floats to buffer the input features. The distance(s) that will be buffered. You must supply values for either the distances or field parameter. You can enter a single distance value or multiple values. The units of the distance values is suppied by the units parameter.

units

Optional string. The linear unit to be used with the distance value(s) specified in distances or contained in the field value.

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

The default is ‘Meters’.

ring_type

Optional string. Determines how multiple-distance buffers are processed.

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

end_type

Optional string. The shape of the buffer at the end of line input features. This parameter is not valid for polygon input features. At the ends of lines the buffer can be rounded (Round) or be straight across (Flat).

Choice list: [‘Round’, ‘Flat’]

context

Optional dict. Additional settings such as processing extent and output spatial reference. For create_buffers, there are three settings.

• extent - a bounding box that defines the analysis area. Only those features in the input_layer that intersect the bounding box will be analyzed.

• outSR - the output features will be projected into the output spatial reference referred to by the wkid.

• overwrite - if True, then the feature layer in output_name will be overwritten with new feature layer. Available for ArcGIS Online or Enterprise 10.9.1+

  # Example Usage
  context = {"extent": {"xmin": 3164569.408035,
                      "ymin": -9187921.892449,
                      "xmax": 3174104.927313,
                      "ymax": -9175500.875353,
                      "spatialReference":{"wkid":102100,"latestWkid":3857}},
              "outSR": {"wkid": 3857},
              "overwrite": True}
  

estimate

Optional boolean. If True, the estimated number of credits required to run the operation will be returned.

Parameter

Description

travel_mode

Optional string or dict. Specify the mode of transportation for the analysis.

Choice list: [‘Driving Distance’, ‘Driving Time’, ‘Rural Driving Distance’, ‘Rural Driving Time’, ‘Trucking Distance’, ‘Trucking Time’, ‘Walking Distance’, ‘Walking Time’]

The default is ‘Driving Time’.

break_units

Optional string. The units of the break_values parameter.

To create areas showing how far you can go along roads or walkways within a given time, specify a time unit. Alternatively, specify a distance unit to generate areas bounded by a maximum travel distance.

When the travel_mode is time based, a time unit should be specified for the break_units. When the travel_mode is distance based, a distance unit should be specified for the break_units.

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

The default is ‘Minutes’.

time_of_day

Optional datetime.datetime. Specify whether travel times should consider traffic conditions. To use traffic in the analysis, set measurement_type to a travel mode object whose impedance_attribute_name property is set to travel_time and assign a value to time_of_day. (A travel mode with other impedance_attribute_name values don’t support traffic.) The time_of_day value represents the time at which travel begins, or departs, from the origin points. The time is specified as datetime.datetime.

The service supports two kinds of traffic: typical and live. Typical traffic references travel speeds that are made up of historical averages for each five-minute interval spanning a week. Live traffic retrieves speeds from a traffic feed that processes phone probe records, sensors, and other data sources to record actual travel speeds and predict speeds for the near future.

The data coverage page shows the countries Esri currently provides traffic data for.

Typical Traffic:

To ensure the task uses typical traffic in locations where it is available, choose a time and day of the week, and then convert the day of the week to one of the following dates from 1990:

• Monday - 1/1/1990

• Tuesday - 1/2/1990

• Wednesday - 1/3/1990

• Thursday - 1/4/1990

• Friday - 1/5/1990

• Saturday - 1/6/1990

• Sunday - 1/7/1990

Set the time and date as datetime.datetime.

For example, to solve for 1:03 p.m. on Thursdays, set the time and date to 1:03 p.m., 4 January 1990; and convert to datetime eg. datetime.datetime(1990, 1, 4, 1, 3).

Live Traffic:

To use live traffic when and where it is available, choose a time and date and convert to datetime.

Esri saves live traffic data for 4 hours and references predictive data extending 4 hours into the future. If the time and date you specify for this parameter is outside the 24-hour time window, or the travel time in the analysis continues past the predictive data window, the task falls back to typical traffic speeds.

Examples: from datetime import datetime

• “time_of_day”: datetime(1990, 1, 4, 1, 3) # 13:03, 4 January 1990. Typical traffic on Thursdays at 1:03 p.m.

• “time_of_day”: datetime(1990, 1, 7, 17, 0) # 17:00, 7 January 1990. Typical traffic on Sundays at 5:00 p.m.

• “time_of_day”: datetime(2014, 10, 22, 8, 0) # 8:00, 22 October 2014. If the current time is between 8:00 p.m., 21 Oct. 2014 and 8:00 p.m., 22 Oct. 2014, live traffic speeds are referenced in the analysis; otherwise, typical traffic speeds are referenced.

• “time_of_day”: datetime(2015, 3, 18, 10, 20) # 10:20, 18 March 2015. If the current time is between 10:20 p.m., 17 Mar. 2015 and 10:20 p.m., 18 Mar. 2015, live traffic speeds are referenced in the analysis; otherwise, typical traffic speeds are referenced.

output_name

Optional string or FeatureLayer. Existing feature layer will cause the new layer to be appended to the Feature Service. If overwrite is True in context, new layer will overwrite existing layer. If output_name not indicated then new FeatureCollection created.

gis

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

point_barrier_layer

Optional layer. Specify one or more point features that act as temporary restrictions (in other words, barriers) when traveling on the underlying streets.

A point barrier can model a fallen tree, an accident, a downed electrical line, or anything that completely blocks traffic at a specific position along the street. Travel is permitted on the street but not through the barrier. See Feature Input.

polygon_barrier_layer

Optional string. Specify one or more polygon features that completely restrict travel on the streets intersected by the polygons.

One use of this type of barrier is to model floods covering areas of the street network and making road travel there impossible. See Feature Input.

travel_direction

Optiona String. Specify whether the direction of travel used to generate the travel areas is toward or away from the input locations.

Values: AwayFromFacility or TowardsFacility

The travel direction can influence how the areas are generated. CreateDriveTimeAreas will obey one-way streets, avoid illegal turns, and follow other rules based on the direction of travel. You should select the direction of travel based on the type of input locations and the context of your analysis. For example, the drive-time area for a pizza delivery store should be created away from the facility, whereas the drive-time area for a hospital should be created toward the facility.

include_reachable_streets

Optional string. Only applicable if output_name is specified. When True (and output_name is specified), a second layer named Reachable Streets is created in the output Feature Layer.

This layer contains the streets that were used to define the drive time area polygons. Set this to true if you want a potentially more accurate result of which streets are actually covered within a specific travel distance than what the drive-time areas would contain.

Parameter

Description

near_layer

Required layer. The nearest features are chosen from this layer. This layer can have point, line, or polygon features. See Feature Input.

max_count

Optional string. The maximum number of nearest locations to find for each feature in analysis_layer. The default is the maximum cutoff allowed by the service, which is 100.

Note that setting a maxCount for this parameter doesn’t guarantee that many features will be found. The search_cutoff and other constraints may also reduce the number of features found.

search_cutoff_units

The units of the search_cutoff parameter. This parameter is ignored when measurement_type is set to a time based travel mode because the units for search_cutoff are always minutes in those cases. If measurement_type is set to StraightLine or another distance-based travel mode, and a value for search_cutoff is specified, set the cutoff units using this parameter.

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

The default value is null, which causes the service to choose either miles or kilometers according to the units property of the user making the request.

time_zone_for_time_of_day

Optional string. Specify the time zone or zones of the time_of_day parameter.

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

GeoLocal-refers to the time zone in which the origins_layer points are located.

UTC-refers to Coordinated Universal Time.

point_barrier_layer

Optional layer. Specify one or more point features that act as temporary restrictions (in other words, barriers) when traveling on the underlying streets.

A point barrier can model a fallen tree, an accident, a downed electrical line, or anything that completely blocks traffic at a specific position along the street. Travel is permitted on the street but not through the barrier.

polygon_barrier_layer

Optional layer. Specify one or more polygon features that completely restrict travel on the streets intersected by the polygons.

One use of this type of barrier is to model floods covering areas of the street network and making road travel there impossible.

context

Optional dict. Additional settings such as processing extent and output spatial reference. For find_nearest, there are three settings.

• extent - a bounding box that defines the analysis area. Only those features in the input_layer that intersect the bounding box will be analyzed.

• outSR - the output features will be projected into the output spatial reference referred to by the wkid.

• overwrite - if True, then the feature layer in output_name will be overwritten with new feature layer. Available for ArcGIS Online or Enterprise 10.9.1+

  # Example Usage
  context = {"extent": {"xmin": 3164569.408035,
                      "ymin": -9187921.892449,
                      "xmax": 3174104.927313,
                      "ymax": -9175500.875353,
                      "spatialReference":{"wkid":102100,"latestWkid":3857}},
              "outSR": {"wkid": 3857},
              "overwrite": True}
  

estimate

Optional boolean. If True, the estimated number of credits required to run the operation will be returned.

Parameter

Description

route_count

Required integer. The number of vehicles that are available to visit the stops. The method supports up to 100 vehicles.

The default value is 0.

The method may be able to find and return a solution that uses fewer vehicles than the number you specify for this parameter. The number of vehicles returned also depends on four other parameters: the total number of stops in stops_layer, the number of stops per vehicle you allow (max_stops_per_route), the travel time between stops, the time spent at each stop (stop_service_time), and any limit you set on the total route time per vehicle (max_route_time).

route_start_time

Required datetime.datetime. Specify when the vehicles or people start their routes. The time is specified as datetime. The starting time value is the same for all routes; that is, all routes start at the same time.

Time zones affect what value you assign to route_start_time. The time zone for the start time is based on the time zone in which the starting point is geographically located. For instance, if you have one route starting location and it is located in Pacific Standard Time (PST), the time you specify for route_start_time is in PST.

There are a couple of scenarios to beware of given that starting times are based on where the starting points are located. One situation to be careful of is when you are located in one time zone but your starting locations are in another times zone. For instance, assume you are in Pacific Standard Time (UTC-8:00) and the vehicles you are routing are stationed in Mountain Standard Time (UTC-7:00). If it is currently 9:30 a.m. PST (10:30 a.m. MST) and your vehicles need to begin their routes in 30 minutes, you would set the start time to 11:00 a.m. That is, the starting locations for the routes are in the Mountain time zone, and it is currently 10:30 a.m. there, therefore, a starting time of 30 minutes from now is 11:00 a.m. Make sure you set the parameter according to the proper time zone.

The other situation that requires caution is where starting locations are spread across multiple time zones. The time you set for route_start_time is specific to the time zone in which the starting location is regardless of whether there are one or more starting locations in the problem you submit. For instance, if one route starts from a point in PST and another route starts from MST, and you enter 11:00 a.m. as the start time, the route in PST will start at 11:00 a.m. PST and the route in MST will start at 11:00 a.m. MST a one-hour difference. The starting times are the same in local time, but offset in actual time, or UTC.

The service automatically determines the time zones of the input starting locations (start_layer) for you.

Examples:

• datetime(2014, 10, 22, 8, 0) # 8:00, 22 October 2014. Routes will depart their starting locations at 8:00 a.m., 22 October. Any routes with starting points in Mountain Standard Time start at 8:00 a.m., 22 October 2014 MST; any routes with starting points in Pacific Standard Time start at 8:00 a.m. 22 October 2014 PST, and so on.

• datetime(2015, 3, 18, 10, 20) # 10:20, 18 March 2015.

start_layer_route_id_field

Optional string. Choose a field that uniquely identifies points in start_layer. This parameter is required when start_layer has more than one point; it is ignored otherwise.

The start_layer_route_id_field parameter helps identify where routes begin and indicates the names of the output routes.

See the the section of this topic entitled Starting and ending locations of routes to learn more.

end_layer

Optional layer. Provide the locations where the people or vehicles end their routes.

If end_layer is not specified, return_to_start must be set to True.

You can specify one or many ending locations.

If specifying one, all routes will end at the one location. If specifying many ending locations, each route needs exactly one predefined ending location, and the following criteria must be met:

• The number of routes (route_count) must equal the number of points in end_layer. (However, when only one point is included in end_layer, it is assumed that all routes end at the same location, and the two numbers can be different.)

• The ending location for each route must be identified with the start_layer_route_id_field parameter. This implies that the input points in endLayer have a unique identifier. Bear in mind that if you also have many starting locations, those locations need to be predetermined as well. The predetermined start and end locations of each route are paired together by matching route ID values. See Feature Input.

travel_mode

Optional string. Optional string. Specify the mode of transportation for the analysis.

Choice list: [‘Driving Distance’, ‘Driving Time’, ‘Rural Driving Distance’, ‘Rural Driving Time’, ‘Trucking Distance’, ‘Trucking Time’, ‘Walking Distance’, ‘Walking Time’]

max_route_time

Optional float. The amount of time you specify here limits the maximum duration of each route. The maximum route time is an accumulation of travel time and the total service time at visited stops (stop_service_time). This parameter is commonly used to prevent drivers from working too many hours or to balance workloads across routes or drivers.

The units are ‘minutes’. The default value, which is also the maximum value, is 525600 minutes, or one year.

output_name

Optional string or FeatureLayer. Existing feature layer will cause the new layer to be appended to the Feature Service. If overwrite is True in context, new layer will overwrite existing layer. If output_name not indicated then new FeatureCollection created.

gis

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

point_barrier_layer

Optional feature layer. Specify one or more point features that act as temporary restrictions (in other words, barriers) when traveling on the underlying streets.

A point barrier can model a fallen tree, an accident, a downed electrical line, or anything that completely blocks traffic at a specific position along the street. Travel is permitted on the street but not through the barrier. See Feature Input.

polygon_barrier_layer

Optional feature layer. Specify one or more polygon features that completely restrict travel on the streets intersected by the polygons.

One use of this type of barrier is to model floods covering areas of the street network and making road travel there impossible. See Feature Input.