/geopandas

name: geopandas
description: Guidance and local audit tools for Python workflows that directly use GeoPandas GeoSeries, GeoDataFrame, spatial operations, or vector-data I/O.
license: MIT
compatibility: Requires Python 3.10+ and uv. Bundled CLIs are local-only; runtime analysis requires the pinned GeoPandas stack below.
allowed-tools: Read Write Bash Glob Grep
metadata:
  version: "1.2"
  skill-author: K-Dense Inc.
  last-reviewed: "2026-07-23"

GeoPandas

Use GeoPandas for planar vector data represented as pandas-like `GeoSeries` and `GeoDataFrame` objects. This skill targets stable **GeoPandas 1.1.4** (released 2026-06-26), not the unreleased 1.2 documentation.

Reproducible environment

GeoPandas 1.1.4 requires Python 3.10+; its tagged source requires NumPy >=1.24, pandas >=2.0, Shapely >=2.0, pyproj >=3.5, pyogrio >=0.7.2, and `packaging`. This exact Python 3.12 snapshot was smoke-tested on 2026-07-23:

uv venv --python 3.12
uv pip install \
  "geopandas==1.1.4" \
  "numpy==2.5.1" \
  "pandas==3.0.5" \
  "shapely==2.1.2" \
  "pyproj==3.7.2" \
  "pyogrio==0.13.0" \
  "pyarrow==25.0.0" \
  "packaging==26.2"

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

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](references/crs-management.md).

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](references/data-structures.md).

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_