geopandas – Security skill for AI agents

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](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_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](references/geometric-operations.md).

Joins, overlay, clip, and dissolve

• [Spatial joins ignore the third dimension](https://geopandas.org/en/stable/docs/reference/api/geopandas.sjoin.html).

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](references/spatial-analysis.md).

I/O, Arrow, and PostGIS

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.

GeoParquet defaults to stable schema 1.1.0 in GeoPandas 1.2. Set

schema_version="1.0.0" explicitly for an old

… (full content is in the download package)