194 added, 192 removed. Audit A to A.
---
name: geopandas
- description: Python library for working with geospatial vector data including shapefiles, GeoJSON, and GeoPackage files. Use when working with geographic data for spatial analysis, geometric operations, coordinate transformations, spatial joins, overlay operations, choropleth mapping, or any task involving reading/writing/analyzing vector geographic data. Supports PostGIS databases, interactive maps, and integration with matplotlib/folium/cartopy. Use for tasks like buffer analysis, spatial joins between datasets, dissolving boundaries, clipping data, calculating areas/distances, reprojecting coordinate systems, creating maps, or converting between spatial file formats.
- license: BSD-3-Clause license
- metadata: {"version": "1.0", "skill-author": "K-Dense Inc."}
+ 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.1"
+ skill-author: K-Dense Inc.
+ last-reviewed: "2026-07-23"
---
# GeoPandas
- GeoPandas extends pandas to enable spatial operations on geometric types. It combines the capabilities of pandas and shapely for geospatial data analysis.
-
- ## Installation
+ 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.
- ```bash
- uv pip install geopandas
- ```
+ ## Reproducible environment
- ### Optional Dependencies
+ 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:
```bash
- # For interactive maps
- uv pip install folium
-
- # For classification schemes in mapping
- uv pip install mapclassify
-
- # For faster I/O operations (2-4x speedup)
- uv pip install pyarrow
-
- # For PostGIS database support
- uv pip install psycopg2
- uv pip install geoalchemy2
-
- # For basemaps
- uv pip install contextily
-
- # For cartographic projections
- uv pip install cartopy
- ```
-
- ## Quick Start
-
- ```python
- import geopandas as gpd
-
- # Read spatial data
- gdf = gpd.read_file("data.geojson")
-
- # Basic exploration
- print(gdf.head())
- print(gdf.crs)
- print(gdf.geometry.geom_type)
-
- # Simple plot
- gdf.plot()
-
- # Reproject to different CRS
- gdf_projected = gdf.to_crs("EPSG:3857")
-
- # Calculate area (use projected CRS for accuracy)
- gdf_projected['area'] = gdf_projected.geometry.area
-
- # Save to file
- gdf.to_file("output.gpkg")
- ```
-
- ## Core Concepts
-
- ### Data Structures
-
- - **GeoSeries**: Vector of geometries with spatial operations
- - **GeoDataFrame**: Tabular data structure with geometry column
-
- See [data-structures.md](references/data-structures.md) for details.
-
- ### Reading and Writing Data
-
- GeoPandas reads/writes multiple formats: Shapefile, GeoJSON, GeoPackage, PostGIS, Parquet.
-
- ```python
- # Read with filtering
- gdf = gpd.read_file("data.gpkg", bbox=(xmin, ymin, xmax, ymax))
-
- # Write with Arrow acceleration
- gdf.to_file("output.gpkg", use_arrow=True)
+ 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"
```
- See [data-io.md](references/data-io.md) for comprehensive I/O operations.
-
- ### Coordinate Reference Systems
+ Keep optional plotting and PostGIS packages pinned in the project lock as well.
+ Do not mix binary geospatial packages from incompatible package channels.
- Always check and manage CRS for accurate spatial operations:
+ ## Safety and privacy contract
- ```python
- # Check CRS
- print(gdf.crs)
+ - 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.
- # Reproject (transforms coordinates)
- gdf_projected = gdf.to_crs("EPSG:3857")
+ ## Correctness gates
- # Set CRS (only when metadata missing)
- gdf = gdf.set_crs("EPSG:4326")
- ```
+ Apply these gates before trusting a result:
- See [crs-management.md](references/crs-management.md) for CRS operations.
+ 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.
- ## Common Operations
+ ## CRS and antimeridian rules
- ### Geometric Operations
+ 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.
- Buffer, simplify, centroid, convex hull, affine transformations:
+ `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.
```python
- # Buffer by 10 units
- buffered = gdf.geometry.buffer(10)
-
- # Simplify with tolerance
- simplified = gdf.geometry.simplify(tolerance=5, preserve_topology=True)
+ 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")
- # Get centroids
- centroids = gdf.geometry.centroid
+ unit_names = [axis.unit_name for axis in crs.axis_info]
+ areas = gdf.geometry.area # square CRS units, not automatically square metres
```
- See [geometric-operations.md](references/geometric-operations.md) for all operations.
-
- ### Spatial Analysis
-
- Spatial joins, overlay operations, dissolve:
-
- ```python
- # Spatial join (intersects)
- joined = gpd.sjoin(gdf1, gdf2, predicate='intersects')
+ See [CRS management](references/crs-management.md).
- # Nearest neighbor join
- nearest = gpd.sjoin_nearest(gdf1, gdf2, max_distance=1000)
+ ## Core API decisions
- # Overlay intersection
- intersection = gpd.overlay(gdf1, gdf2, how='intersection')
+ ### Data structures
- # Dissolve by attribute
- dissolved = gdf.dissolve(by='region', aggfunc='sum')
- ```
+ - 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 [spatial-analysis.md](references/spatial-analysis.md) for analysis operations.
+ See [data structures](references/data-structures.md).
- ### Visualization
+ ### Geometry validity, precision, and union
- Create static and interactive maps:
+ 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.
- ```python
- # Choropleth map
- gdf.plot(column='population', cmap='YlOrRd', legend=True)
+ `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.
- # Interactive map
- gdf.explore(column='population', legend=True).save('map.html')
+ See [geometric operations](references/geometric-operations.md).
- # Multi-layer map
- import matplotlib.pyplot as plt
- fig, ax = plt.subplots()
- gdf1.plot(ax=ax, color='blue')
- gdf2.plot(ax=ax, color='red')
- ```
+ ### Joins, overlay, clip, and dissolve
- See [visualization.md](references/visualization.md) for mapping techniques.
+ - `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.
- ## Detailed Documentation
+ See [spatial analysis](references/spatial-analysis.md).
- - **[Data Structures](references/data-structures.md)** - GeoSeries and GeoDataFrame fundamentals
- - **[Data I/O](references/data-io.md)** - Reading/writing files, PostGIS, Parquet
- - **[Geometric Operations](references/geometric-operations.md)** - Buffer, simplify, affine transforms
- - **[Spatial Analysis](references/spatial-analysis.md)** - Joins, overlay, dissolve, clipping
- - **[Visualization](references/visualization.md)** - Plotting, choropleth maps, interactive maps
- - **[CRS Management](references/crs-management.md)** - Coordinate reference systems and projections
+ ### I/O, Arrow, and PostGIS
- ## Common Workflows
+ GeoPandas 1.x defaults to pyogrio. Driver availability and semantics come from
+ the installed GDAL, not GeoPandas alone. Prefer local GeoPackage for general
+ interchange and WKB GeoParquet for columnar interoperability.
- ### Load, Transform, Analyze, Export
+ GeoParquet defaults to stable schema 1.0.0. Native GeoArrow encodings and bbox
+ covering require schema 1.1.0 and remain less interoperable. A missing GeoParquet
+ `crs` key means `OGC:CRS84`; explicit `crs: null` means unknown—do not conflate
+ them. Reopen and validate every export.
- ```python
- # 1. Load data
- gdf = gpd.read_file("data.shp")
+ Use parameterized SQL and a SQLAlchemy `Engine`/`Connection` for PostGIS.
+ `if_exists="replace"` is destructive; default to `"fail"` and use a transaction.
- # 2. Check and transform CRS
- print(gdf.crs)
- gdf = gdf.to_crs("EPSG:3857")
+ See [data I/O](references/data-io.md).
- # 3. Perform analysis
- gdf['area'] = gdf.geometry.area
- buffered = gdf.copy()
- buffered['geometry'] = gdf.geometry.buffer(100)
+ ## Migration checklist
- # 4. Export results
- gdf.to_file("results.gpkg", layer='original')
- buffered.to_file("results.gpkg", layer='buffered')
- ```
+ For code moving from GeoPandas 0.14 or earlier:
- ### Spatial Join and Aggregate
+ - GeoPandas 1.0 supports Shapely >=2 only; PyGEOS, Shapely <2, and the rtree
+ spatial-index backend were removed.
+ - pyogrio replaced Fiona as the installed/default I/O engine. Set `engine=`
+ explicitly and test schema, empty, datetime, encoding, and append behavior.
+ - Replace `sjoin(op=...)` with `predicate=`, `sindex.query_bulk()` with
+ `sindex.query()`, `unary_union` with `union_all()`, and
+ `GeometryArray.data` with `to_numpy()`/`np.asarray`.
+ - Replace `read_file(include_fields=...|ignore_fields=...)` with `columns=`.
+ Use `schema_version=`, not the removed GeoParquet `version=` compatibility.
+ - Do not use removed `geopandas.datasets`, internal `geopandas.io.*` entry
+ points, plot `axes`/`colormap`, or set-operation operators.
+ - `explode()` now defaults `index_parts=False`; a named Series passed to
+ `set_geometry()` supplies the new active-column name; a named right index can
+ replace `index_right` in `sjoin` output.
+ - Do not assign `.crs` to override metadata or rely on deprecated
+ `set_geometry(drop=...)`; use explicit `set_crs()` and rename/drop steps.
+ - GeoPandas 1.1 requires Python >=3.10, pandas >=2.0, NumPy >=1.24, and pyproj
+ >=3.5. Version 1.1.2 fixed SQL injection through a PostGIS geometry-column
+ name; the pinned 1.1.4 includes that fix.
- ```python
- # Join points to polygons
- points_in_polygons = gpd.sjoin(points_gdf, polygons_gdf, predicate='within')
+ ### Plotting and exploration
- # Aggregate by polygon
- aggregated = points_in_polygons.groupby('index_right').agg({
- 'value': 'sum',
- 'count': 'size'
- })
+ Maps are analytical outputs: label units, classification method, missing data,
+ normalization denominator, and date. `explore()` can expose every attribute in
+ tooltips/popups and contact tile/CDN servers; generalize first and use
+ `tiles=None`, `tooltip=False`, and `popup=False` for a local draft.
- # Merge back to polygons
- result = polygons_gdf.merge(aggregated, left_index=True, right_index=True)
- ```
+ See [visualization](references/visualization.md).
- ### Multi-Source Data Integration
+ ## Bundled local CLIs
- ```python
- # Read from different sources
- roads = gpd.read_file("roads.shp")
- buildings = gpd.read_file("buildings.geojson")
- parcels = gpd.read_postgis("SELECT * FROM parcels", con=engine, geom_col='geom')
+ All helpers are deterministic, reject network/archive paths, bound input bytes
+ and feature counts, keep imports lazy so `--help` is dependency-free, and emit
+ JSON without coordinates or record identifiers.
- # Ensure matching CRS
- buildings = buildings.to_crs(roads.crs)
- parcels = parcels.to_crs(roads.crs)
+ | CLI | Purpose |
+ |---|---|
+ | `scripts/vector_inventory.py` | Redacted local vector/GeoParquet technical inventory |
+ | `scripts/crs_reprojection_plan.py` | CRS units, axes, candidate transform and antimeridian plan |
+ | `scripts/geometry_validity_report.py` | Dry-run validity audit; optional repair to a new GeoPackage |
+ | `scripts/spatial_join_audit.py` | Predicate semantics, duplicate IDs and join cardinality |
+ | `scripts/export_plan.py` | Non-executing vector/GeoParquet export contract |
+ | `scripts/sensitive_coordinates_checklist.py` | Privacy/generalization release gate |
- # Perform spatial operations
- buildings_near_roads = buildings[buildings.geometry.distance(roads.union_all()) < 50]
+ ```bash
+ python skills/geopandas/scripts/vector_inventory.py --help
+ python skills/geopandas/scripts/crs_reprojection_plan.py \
+ --source-crs EPSG:4326 --target-crs EPSG:32631
+ python skills/geopandas/scripts/geometry_validity_report.py data.gpkg
+ python skills/geopandas/scripts/spatial_join_audit.py points.gpkg zones.gpkg \
+ --predicate within --left-id point_id --right-id zone_id
+ python skills/geopandas/scripts/export_plan.py data.gpkg result.parquet \
+ --format geoparquet --schema-version 1.0.0 \
+ --stable-id-column feature_id --id-unique-verified
+ python skills/geopandas/scripts/sensitive_coordinates_checklist.py \
+ --public-output --precise-points --contains-addresses
```
- ## Performance Tips
-
- 1. **Use spatial indexing**: GeoPandas creates spatial indexes automatically for most operations
- 2. **Filter during read**: Use `bbox`, `mask`, or `where` parameters to load only needed data
- 3. **Use Arrow for I/O**: Add `use_arrow=True` for 2-4x faster reading/writing
- 4. **Simplify geometries**: Use `.simplify()` to reduce complexity when precision isn't critical
- 5. **Batch operations**: Vectorized operations are much faster than iterating rows
- 6. **Use appropriate CRS**: Projected CRS for area/distance, geographic for visualization
+ ## Reference index
- ## Best Practices
+ - [Data structures](references/data-structures.md)
+ - [CRS management](references/crs-management.md)
+ - [Geometric operations](references/geometric-operations.md)
+ - [Spatial analysis](references/spatial-analysis.md)
+ - [Data I/O](references/data-io.md)
+ - [Visualization](references/visualization.md)
- 1. **Always check CRS** before spatial operations
- 2. **Use projected CRS** for area and distance calculations
- 3. **Match CRS** before spatial joins or overlays
- 4. **Validate geometries** with `.is_valid` before operations
- 5. **Use `.copy()`** when modifying geometry columns to avoid side effects
- 6. **Preserve topology** when simplifying for analysis
- 7. **Use GeoPackage** format for modern workflows (better than Shapefile)
- 8. **Set max_distance** in sjoin_nearest for better performance
+ ## Sources (verified 2026-07-23)
+ - [GeoPandas 1.1.4 on PyPI](https://pypi.org/project/geopandas/1.1.4/) — released 2026-06-26.
+ - [GeoPandas 1.1.4 release](https://github.com/geopandas/geopandas/releases/tag/v1.1.4) — bug-fix release.
+ - [GeoPandas 1.1.4 tagged dependencies](https://github.com/geopandas/geopandas/blob/v1.1.4/pyproject.toml).
+ - [Stable GeoPandas documentation](https://geopandas.org/en/stable/).
+ - [GeoPandas 1.0 migration release](https://github.com/geopandas/geopandas/releases/tag/v1.0.0).