# arcgis.features.find_locations module¶

These functions are used to identify areas that meet a number of different criteria you specify. These criteria can be based upon attribute queries (for example, parcels that are vacant) and spatial queries (for example, within 1 kilometer of a river). The areas that are found can be selected from existing features (such as existing land parcels) or new features can be created where all the requirements are met.

find_existing_locations searches for existing areas in a layer that meet a series of criteria. derive_new_locations creates new areas from locations in your study area that meet a series of criteria. find_similar_locations finds locations most similar to one or more reference locations based on criteria you specify. choose_best_facilities choose the best locations for facilities by allocating locations that have demand for these facilities in a way that satisfies a given goal. create_viewshed creates areas that are visible based on locations you specify. create_watersheds creates catchment areas based on locations you specify. trace_downstream determines the flow paths in a downstream direction from the locations you specify

## find_existing_locations¶

find_locations.find_existing_locations(expressions=None, output_name=None, context=None, gis=None, estimate=False)

The Find Existing Locations task selects features in the input layer that meet a query you specify. A query is made up of one or more expressions. There are two types of expressions: attribute and spatial. An example of an attribute expression is that a parcel must be vacant, which is an attribute of the Parcels layer (where STATUS = ‘VACANT’). An example of a spatial expression is that the parcel must also be within a certain distance of a river (Parcels within a distance of 0.75 Miles from Rivers).

input_layersRequired list of strings

A list of layers that will be used in the expressions parameter.

expressionsRequired string

output_nameOptional string

Additional properties such as output feature service name.

contextOptional string

Additional settings such as processing extent and output spatial reference.

gis :

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

result_layer : layer (FeatureCollection)

## derive_new_locations¶

find_locations.derive_new_locations(expressions=[], output_name=None, context=None, gis=None, estimate=False)

The Derive New Locations task derives new features from the input layers that meet a query you specify. A query is made up of one or more expressions. There are two types of expressions: attribute and spatial. An example of an attribute expression is that a parcel must be vacant, which is an attribute of the Parcels layer (where STATUS = ‘VACANT’). An example of a spatial expression is that the parcel must also be within a certain distance of a river (Parcels within a distance of 0.75 Miles from Rivers).The Derive New Locations task is very similar to the Find Existing Locations task, the main difference is that the result of Derive New Locations can contain partial features.In both tasks, the attribute expression where and the spatial relationships within and contains return the same result. This is because these relationships return entire features.When intersects or withinDistance is used, Derive New Locations creates new features in the result. For example, when intersecting a parcel feature and a flood zone area that partially overlap each other, Find Existing Locations will return the entire parcel whereas Derive New Locations will return just the portion of the parcel that is within the flood zone.

input_layersRequired list of strings

A list of layers that will be used in the expressions parameter.

expressionsRequired string

output_nameOptional string

Additional properties such as output feature service name.

contextOptional string

Additional settings such as processing extent and output spatial reference.

gis :

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

estimate :

Optional Boolean. If True, the number of credits to run the operation will be returned.

result_layer : layer (FeatureCollection)

## find_similar_locations¶

find_locations.find_similar_locations(search_layer, analysis_fields=[], input_query=None, number_of_results=0, output_name=None, context=None, gis=None, estimate=False)

Finds the locations that are most similar to one or more reference locations based on criteria that you specify.

input_layer : Required layer (see Feature Input in documentation)

search_layer : Required layer (see Feature Input in documentation)

analysis_fields : Required list of strings

input_query : Optional string

number_of_results : Optional int

output_name : Optional string

context : Optional string

dict with the following keys:

“similar_result_layer” : layer (FeatureCollection) “process_info” : layer (FeatureCollection)

## choose_best_facilities¶

find_locations.choose_best_facilities(demand_locations_layer: str = None, demand: float = 1, demand_field: str = None, max_travel_range: float = 2147483647, max_travel_range_field: str = None, max_travel_range_units: str = 'Minutes', travel_mode: str = None, time_of_day: datetime.datetime = None, time_zone_for_time_of_day: str = 'GeoLocal', travel_direction: str = 'FacilityToDemand', required_facilities_layer: str = None, required_facilities_capacity: float = 2147483647, required_facilities_capacity_field: str = None, candidate_facilities_layer: str = None, candidate_count: int = 1, candidate_facilities_capacity: float = 2147483647, candidate_facilities_capacity_field: str = None, percent_demand_coverage: float = 100, output_name: str = None, context: str = None, gis=None) → tuple

This tool chooses the best locations for facilities by allocating locations that have demand for these facilities in a way that satisfies a given goal.

Parameters:

goal: goal (str). Required parameter. Specify the goal that must be satisfied when allocating demand locations to facilities.

Choice list:[‘Allocate’, ‘MinimizeImpedance’, ‘MaximizeCoverage’, ‘MaximizeCapacitatedCoverage’, ‘PercentCoverage’]

demand_locations_layer: demandLocationsLayer (str). Required parameter. A point layer specifying the locations that have demand for facilities

demand: demand (float). Optional parameter. The amount of demand available at every demand locations.

demand_field: demandField (str). Optional parameter. The field on the demandLocationsLayer representing the amount of demand available at each demand location.

max_travel_range: maxTravelRange (float). Optional parameter. Specify the maximum travel time or distance allowed between a demand location and the facility it is allocated to

max_travel_range_field: maxTravelRangeField (str). Optional parameter. The field on the demandLocationsLayer specifying the maximum travel time or distance allowed between a demand location and the facility it is allocated to. This parameter takes precedence when maxTravelRange parameter is also specified

max_travel_range_units: maxTravelRangeUnits (str). Optional parameter. The units for the maximum travel time or distance allowed between a demand location and the facility it is allocated to.

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

travel_mode: travelMode (str). Optional parameter. Specify the mode of transportation for the analysis

time_of_day: timeOfDay (datetime). Optional parameter. Specify whether travel times should consider traffic conditions

time_zone_for_time_of_day: timeZoneForTimeOfDay (str). Optional parameter. Specify the time zone or zones for the timeOfDay parameter.

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

travel_direction: travelDirection (str). Optional parameter. Specify whether to measure travel times or distances from facilities to demand locations or from demand locations to facilities.

Choice list:[‘FacilityToDemand’, ‘DemandToFacility’]

required_facilities_layer: requiredFacilitiesLayer (str). Optional parameter. A point layer specifying one or more locations that act as facilities by providing some kind of service. Facilities specified by this parameter are required to be part of the output solution and will be used before any facilities from the candidatesFacilitiesLayer when allocating demand locations.

required_facilities_capacity: requiredFacilitiesCapacity (float). Optional parameter. Specify how much demand every facility in the requiredFacilitiesLayer is capable of supplying.

required_facilities_capacity_field: requiredFacilitiesCapacityField (str). Optional parameter. A field on the requiredFacilitiesLayer representing how much demand each facility in the requiredFacilitiesLayer is capable of supplying. This parameter takes precedence when requiredFacilitiesCapacity parameter is also specified.

candidate_facilities_layer: candidateFacilitiesLayer (str). Optional parameter. A point layer specifying one or more locations that act as facilities by providing some kind of service. Facilities specified by this parameter are not required to be part of the output solution and will be used only after all the facilities from the candidatesFacilitiesLayer have been used when allocating demand locations.

candidate_count: candidateCount (int). Optional parameter. Specify the number of facilities to choose when allocating demand locations. If requiredFacilitiesLayer is specified, the number of facilities to choose should be equal to or greater than the count of locations in the requiredFacilitiesLayer.

candidate_facilities_capacity: candidateFacilitiesCapacity (float). Optional parameter. Specify how much demand every facility in the candidateFacilitiesLayer is capable of supplying.

candidate_facilities_capacity_field: candidateFacilitiesCapacityField (str). Optional parameter. A field on the candidateFacilitiesLayer representing how much demand each facility in the candidatesFacilitiesLayer is capable of supplying. This parameter takes precedence when candidateFacilitiesCapacity parameter is also specified.

percent_demand_coverage: percentDemandCoverage (float). Optional parameter. Specify the percentage of the total demand that you want the chosen and required facilities to capture.

output_name: outputName (str). Optional parameter. If provided, the task will create a feature service of the results. You define the name of the service. If outputName is not supplied, the task will return a feature collection.

context: context (str). Optional parameter. Context contains additional settings that affect task execution such as the extent of inputs.

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

Returns the following as a named tuple:

allocated_demand_locations_layer - allocatedDemandLocationsLayer as a str allocation_lines_layer - allocationLinesLayer as a str assigned_facilities_layer - assignedFacilitiesLayer as a str

## create_viewshed¶

find_locations.create_viewshed(dem_resolution='Finest', maximum_distance=None, max_distance_units='Meters', observer_height=None, observer_height_units='Meters', target_height=None, target_height_units='Meters', generalize=True, output_name=None, context=None, gis=None, estimate=False)

Creates areas that are visible based on locations you specify.

input_layer : Required layer (see Feature Input in documentation)

dem_resolution : Optional string

maximum_distance : Optional float

max_distance_units : Optional string

observer_height : Optional float

observer_height_units : Optional string

target_height : Optional float

target_height_units : Optional string

generalize : Optional bool

output_name : Optional string

context : Optional string

gis :

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

estimate :

Optional Boolean. If True, the number of credits to run the operation will be returned.

viewshed_layer : layer (FeatureCollection)

## create_watersheds¶

find_locations.create_watersheds(search_distance=None, search_units='Meters', source_database='FINEST', generalize=True, output_name=None, context=None, gis=None, estimate=False)

Creates catchment areas based on locations you specify.

input_layer : Required layer (see Feature Input in documentation)

search_distance : Optional float

search_units : Optional string

source_database : Optional string

generalize : Optional bool

output_name : Optional string

context : Optional string

gis :

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

estimate :

Optional Boolean. If True, the number of credits to run the operation will be returned.

dict with the following keys:

“snap_pour_pts_layer” : layer (FeatureCollection) “watershed_layer” : layer (FeatureCollection)

## trace_downstream¶

find_locations.trace_downstream(split_distance=None, split_units='Kilometers', max_distance=None, max_distance_units='Kilometers', bounding_polygon_layer=None, source_database=None, generalize=True, output_name=None, context=None, gis=None, estimate=False)

Determine the flow paths in a downstream direction from the locations you specify.

input_layer : Required layer (see Feature Input in documentation)

split_distance : Optional float

split_units : Optional string

max_distance : Optional float

max_distance_units : Optional string

bounding_polygon_layer : Optional layer (see Feature Input in documentation)

source_database : Optional string

generalize : Optional bool

output_name : Optional string

context : Optional string

gis :

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

estimate :

Optional Boolean. If True, the number of credits to run the operation will be returned.

trace_layer : layer (FeatureCollection)