Learn Spatial Joins: Within, Intersects, Contains | Spatial Operations and Map Processing

Spatial joins are essential techniques in geospatial data science, allowing you to combine information from different datasets based on their spatial relationships rather than traditional attribute keys. The most common spatial join predicates are within, intersects, and contains, each serving a specific analytical purpose. When you use the within predicate, you are looking to identify all features from one dataset (such as points) that are completely inside features of another dataset (such as polygons). This is useful, for example, when you want to determine which cities (points) are located within specific country boundaries (polygons).

The intersects predicate is broader: it matches features that share any spatial overlap, including touching at edges or corners. This is helpful for analyses like finding all rivers (lines) that cross or touch a protected area (polygon), or identifying parcels that touch a road network.

The contains predicate is essentially the inverse of within: it finds features in one dataset (such as polygons) that fully contain features from another dataset (such as points). This is valuable for queries such as listing all parks (polygons) that contain playgrounds (points).

Choosing the right predicate depends on your analytical goal:

Use within when you want features entirely inside another feature;
Use intersects when any overlap or contact is relevant;
Use contains when you want to know which features fully enclose others.


              12345678910111213141516171819202122232425
            
import geopandas as gpd
from shapely.geometry import Point, Polygon

# Create example polygons (e.g., city boundaries)
polygons = gpd.GeoDataFrame({
    "name": ["PolygonA", "PolygonB"],
    "geometry": [
        Polygon([(-1, -1), (-1, 2), (2, 2), (2, -1)]),
        Polygon([(3, 0), (3, 3), (6, 3), (6, 0)])
    ]
})

# Create example points (e.g., locations)
points = gpd.GeoDataFrame({
    "location": ["Loc1", "Loc2", "Loc3"],
    "geometry": [
        Point(0, 0),   # inside PolygonA
        Point(4, 1),   # inside PolygonB
        Point(5, 4)    # outside both
    ]
})

# Perform spatial join: which points fall within which polygons?
joined = gpd.sjoin(points, polygons, predicate="within", how="left")
print(joined[["location", "name"]])


              12345678910111213141516171819202122232425
            
import geopandas as gpd
from shapely.geometry import LineString, Polygon

# Create example polygons
polygons = gpd.GeoDataFrame({
    "area": ["Park", "Lake"],
    "geometry": [
        Polygon([(0, 0), (0, 3), (3, 3), (3, 0)]),
        Polygon([(2, 2), (2, 5), (5, 5), (5, 2)])
    ]
})

# Create example lines (e.g., rivers)
lines = gpd.GeoDataFrame({
    "river": ["RiverA", "RiverB"],
    "geometry": [
        LineString([(1, 1), (4, 4)]),  # crosses both polygons
        LineString([(4, 0), (4, 6)])   # only intersects Lake
    ]
})

# Use 'intersects' predicate to join lines and polygons
intersections = gpd.sjoin(lines, polygons, predicate="intersects", how="inner")
print(intersections[["river", "area"]])

1. What does a spatial join with the 'within' predicate return?

2. Which predicate would you use to find features that overlap?

Everything was clear?

Thanks for your feedback!

Section 2. Chapter 3

Ask AI

Ask anything or try one of the suggested questions to begin our chat

Swipe to show menu