/geopandas

name: geopandas
description: >-
  Spatial data: GeoDataFrames, spatial joins, CRS/projections, choropleth/interactive maps, spatial autocorrelation, PySAL. Use for geographic data, spatial files (Shapefile, GeoPackage, GeoParquet), or spatial stats. For charts without GIS use plotly.
metadata:
  audience: research-coders
  domain: python-library
  library-version: "1.1.3"
  skill-last-updated: "2026-03-28"

GeoPandas Skill

geopandas spatial data library for Python: manipulation, analysis, and visualization of geographic data. Covers GeoDataFrames, spatial joins, CRS/projections, vector operations, raster integration (rasterio, xarray), choropleth mapping, interactive maps (folium), basemap tiles (contextily), spatial autocorrelation, and the PySAL ecosystem. Use when working with geographic data, reading/writing spatial files (Shapefile, GeoPackage, GeoParquet), making maps, or running spatial statistics. For interactive web-based geographic charts without spatial analysis, use plotly.

Comprehensive skill for spatial data analysis with geopandas and the broader Python geospatial stack. Use the decision trees below to find the right guidance, then load detailed references as needed.

Version Notes

This skill targets **geopandas 1.x** (tested with 1.1.3). Key changes from earlier versions:

• Shapely >= 2.0 required (PyGEOS backend removed, vectorized ops built-in)
• pyogrio is the default I/O engine (replacing fiona, 5-10x faster)
• `cascaded_union` removed — use `union_all()` instead
• `GeoSeries.unary_union` property renamed to `GeoSeries.union_all()` method

What is GeoPandas?

GeoPandas extends pandas with spatial data types and operations:

• **GeoDataFrame**: A pandas DataFrame with a geometry column — tabular data meets spatial operations
• **Spatial operations**: Joins, overlays, dissolve, clip, buffer, and distance calculations on vector geometries
• **CRS handling**: Coordinate reference system management via pyproj for correct spatial computations
• **Visualization**: Static maps (matplotlib), interactive maps (folium via `.explore()`), and GPU-accelerated rendering (lonboard)
• **Ecosystem hub**: Integrates with PySAL (spatial statistics), rasterio (rasters), contextily (basemaps), and mapclassify (classification schemes)

How to Use This Skill

Reference File Structure

| File | Purpose | When to Read | |------|---------|--------------| | `quickstart.md` | Installation, GeoDataFrame creation, basic I/O and plotting | Starting with geopandas | | `data-io.md` | File formats, pyogrio, web data, spatial databases | Loading/saving spatial data | | `crs-projections.md` | CRS fundamentals, reprojecting, choosing projections | CRS errors or projection decisions | | `spatial-operations.md` | Spatial joins, overlays, dissolve, clip, buffer, distance | Combining or transforming spatial data | | `raster-integration.md` | rasterio, xarray/rioxarray, zonal statistics | Working with raster data | | `visualization.md` | Static maps, interactive maps, basemaps, classification | Making maps and figures | | `pysal-spatial-stats.md` | Spatial weights, autocorrelation, LISA, spatial regression | Spatial statistics and modeling | | `gotchas.md` | CRS mismatches, invalid geometries, common errors | Debugging spatial issues |

Reading Order

1. **New to geopandas?** Start with `quickstart.md` then `spatial-operations.md` 2. **Making maps?** Read `visualization.md` (relies on `crs-projections.md` for projection choices) 3. **Spatial statistics?** Read `pysal-spatial-stats.md` (for methodology context, also load `data-scientist` skill's `geospatial-analysis.md`) 4. **Having issues?** Check `gotchas.md` first

Related Skills

• **data-scientist** (`geospatial-analysis.md`, `geospatial-operations.md`): Spatial methodology — when/why to use spatial methods, interpretation guidance, MAUP, ecological fallacy. Load alongside this skill for research workflows.
• **polars**: If spatial data is combined with large tabular datasets, use polars for non-spatial transformations before converting to GeoDataFrame.
• **plotnine / plotly**: For non-map visualizations of spatial analysis results (coefficient plots, distributions).

Quick Decision Trees

"I need to read or write spatial data"

Loading/saving spatial data?
├─ Read vector file (Shapefile, GeoPackage, GeoJSON) → ./references/data-io.md
├─ Read GeoParquet → ./references/data-io.md
├─ Read from PostGIS / DuckDB Spatial → ./references/data-io.md
├─ Download boundaries (Census, OSM) → ./references/data-io.md
├─ Create GeoDataFrame from lat/lon columns → ./references/quickstart.md
├─ Write to file → ./references/data-io.md
└─ Read raster data (GeoTIFF) → ./references/raster-integration.md

"I need to combine or transform spatial data"

Spatial operations?
├─ Join by location (point-in-polygon, etc.) → ./references/spatial-operations.md
├─ Join by nearest feature → ./references/spatial-operations.md
├─ Overlay (intersection, union, difference) → ./references/spatial-operations.md
├─ Dissolve (merge polygons by attribute) → ./references/spatial-operations.md
├─ Clip to boundary → ./references/spatial-operations.md
├─ Buffer features → ./references/spatial-operations.md
├─ Compute distances → ./references/spatial-operations.md
├─ Compute centroids or areas → ./references/spatial-operations.md
└─ Areal interpolation (mismatched boundaries) → ./references/spatial-operations.md

"I need to fix CRS or projection issues"

CRS/projection issues?
├─ Check current CRS → ./references/crs-projections.md
├─ Reproject to different CRS → ./references/crs-projections.md
├─ Choose a projection for analysis → ./references/crs-projections.md
├─ Data has no CRS (set it) → ./references/crs-projections.md
├─ CRS mismatch error → ./references/gotchas.md
└─ Area/distance calculations wrong → ./references/crs-projections.md

"I need to make a map"

Making maps?
├─ Quick static choropleth → ./references/visual