Generate Near Table (Analysis)

Summary

Calculates distances and other proximity information between features in one or more feature classes or layers. Unlike the Near tool, which modifies the input, Generate Near Table writes results to a new stand-alone table and supports finding more than one near feature.

Learn more about how proximity is calculated by geoprocessing tools

Illustration

Generate Near Table tool illustration

Usage

  • The output table will contain the following fields:

    • IN_FID—The Object ID of the input feature.
    • NEAR_FID—The Object ID of the nearest feature.
    • NEAR_DIST—The distance from the input feature to the near feature. The value distance unit of this field is 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.
    • NEAR_FC—The catalog path to the feature class that contains the near feature. This field is only added to the output table if multiple Near Features values are specified.
    • NEAR_RANK—An integer value ranking all near features based on their proximity to an individual input feature. The closest feature will have a value of 1, the second closest will have a value of 2, and so on.

    The fields below will be added to the output table if the Location parameter is checked. The field value unit depends 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.

    • FROM_X—The x-coordinate of the location on the input feature that is closest to the near feature
    • FROM_Y—The y-coordinate of the location on the input feature that is closest to the near feature
    • NEAR_X—The x-coordinate of the location on the near feature that is closest to the input feature
    • NEAR_Y—The y-coordinate of the location on the near feature that is closest to the input feature

    The following field will be added to the output table if the Angle parameter is checked:

    • NEAR_ANGLE—The angle of the line at the FROM_X and FROM_Y location that connects the input features to the near feature

  • When the input and near feature intersect, the following values will be written to the output table:

    • NEAR_ANGLE and NEAR_DIST will be set to 0.0.
    • FROM_X and FROM_Y will be identical to NEAR_X and NEAR_Y and will be a location within the intersection of the two features.

  • The values for 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 Method parameter is set to Geodesic, the unit of the NEAR_DIST field will be meters.

  • The output table can be joined back to the input features using the IN_FID field or to the near features using the NEAR_FID field.

  • If the Search Radius parameter value is specified and no near feature is found, no record will be output.

  • If the Search Radius parameter value is not specified, all near features will be considered candidates.

  • If the Search Radius parameter value is not specified, the Find only closest features parameter is unchecked, and the Maximum number of closest matches parameter is set to the default (0 or empty), the output table will contain distance calculations between all input features and all near features. This process may take a long time and create a large output table. For example, if you have 1,000 input features and 1,000 near features, the output table will contain 1 million records.

  • The same feature class or layer can be used as both input features and near features. In this situation, the input feature being evaluated will be excluded from the near features candidates to avoid all features being closest to themselves.

  • 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 FROM_X, FROM_Y, NEAR_X, and NEAR_Y field values, the output table can be used as input to the Make XY Event Layeror 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.

Parameters

LabelExplanationData 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
Output Table

The output table containing the result of the analysis.

Table
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 input feature's location and closest location of the near feature will be written to the FROM_X, FROM_Y, NEAR_X, and NEAR_Y fields.

  • Unchecked—Locations will not be written to the output table. This is the default.
  • Checked—Locations will be written to the output table.
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 locations. 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.

  • Unchecked—The near angle will not be calculated and the NEAR_ANGLE field will not be added to the output table. This is the default.
  • Checked—The near angle will be calculated and the NEAR_ANGLE field will be added to the output table.
Boolean
Find only closest feature
(Optional)

Specifies whether only the closest near feature will be written to the output table.

  • Checked—Only the closest near feature will be written to the output table. This is the default.
  • Unchecked—Multiple near features will be written to the output table (a limit can be specified in the Maximum number of closest matches parameter).
Boolean
Maximum number of closest matches
(Optional)

Limits the number of near features reported for each input feature. This parameter is inactive if the Find only closest feature parameter is checked.

Long
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.

  • PlanarPlanar distance will be used between features. This is the default.
  • GeodesicGeodesic 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
Distance Unit
(Optional)

Specifies the unit of measurement for the NEAR_DIST filed. 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.

  • KilometersThe unit will be kilometers.
  • MetersThe unit will be meters.
  • International Nautical MilesThe unit will be international nautical miles.
  • Statute MilesThe unit will be statute miles.
  • International YardsThe unit will be international yards.
  • International FeetThe unit will be international feet.
  • US Survey Nautical MilesThe unit will be U.S. survey nautical miles.
  • US Survey MilesThe unit will be U.S. survey miles.
  • US Survey YardsThe unit will be U.S. survey yards.
  • US Survey FeetThe unit will be U.S. survey feet.
String

arcpy.analysis.GenerateNearTable(in_features, near_features, out_table, {search_radius}, {location}, {angle}, {closest}, {closest_count}, {method}, {distance_unit})
NameExplanationData 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
out_table

The output table containing the result of the analysis.

Table
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 input feature's location and closest location of the near feature will be written to the FROM_X, FROM_Y, NEAR_X, and NEAR_Y fields.

  • NO_LOCATION Locations will not be written to the output table. This is the default.
  • LOCATION Locations will be written to the output table.
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 locations. 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.

  • NO_ANGLEThe near angle will not be calculated and the NEAR_ANGLE field will not be added to the output table. This is the default.
  • ANGLEThe near angle will be calculated and the NEAR_ANGLE field will be added to the output table.
Boolean
closest
(Optional)

Specifies whether only the closest near feature will be written to the output table.

  • CLOSESTOnly the closest near feature will be written to the output table. This is the default.
  • ALLMultiple near features will be written to the output table (a limit can be specified in the closest_count parameter).
Boolean
closest_count
(Optional)

Limits the number of near features reported for each input feature. This parameter is ignored if the closest parameter is set to CLOSEST.

Long
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.

  • PLANARPlanar distance will be used between features. This is the default.
  • GEODESICGeodesic 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
distance_unit
(Optional)

Specifies the unit of measurement for the NEAR_DIST filed. 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.

  • KilometersThe unit will be kilometers.
  • MetersThe unit will be meters.
  • NauticalMilesIntThe unit will be international nautical miles.
  • MilesIntThe unit will be statute miles.
  • YardsIntThe unit will be international yards.
  • FeetIntThe unit will be international feet.
  • NauticalMilesThe unit will be U.S. survey nautical miles.
  • MilesThe unit will be U.S. survey miles.
  • YardsThe unit will be U.S. survey yards.
  • FeetThe unit will be U.S. survey feet.
String

Code sample

GenerateNearTable example 1 (Python window)

The following demonstrates how to use the GenerateNearTable function in the Python window.

import arcpy

arcpy.env.workspace = "C:/data/input/gnt.gdb"

arcpy.analysis.GenerateNearTable("campsites", ["parks", "trails"], "better_sites")
GenerateNearTable example 2 (stand-alone script)

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

# Name: GenerateNearTable.py
# Description: Finds 3 nearest in the near feature class from the input feature class.


# import system modules
import arcpy

# set workspace environment
arcpy.env.workspace = "C:/data/input/gnt.gdb"

# set required parameters 
in_features = "campsites"
near_features = ["parks", "trails"]
out_table = "near_parks_trails"

# optional parameters
search_radius = '1500 Meters'
location = 'NO_LOCATION'
angle = 'NO_ANGLE'
closest = 'ALL'
closest_count = 3

# find crime locations within the search radius
arcpy.analysis.GenerateNearTable(in_features, near_features, out_table, search_radius, 
                                 location, angle, closest, closest_count)

Licensing information

  • Basic: Yes
  • Standard: Yes
  • Advanced: Yes

Related topics