Nearest Join

Draft: written, not yet checked by a person Operation · nearest-join

Joins to each feature the attributes of the nearest feature in another layer, optionally with the distance.

Pitfall. Distances in a geographic CRS are in degrees.

Pitfall. Ties (two features at the same distance) give two rows in some engines and one in others.

About this operation
Also called	Join By Nearest, Near, closest feature join, sjoin_nearest, Spatial Join (closest)
Group	`vector/joins`
Checks	`crs.agreement, crs.measure, join.unmatched`
Pitfalls	2 listed above
Columbus tool	Not stated
Notes	Not stated
Status	active
Broader	Not stated
Narrower	Not stated
Related	`spatial-join`

Parameters

Name	Type	Required	Default	Values	Note
`max_distance`	length	no	Not stated	Not stated	Only join features within this distance, in the CRS's units.
`distance_field`	string	no	Not stated	Not stated	Name of a new attribute holding the distance.
`how`	enum	no	`left`	`left, inner`	left keeps features with no match within max_distance.

Direction	Name	Type	Geometry	Note
Input	`left`	vector	Not stated	Not stated
Input	`right`	vector	Not stated	Not stated
Output	`output`	vector	Not stated	Not stated

Engine	Tool	Parameters	Differences
`geopandas`	`geopandas.GeoDataFrame.sjoin_nearest`	`max_distance` → `max_distance` `distance_field` → `distance_col` `how` → `how` `right` → `right`	Called on the left GeoDataFrame; defaults to an inner join.
`geopandas`	`geopandas.sjoin_nearest`	`max_distance` → `max_distance` `distance_field` → `distance_col` `how` → `how` `right` → `right_df` `left` → `left_df`	Defaults to an inner join; Columbus's default is left. Ties give one row per tied feature.
`grass`	`v.distance`	`max_distance` → `dmax` `distance_field` upload = dist with column = the field name. `right` → `to` `left` → `from`	Writes into the from map's attribute table (upload, column, to_column) rather than making a joined layer.
`qgis`	`native:joinbynearest`	`max_distance` → `MAX_DISTANCE` `distance_field` Adds the fields distance, feature_x, feature_y, nearest_x and nearest_y itself. `how` → `DISCARD_NONMATCHING` : left = no; inner = yes `right` → `INPUT_2` `left` → `INPUT` `output` → `OUTPUT`	NEIGHBORS can join the k nearest features (one row each). Preset: `{"NEIGHBORS":1}`
`sf`	`sf::st_nearest_feature`	`max_distance` No limit; filter with st_distance afterwards. `right` → `y` `left` → `x`	Returns the index of the nearest feature in y for each feature of x; join with cbind(x, st_drop_geometry(y)[idx, ]).