Geopandas

GeoPandas

Use GeoPandas for planar vector data represented as pandas-like GeoSeries and GeoDataFrame objects. This skill targets stable GeoPandas 1.2.0 (released 2026-09-28). The stable website currently carries a development build label; release-specific behavior below was checked against the v1.2.0 source and wheel.

Reproducible environment

GeoPandas 1.2.0 requires Python 3.11+, NumPy >=2, pandas >=2.2, Shapely >=2.1, pyproj >=3.7, pyogrio >=0.8, and packaging. The current pyproj wheel below requires Python 3.12+. This exact Python 3.12 snapshot was smoke-tested on 2026-10-01:

uv venv --python 3.12
uv pip install \
  "geopandas==1.2.0" \
  "numpy==2.5.3" \
  "pandas==3.0.6" \
  "shapely==2.1.2" \
  "pyproj==3.8.0" \
  "pyogrio==0.13.0" \
  "pyarrow==25.0.1" \
  "packaging==26.3"

Keep optional plotting and PostGIS packages pinned in the project lock as well. Do not mix binary geospatial packages from incompatible package channels.

Workflow

1. Inspect a vetted local layer with vector_inventory.py; retain source hashes.
2. Use crs_reprojection_plan.py to inspect candidate transformations. It plans only: execute an appropriate to_crs()/pyproj transformation separately.
3. Audit geometry with geometry_validity_report.py; compare simulated repair changes before requesting its optional new GeoPackage output.
4. Run the intended analysis with explicit predicates, CRS units, precision, and aggregation rules. spatial_join_audit.py measures join cardinality; it does not export joined features or perform a dissolve.
5. Use export_plan.py to inspect the proposed contract, then write and reopen the actual output separately. A successful plan has not written a file.
6. Review disclosure and generalization before sharing derived geodata/maps, using sensitive_coordinates_checklist.py when sensitive locations occur.

Examples below use synthetic or placeholder local inputs. File/database examples need the named dataset or service; PostGIS and tile-provider calls were reviewed against upstream contracts but were not exercised against a live service.

Safety and privacy contract

• Treat exact coordinates, addresses, parcel boundaries, trajectories, and small-area joins as sensitive. Default reports to counts, categories, coarse extents, and redacted identifiers. Generalize before publication.
• Never automatically load a URL, cloud URI, GDAL /vsi* path, archive, or geocode an address. Obtain explicit approval, validate provenance and hashes, then stage an unpacked local file in an isolated workspace.
• GDAL/OGR drivers, GEOS, PROJ, pyogrio, Shapely, pyproj, and their wheels are a native-code trust boundary. Prefer official wheels/conda-forge, record native versions, restrict drivers, and process untrusted data in a sandbox.
• Do not open macro-enabled office files or nested archives through permissive GDAL drivers. The bundled CLIs use an extension allowlist and reject archives.
• Read only named database secrets such as GEOPANDAS_POSTGIS_PASSWORD; use a secret manager or scoped environment variable. Never embed a password in a URL or source, print an engine/URL, or dump the environment.
• Every derived artifact needs source hashes/versions, CRS, operation parameters, predicate, join cardinality, precision/repair choices, and row-count checks.

Correctness gates

Apply these gates before trusting a result:

1. Identity and provenance — identify the source layer, stable feature key, duplicate IDs, row count, geometry column, parser/driver, and content hash.
2. Geometry state — count null, empty, invalid, mixed, Z/M, and collapsed geometries separately. None is missing; an empty Shapely geometry is real.
3. CRS semantics — require CRS metadata. set_crs() assigns metadata; to_crs() transforms coordinates. Never guess a CRS from coordinate ranges.
4. Units and operation — GeoPandas is planar. Geographic coordinates are angular; do not use them directly for buffer, distance, area, nearest joins, precision grids, or tolerances. Choose a fit-for-purpose local/equal-area CRS or a geodesic method.
5. Transform quality — inspect axis order, area of use, datum pipeline, expected accuracy, ballpark status, and missing grids. Keep PROJ network disabled unless the user explicitly approves grid retrieval.
6. Topology and precision — validate before and after repair/overlay. Pick a precision grid from source accuracy and CRS units; arbitrary snapping can collapse features or create bias.
7. Cardinality — state expected one-to-one, one-to-many, or many-to-many behavior before merge, sjoin, or sjoin_nearest; audit unmatched and multiplied rows afterward.
8. Output contract — use a new output path, preserve a stable feature ID, document schema/CRS/encoding, reopen the artifact, and compare counts/types.

CRS and antimeridian rules

GeoPandas stores CRS as pyproj.CRS. Coordinate arrays use traditional GIS (x, y) order, while authority definitions can advertise latitude-first axes. Use Transformer(..., always_xy=True) for explicit coordinate-array pipelines, and record that choice.

to_crs() transforms vertices and assumes each segment is straight in the source CRS; it does not transform geodesic arcs. Geometries crossing ±180° or a projection boundary can be badly wrapped. Detect crossings, split/unwrap and densify in a documented geographic representation, transform parts, then validate. Do not use Web Mercator as a general measurement CRS.

crs = gdf.crs  # a pyproj.CRS when present
if crs is None or crs.is_geographic:
    raise ValueError("Choose a justified projected CRS before planar measurement")

unit_names = [axis.unit_name for axis in crs.axis_info]
areas = gdf.geometry.area  # square CRS units, not automatically square metres

See CRS management.

Core API decisions

Data structures

• A GeoDataFrame can hold multiple geometry columns, each with CRS metadata, but only active_geometry_name drives frame-level spatial operations.
• Binary GeoSeries methods are row-wise and align by index by default. Use align=False only when positional pairing is explicitly intended and lengths and order were verified.
• Duplicate column names and duplicate feature IDs are ambiguous; reject or resolve them before joins and exports.

See data structures.

Geometry validity, precision, and union

Use is_valid and redacted is_valid_reason() categories before make_valid(method="linework"|"structure", keep_collapsed=...). Repair can change geometry type or dimension; retain the original and compare counts, area, types, empties, and collapsed parts.

set_precision(grid_size, mode=...) uses CRS units and may remove duplicate vertices or collapse features. union_all(method="unary", grid_size=...) is the robust default. Use coverage only after is_valid_coverage() proves non-overlap and edge matching; use disjoint_subset with Shapely >=2.1 when its partitioning assumption is useful.

See geometric operations.

Joins, overlay, clip, and dissolve

• Spatial joins ignore the third dimension. Features at different elevations can still match in XY. For discrete floors, strata, or survey dates, use a validated shared attribute restriction (on_attribute) when scientifically appropriate; true 3D distance or intersection requires a method that models Z.
• sjoin predicates are directional: left.within(right) is not left.contains(right). intersects includes boundary contact; contains excludes boundary-only points, while covers includes boundary points.
• predicate="dwithin" requires distance; scalar or per-left-row distances are in CRS units. sjoin_nearest returns all equidistant nearest matches and does not implement a k= parameter.
• overlay(..., make_valid=True) repairs invalid input but can change types; keep_geom_type=None drops other types with a warning. Precision mismatch can create slivers; quantify them rather than silently deleting them.
• clip dissolves the mask. Rectangle clipping is fast but possibly dirty and may omit a line collapsed to a point; validate its output.
• dissolve combines groupby.agg with union_all; choose explicit attribute aggregations and audit null group keys.

See spatial analysis.