Find Nearby Locations (Business Analyst)

Available with Business Analyst license.

Summary

Identifies locations closest to the input features based on a selected distance type. The number of points in the output is defined by limiting the count or percentage of location points to return or by limiting the distance from the input points.

Usage

  • The Input Features parameter value must be a point feature class. The input features are the sites you are analyzing, such as stores or facilities.

  • The Location Points parameter value must be a point feature class. The location points are all nearby locations that will be used in the tool calculations.

  • The Output Feature Class parameter will contain all attributes from the Input Features and Location Points parameters, as well as calculated fields containing distance and direction values.

  • To create a report, check the Create Report parameter.

Parameters

LabelExplanationData Type
Input Features

The point layer to be measured to or from Location Points.

Feature Layer
ID Field

A field containing unique identifiers for each input feature.

Field
Location Points

The layer that will be used to generate the output with distance and direction attributes to or from Input Features.

Feature Layer
Output Feature Class

The output location point features.

Feature Class
Distance Type
(Optional)

The calculated distance based on the method of travel. Straight Line is the default value.

String
Distance Units
(Optional)

The measurement units, in distance or time, that will be used when calculating nearby locations.

String
Distance Limit
(Optional)

The analysis extent measured in distance or time.

Double
Number of Locations Limit

The numeric limit of the Location Points value.

Long
Percentage of Locations Limit

The closest points, as a percentage of the points of the Location Points value.

Double
Create Report
(Optional)

Specifies whether an output report will be created.

  • Checked—A report will be created.
  • Unchecked—A report will not be created. This is the default.
Boolean
Report Title
(Optional)

The title of the output report.

String
Output Report Folder
(Optional)

The directory that will contain the output report.

Folder
Report Output Formats
(Optional)

The output report formats. The default value is InfographicHTML. Additional available formats are PDF, XLSX, S.XLSX, HTML, S.XML, ZIP, CVS, PAGX, and InfographicPDF.

String
Report Fields
(Optional)

The additional fields that will be added to the report.

Field
Travel Direction
(Optional)

Specifies whether travel times or distances will be measured from location points to input features or from input features to location points.

  • Toward Input Features —The direction of travel will be from location points to input features. This is the default.
  • Away from Input Features —The direction of travel will be from input features to location points.
String
Time of Day
(Optional)

The time at which travel begins.

Date
Time Zone
(Optional)

Specifies the time zone that will be used for the time_of_day parameter.

  • UTC —Coordinated universal time (UTC) will be used. Choose this option if you want the best location for a specific time, such as now, but aren't certain of the time zone in which the in_location_points value will be located.
  • Local time at locations —The time zone in which the in_location_points value will be located will be used. If the travel direction is input features to location points, this is the time zone of the input features. If the travel direction is location points to input features, this is the time zone of the location points. This is the default.
  • UTC —Coordinated universal time (UTC) will be used. Choose this option if you want the best location for a specific time, such as now, but aren't certain of the time zone in which the Location Points value will be located.
  • Local time at locations —The time zone in which the Location Points value will be located will be used. If the travel direction is input features to location points, this is the time zone of the input features. If the travel direction is location points to input features, this is the time zone of the location points. This is the default.
String
Search Tolerance
(Optional)

The maximum distance that input points can be from the network. Points located beyond the search tolerance will be excluded from processing.

Linear Unit

Derived Output

LabelExplanationData Type
Output Report

The output report file.

File

arcpy.ba.FindNearbyLocations(in_features, id_field, in_location_points, out_feature_class, {distance_type}, {units}, {distance_limit}, number_limit, percent_limit, {create_report}, {report_title}, {report_folder}, {report_format}, {report_fields}, {travel_direction}, {time_of_day}, {time_zone}, {search_tolerance})
NameExplanationData Type
in_features

The point layer to be measured to or from in_location_points.

Feature Layer
id_field

A field containing unique identifiers for each input feature.

Field
in_location_points

The layer that will be used to generate the output with distance and direction attributes to or from in_features.

Feature Layer
out_feature_class

The output location point features.

Feature Class
distance_type
(Optional)

The calculated distance based on the method of travel. Straight Line is the default value.

String
units
(Optional)

The measurement units, in distance or time, that will be used when calculating nearby locations.

String
distance_limit
(Optional)

The analysis extent measured in distance or time.

Double
number_limit

The numeric limit of the in_location_points value.

Long
percent_limit

The closest points, as a percentage of the points of the in_location_points value.

Double
create_report
(Optional)

Specifies whether an output report will be created.

  • CREATE_REPORTA report will be created.
  • DO_NOT_CREATE_REPORTA report will not be created. This is the default.
Boolean
report_title
(Optional)

The title of the output report.

String
report_folder
(Optional)

The directory that will contain the output report.

Folder
report_format
[report_format,...]
(Optional)

The output report formats. The default value is InfographicHTML. Additional available formats are PDF, XLSX, S.XLSX, HTML, S.XML, ZIP, CVS, PAGX, and InfographicPDF.

String
report_fields
[report_fields,...]
(Optional)

The additional fields that will be added to the report.

Field
travel_direction
(Optional)

Specifies whether travel times or distances will be measured from location points to input features or from input features to location points.

  • TOWARD_STORESThe direction of travel will be from location points to input features. This is the default.
  • AWAY_FROM_STORESThe direction of travel will be from input features to location points.
String
time_of_day
(Optional)

The time at which travel begins.

Date
time_zone
(Optional)

Specifies the time zone that will be used for the time_of_day parameter.

  • UTCCoordinated universal time (UTC) will be used. Choose this option if you want the best location for a specific time, such as now, but aren't certain of the time zone in which the in_location_points value will be located.
  • TIME_ZONE_AT_LOCATIONThe time zone in which the in_location_points value will be located will be used. If the travel direction is input features to location points, this is the time zone of the input features. If the travel direction is location points to input features, this is the time zone of the location points. This is the default.
String
search_tolerance
(Optional)

The maximum distance that input points can be from the network. Points located beyond the search tolerance will be excluded from processing.

Linear Unit

Derived Output

NameExplanationData Type
output_report

The output report file.

File

Code sample

FindNearbyLocations example (stand-alone script)

The following Python window script demonstrates how to use the FindNearbyLocations function.

import arcpy

# Access data locally.
arcpy.env.baDataSource = "LOCAL;;USA_ESRI_2020"
arcpy.ba.FindNearbyLocations("FindNearby.gdb/stores", "STORE_ID", "FindNearby.gdb/coffee", "FindNearby.gdb/Nearby_coffee_competitors", "STRAIGHT_LINE_DISTANCE", "MILES", None, "10", None, "DO_NOT_CREATE_REPORT", None, "#", None, None, "TOWARD_STORES", None, "TIME_ZONE_AT_LOCATION", None")

Licensing information

  • Basic: Requires Business Analyst
  • Standard: Requires Business Analyst
  • Advanced: Requires Business Analyst

Related topics