geopandas.sindex.SpatialIndex.nearest

SpatialIndex.nearest(*args, **kwargs)

Return the nearest geometry in the tree for each input geometry in geometry.

Note

nearest currently only works with PyGEOS >= 0.10.

Note that if PyGEOS is not available, geopandas will use rtree for the spatial index, where nearest has a different function signature to temporarily preserve existing functionality. See the documentation of rtree.index.Index.nearest() for the details on the rtree-based implementation.

If multiple tree geometries have the same distance from an input geometry, multiple results will be returned for that input geometry by default. Specify return_all=False to only get a single nearest geometry (non-deterministic which nearest is returned).

In the context of a spatial join, input geometries are the “left” geometries that determine the order of the results, and tree geometries are “right” geometries that are joined against the left geometries. If max_distance is not set, this will effectively be a left join because every geometry in geometry will have a nearest geometry in the tree. However, if max_distance is used, this becomes an inner join, since some geometries in geometry may not have a match in the tree.

For performance reasons, it is highly recommended that you set the max_distance parameter.

Parameters

geometry{shapely.geometry, GeoSeries, GeometryArray, numpy.array of PyGEOS geometries}

A single shapely geometry, one of the GeoPandas geometry iterables (GeoSeries, GeometryArray), or a numpy array of PyGEOS geometries to query against the spatial index.

return_allbool, default True

If there are multiple equidistant or intersecting nearest geometries, return all those geometries instead of a single nearest geometry.

max_distancefloat, optional

Maximum distance within which to query for nearest items in tree. Must be greater than 0. By default None, indicating no distance limit.

return_distancebool, optional

If True, will return distances in addition to indexes. By default False

Returns

Indices or tuple of (indices, distances)

Indices is an ndarray of shape (2,n) and distances (if present) an ndarray of shape (n). The first subarray of indices contains input geometry indices. The second subarray of indices contains tree geometry indices.

Examples

>>> from shapely.geometry import Point, box
>>> s = geopandas.GeoSeries(geopandas.points_from_xy(range(10), range(10)))
>>> s.head()
0    POINT (0.00000 0.00000)
1    POINT (1.00000 1.00000)
2    POINT (2.00000 2.00000)
3    POINT (3.00000 3.00000)
4    POINT (4.00000 4.00000)
dtype: geometry

>>> s.sindex.nearest(Point(1, 1))
array([[0],
       [1]])

>>> s.sindex.nearest([box(4.9, 4.9, 5.1, 5.1)])
array([[0],
       [5]])

>>> s2 = geopandas.GeoSeries(geopandas.points_from_xy([7.6, 10], [7.6, 10]))
>>> s2
0    POINT (7.60000 7.60000)
1    POINT (10.00000 10.00000)
dtype: geometry

>>> s.sindex.nearest(s2)
array([[0, 1],
       [8, 9]])

geopandas.sindex.SpatialIndex.is_empty geopandas.sindex.SpatialIndex.query