Near (Analysis Tools)

Summary

Calculates distances and other proximity information between features in one or more feature classes or layers.

Learn more about how proximity is calculated by geoprocessing tools

Illustration

Usage

The fields below will be added to the input. If the fields already exist, the field values will be updated. These field names can be configured using the Field Names parameter.
- NEAR_FID—The object ID of the nearest feature. If no near feature is found, the value will be -1.
- NEAR_DIST—The distance from the input feature to the near feature. The value is in the linear unit of the input feature's coordinate system, or meters when the Method parameter is set to Geodesic and the input is in a geographic coordinate system. If no near feature is found, the value will be -1.
- NEAR_FC—The path of the source feature class containing the nearest feature found. The layer name will be used if layers are used as input, and the catalog path to the feature class will be used if paths are used as input. This field is only added to the output table if multiple near features are specified. If no near feature is found, the value will be an empty string or null.
The fields below will be added to the input if the Location parameter is checked. The field values will be updated if the fields already exist. The field value units depend on the Method parameter value. If the Method parameter is set to Planar, the field value will be in the linear unit of the input feature's coordinate system. If it's set to Geodesic, the field value will be in the geographic coordinate system associated with the input feature's coordinate system.
- NEAR_X—The x-coordinate of the location on the near feature that is closest to the input feature. If no near feature is found, the value will be -1.
- NEAR_Y—The y-coordinate of the location on the near feature that is closest to the input feature. If no near feature is found, the value will be -1.
The field below will be added to the input features if the Angle parameter is checked. The field value will be updated if the field already exists.
- NEAR_ANGLE—The angle of the line at the FROM_X and FROM_Y location that connects the input features to the near feature. If no near feature is found or the near feature intersects the input feature, the value will be 0.
The values for NEAR_FID and NEAR_DIST will be -1 if no feature is found within the search radius.
Both input features and near features can be point, multipoint, line, or polygon.
The Near Features parameter value can include one or more feature classes of different shape types (point, multipoint, line, or polygon).
To calculate distance and additional proximity information within a single feature class or layer, the same feature class or layer can be used. In this case, the input feature being evaluated will be excluded from the near feature candidates to avoid all features being closest to themselves.
The input features can be a layer on which you have performed a selection. The selected features will be used and updated during tool operation. The remaining features will have the values of the newly created fields (such as NEAR_FID and NEAR_DIST) set to -1.
When more than one near feature has the same shortest distance from an input feature, one of them is randomly chosen as the nearest feature.
When using the Planar option for the Method parameter, use a projection for the input features that is appropriate for distance measurement, such as an equidistant projection.

Learn more about coordinate systems and projections
To visualize the NEAR_X and NEAR_Y locations, the output table can be used as input to the Make XY Event Layer or XY To Line tool.
You can set a unit of measurement for the NEAR_DIST field—such as meters, kilometers, or miles—using the Distance Unit parameter.
This tool supports finding the nearest feature for each input of the multiple Near Features parameter values.

Label	Explanation	Data type
Input Features	The input features, which can be point, polyline, polygon, or multipoint type.	Feature Layer
Near Features	One or more feature layers or feature classes containing near feature candidates. The near features can be point, polyline, polygon, or multipoint. If multiple layers or feature classes are specified, the `NEAR_FC` field will be added to the input table and will store the paths of the source feature class containing the nearest feature found. The same feature class or layer can be used as both input features and near features.	Feature Layer
Search Radius (Optional)	The radius that will be used to search for near features. If no value is specified, all near features will be considered. If a distance but no unit or unknown is specified, the units of the coordinate system of the input features will be used. If the Geodesic option is used for the Method parameter, use a linear unit such as kilometers or miles.	Linear Unit
Location (Optional)	Specifies whether x- and y-coordinates of the closest location of the near feature will be written to the `NEAR_X` and `NEAR_Y` fields. Checked—Locations will be written. Unchecked—Locations will not be written. This is the default.	Boolean
Angle (Optional)	Specifies whether the near angle will be calculated and written to the `NEAR_ANGLE` field in the output table. A near angle measures direction of the line connecting an input feature to its nearest feature at their closest location. When the `PLANAR` method is used for the `method` parameter, the angle will be within the range of -180° to 180°, with 0° to the east, 90° to the north, 180° (or -180°) to the west, and -90° to the south. When the `GEODESIC` method is used for the `method` parameter, the angle will be within the range of -180° to 180°, with 0° to the north, 90° to the east, 180° (or -180°) to the south, and -90° to the west. Checked—The near angle will be calculated and written to the `NEAR_ANGLE` field. Unchecked—The near angle will not be calculated or written to the `NEAR_ANGLE` field. This is the default.	Boolean
Method (Optional)	Specifies whether a shortest path on a spheroid (geodesic) or a flat earth (planar) distance method will be used. It is recommended that you use the Geodesic method for data stored in a coordinate system that is not appropriate for distance measurements (for example, Web Mercator or any geographic coordinate system) and for a dataset that spans a large geographic area. Planar—Planar distance will be used between features. This is the default. Geodesic—Geodesic distance will be used between features. This method takes into account the curvature of the spheroid and correctly deals with data near the international date line and the poles.	String
Field Names (Optional)	The names of the attribute fields that will be added during processing. If this parameter is not used or any fields that will be added are excluded from this parameter, the default field names will be used. By default, the `NEAR_FID` and `NEAR_DIST` fields will be added, the `NEAR_X` and `NEAR_Y` fields will be added when the Location parameter is checked, the `NEAR_ANGLE` field will be added when the Angle parameter is checked, and the `NEAR_FC` field will be added when multiple inputs are used. Optionally, when there are multiple Near Features parameter values, specify a `Near Features` column to designate the input on which the field will be based. Value table columns: Property—The property type. Feature ID—The object ID of the feature that is nearest will be added. Distance—The distance to the feature that is nearest will be added. Location x-coordinate—The x-coordinate of the feature that is nearest will be added. Location y-coordinate—The y-coordinate of the feature that is nearest will be added. Angle—The angle to the feature that is nearest will be added. Feature class—The name of the feature class with the nearest feature will be added. Field Name—The name of the attribute field to add to contain the specified Near property. Near Features—The near features that the field values will be based on.	Value Table
Distance Unit (Optional)	Specifies the unit of measurement for the `NEAR_DIST` field. When no unit of measurement is specified, the values in the `NEAR_DIST` field will be in the linear unit of the input feature's coordinate system. If the input is in a geographic coordinate system and the geodesic method is used, the units of the `NEAR_DIST` field will be meters. Kilometers—The unit will be kilometers. Meters—The unit will be meters. International Nautical Miles—The unit will be international nautical miles. Statute Miles—The unit will be statute miles. International Yards—The unit will be international yards. International Feet—The unit will be international feet. US Survey Nautical Miles—The unit will be U.S. survey nautical miles. US Survey Miles—The unit will be U.S. survey miles. US Survey Yards—The unit will be U.S. survey yards. US Survey Feet—The unit will be U.S. survey feet.	String
Match Fields (Optional)	The pairs of fields from the input features and near features that will be used for attribute matching. Only the near features that share match field values with the input features will be used in the near calculation. Value table columns: Input Fields—Fields from the input features that will be used for attribute matching. Near Fields—Fields from the near features that will be used for attribute matching.	Value Table

Derived output

Label	Explanation	Data type
Updated Input Features	The updated input features.	Feature Layer

arcpy.analysis.Near(in_features, near_features, {search_radius}, {location}, {angle}, {method}, {field_names}, {distance_unit}, {match_fields})

Name	Explanation	Data type
in_features	The input features, which can be point, polyline, polygon, or multipoint type.	Feature Layer
near_features [near_features,...]	One or more feature layers or feature classes containing near feature candidates. The near features can be point, polyline, polygon, or multipoint. If multiple layers or feature classes are specified, the `NEAR_FC` field will be added to the input table and will store the paths of the source feature class containing the nearest feature found. The same feature class or layer can be used as both input features and near features.	Feature Layer
search_radius (Optional)	The radius that will be used to search for near features. If no value is specified, all near features will be considered. If a distance but no unit or unknown is specified, the units of the coordinate system of the input features will be used. If the `GEODESIC` option is used for the `method` parameter, use a linear unit such as kilometers or miles.	Linear Unit
location (Optional)	Specifies whether x- and y-coordinates of the closest location of the near feature will be written to the `NEAR_X` and `NEAR_Y` fields. `LOCATION`—Locations will be written. `NO_LOCATION`—Locations will not be written. This is the default.	Boolean
angle (Optional)	Specifies whether the near angle will be calculated and written to the `NEAR_ANGLE` field in the output table. A near angle measures direction of the line connecting an input feature to its nearest feature at their closest location. When the `PLANAR` method is used for the `method` parameter, the angle will be within the range of -180° to 180°, with 0° to the east, 90° to the north, 180° (or -180°) to the west, and -90° to the south. When the `GEODESIC` method is used for the `method` parameter, the angle will be within the range of -180° to 180°, with 0° to the north, 90° to the east, 180° (or -180°) to the south, and -90° to the west. `ANGLE`—The near angle will be calculated and written to the `NEAR_ANGLE` field. `NO_ANGLE`—The near angle will not be calculated or written to the `NEAR_ANGLE` field. This is the default.	Boolean
method (Optional)	Specifies whether a shortest path on a spheroid (geodesic) or a flat earth (planar) distance method will be used. It is recommended that you use the `GEODESIC` method for data stored in a coordinate system that is not appropriate for distance measurements (for example, Web Mercator or any geographic coordinate system) and for a dataset that spans a large geographic area. `PLANAR`—Planar distance will be used between features. This is the default. `GEODESIC`—Geodesic distance will be used between features. This method takes into account the curvature of the spheroid and correctly deals with data near the international date line and the poles.	String
field_names [[property, fieldname],...] (Optional)	The names of the attribute fields that will be added during processing. If this parameter is not used or any fields that will be added are excluded from this parameter, the default field names will be used. By default, the `NEAR_FID` and `NEAR_DIST` fields will be added, the `NEAR_X` and `NEAR_Y` fields will be added when the `location` parameter is set to `LOCATION`, the `NEAR_ANGLE` field will be added when the `angle` parameter is set to `ANGLE`, and the `NEAR_FC` field will be added when multiple inputs are used. Optionally, when there are multiple `near_features` parameter values, include the feature class or feature layer to designate the input on which the field will be based. Value table columns: `Property`—The property type. `NEAR_FID`—The object ID of the feature that is nearest will be added. `NEAR_DIST`—The distance to the feature that is nearest will be added. `NEAR_X`—The x-coordinate of the feature that is nearest will be added. `NEAR_Y`—The y-coordinate of the feature that is nearest will be added. `NEAR_ANGLE`—The angle to the feature that is nearest will be added. `NEAR_FC`—The name of the feature class with the nearest feature will be added. `Field Name`—The name of the attribute field to add to contain the specified Near property. `Near Features`—The near features that the field values will be based on.	Value Table
distance_unit (Optional)	Specifies the unit of measurement for the `NEAR_DIST` field. When no unit of measurement is specified, the values in the `NEAR_DIST` field will be in the linear unit of the input feature's coordinate system. If the input is in a geographic coordinate system and the geodesic method is used, the units of the `NEAR_DIST` field will be meters. `Kilometers`—The unit will be kilometers. `Meters`—The unit will be meters. `NauticalMilesInt`—The unit will be international nautical miles. `MilesInt`—The unit will be statute miles. `YardsInt`—The unit will be international yards. `FeetInt`—The unit will be international feet. `NauticalMiles`—The unit will be U.S. survey nautical miles. `Miles`—The unit will be U.S. survey miles. `Yards`—The unit will be U.S. survey yards. `Feet`—The unit will be U.S. survey feet.	String
match_fields [[input_field, near_field],...] (Optional)	The pairs of fields from the input features and near features that will be used for attribute matching. Only the near features that share match field values with the input features will be used in the near calculation. Value table columns: `Input Fields`—Fields from the input features that will be used for attribute matching. `Near Fields`—Fields from the near features that will be used for attribute matching.	Value Table

Derived output

Name	Explanation	Data type
out_feature_class	The updated input features.	Feature Layer

Code sample

Near example 1 (Python window)

The following Python interactive window script demonstrates how to use the Near function in immediate mode.

import arcpy
arcpy.env.workspace = "C:/data/city.gdb"

# Find the nearest road from each house
arcpy.analysis.Near('houses', 'roads')

Near example 2 (stand-alone script)

The following Python script demonstrates how to use the Near function in a stand-alone script.

# Name: Near.py
# Description: Finds nearest features from input feature class to near feature class.

import arcpy

# Set workspace environment
arcpy.env.workspace = "C:/data/city.gdb"

try:
    # set local variables
    in_features = "houses"
    near_features = "parks"

    # find features only within search radius
    search_radius = "5000 Meters"

    # find location nearest features
    location = "LOCATION"

    # avoid getting angle of neares features
    angle = "NO_ANGLE"

    # run the function
    arcpy.analysis.Near(in_features, near_features, search_radius, location, angle)

    # get geoprocessing messages
    print(arcpy.GetMessages())

except arcpy.ExecuteError:
    print(arcpy.GetMessages(2))

except Exception as err:
    print(err.args[0])

Near example 3 (stand-alone script)

The following Python script demonstrates how to convert the near angle to azimuth.

# Name: near_angle_to_azimuth.py

import arcpy

# Near tool does not calculate angle in azimuths
# This script, using the output of the tool, converts the angles
# to azimuth angles.

in_table = r"C:/data/city.gdb/near_table"

angles = arcpy.da.SearchCursor(in_table, ["NEAR_ANGLE"])

azimuth_angles = []

with angles as rows:
    for row in rows:
        angle = row[0]
        if angle <= 180 and angle > 90:
            azimuth_angles.append(360.0 - (angle - 90))
        else:
            azimuth_angles.append(abs(angle - 90))

# Use these azimuth angles as necessary.

Near example 4 (stand-alone script)

The following Python script demonstrates postprocessing using the Near function's derived output. The script finds, for each near feature, the input features it is closest to.

# Name: features_closest_to_input.py

"""
    This script finds, for each input feature, a list of near feature it is closest to.
    If near features 6, 7, 10 are closest to input feature 3 then the
    resulting dictionary will have a list [6, 7, 10] as value for key 3
"""

import os
import arcpy

in_fc = r"C:\data\cities.gdb\cities_many"

# create a dictionary to hold the list of near ids for each input id
nearest_dict = dict()

with arcpy.da.SearchCursor(in_fc, ["OID@", "NEAR_FID"]) as rows:
    for row in rows:
        nearest_id = row[0]  # get OID value for that row
        input_id = row[1]    # get NEAR_FID value

        if input_id in nearest_dict:
            # if a dict key already exists, append near id to value list for that key
            nearest_dict[input_id].append(nearest_id)
        else:
            # if the key does not exist then create a new list with near id
            # and add it to the dictionary
            nearest_dict[input_id] = [nearest_id]

print(nearest_dict)

# output will look like:
# {1: [13, 28], 2: [2, 9, 14, 20, 22], 3: [11, 12, 24, 25]}

Environments

Extent, Current Workspace

Licensing information

Basic: Yes
Standard: Yes
Advanced: Yes

Near (Analysis Tools)

Summary

Illustration

Usage

Parameters

Derived output

Environments

Licensing information

Related topics