Working with GeoPandas and Shapely
Shapely supplies immutable geometry objects, predicates, and constructive operations in a Cartesian plane. GeoPandas adds pandas-aligned geometry columns, CRS metadata, file interfaces, spatial indexes, joins, and vectorized operations. Neither library infers the correct real-world semantics for a dataset.
Prerequisites
Complete geometry validity and topology. You should be able to reject or quarantine invalid input before applying a constructive operation.
Learning goals
- Build and inspect a
GeoDataFramewith one active geometry column and an explicit CRS. - Preserve identifiers and missing attributes through filtering and transformation.
- Run planar Shapely operations only in units suitable for the question.
- Verify the exact GeoPandas, Shapely, pyproj, and PROJ runtime used by examples.
The geometry column is data, not decoration
A GeoDataFrame aligns an active geometry column with ordinary attributes. Inspect .geometry.name, .geom_type, .is_empty, .is_valid, .total_bounds, and .crs before analysis. Missing geometry and empty geometry are different: missing means no geometry value; empty is a valid geometry object with no points. Missing attributes such as the fixture's kind must remain missing unless a documented rule supplies a value.
Shapely operations use the coordinates supplied and do not transform CRSs. Calling .buffer(250) on longitude-latitude data creates a 250-degree planar buffer, not 250 metres. Transform the Berlin layer to EPSG:32633, buffer in metres, and retain the source layer or transform the result back only for interchange or display.
This repository verifies against GeoPandas 1.2.0, Shapely 2.2.0, and pyproj 3.8.0. The pyproj 3.8.0 wheels used by the verification environment embed PROJ 9.8.1; the independently released current PROJ source is 9.9.0. A package pin and a runtime library version are related but distinct evidence.
Worked example
import json
from pathlib import Path
import geopandas as gpd
import pyproj
import shapely
path = Path("tests/fixtures/geospatial-data-science/places.geojson")
document = json.loads(path.read_text(encoding="utf-8"))
places = gpd.GeoDataFrame.from_features(
document["features"],
crs=document["metadata"]["crs"],
)
projected = places.to_crs("EPSG:32633")
west = projected.loc[projected["place_id"] == "west-library", "geometry"].iloc[0]
area = west.buffer(250).area
print(f"geopandas={gpd.__version__} shapely={shapely.__version__} pyproj={pyproj.__version__} proj={pyproj.proj_version_str}")
print(f"rows={len(places)} crs={places.crs.to_string()} missing_kind={int(places['kind'].isna().sum())}")
print(f"buffer_radius_m=250 west_buffer_area_m2={area:.0f}")
Expected output:
geopandas=1.2.0 shapely=2.2.0 pyproj=3.8.0 proj=9.8.1
rows=5 crs=OGC:CRS84 missing_kind=1
buffer_radius_m=250 west_buffer_area_m2=196034
The polygon is an approximation to a planar circle, so its area is slightly below (\pi 250^2). Buffer resolution, projection distortion, and source positional accuracy all matter if the boundary drives a decision.
Safe operation pattern
For each operation:
- assert identifiers, required attributes, geometry presence, and geometry type;
- inspect validity and preserve rejected-record evidence;
- confirm CRS equivalence and units across every input;
- select a predicate or constructive operation from the question;
- record row cardinality and geometry-type changes;
- validate literal known cases, especially boundaries and missing values;
- report limitations rather than extrapolating tiny-fixture timings.
GeoPandas aligns pandas indices during many operations. Resetting, sorting, exploding multipart geometry, or joining can change index shape. Stable domain IDs must not be replaced by transient row numbers.
Limitations and common mistakes
- Shapely is planar; it does not choose or transform a CRS.
- GeoPandas warnings about geographic distance or area identify a semantic defect, not cosmetic noise.
- Vectorized operations can return multipart or collection geometries.
- Dependency versions do not prove that every optional file driver or datum grid is available.
- A spatial index accelerates candidate lookup; it does not change predicate semantics.
Practice
Add an empty geometry and a missing geometry to a copy of the places frame. Design separate validation outcomes for them, and explain why filling either with (0, 0) would manufacture a location.
Next steps
Next, combine layers with spatial joins, overlay, and dissolve while measuring cardinality and geometry changes.
Primary sources
Checked 2026-10-18: GeoPandas, 1.2.0 changelog and GeoDataFrame reference; Shapely, 2.2.0 release notes and planar coordinate-system guidance; PyPI, pyproj 3.8.0 metadata; PROJ, 9.9.0 releases and 9.8.1 datum-database warning.