GeoSQL: Turning LLMs into Geospatial Analytics Agents

GeoSQL is a new open-source skill that turns AI coding assistants like Claude, Codex, and GitHub Copilot into geospatial analytics agents. It works with PostGIS, BigQuery, Snowflake, and Wherobots — and runs entirely locally or self-hosted, no SaaS account required.

Quick Start

Install via pip and launch interactive mode:

pip install geosql && geosql

Or install directly into a supported agent:

geosql install claude
geosql install codex
geosql install copilot

For Claude Code, use the plugin marketplace:

/plugin marketplace add dekart-xyz/geosql
/plugin install geosql

After installation, you can use prompts like:

/geosql Show EV charger density along major roads and render a map

How It Works

GeoSQL runs an agent loop that includes a map. The process has five stages:

1. Discovery. The skill explores your warehouse metadata (tables, columns, types) instead of guessing schemas. Works with Overture Maps shares on BigQuery and Snowflake, and private tables on supported databases.
2. SQL generation. The agent writes spatial SQL using the correct functions for your engine (ST_INTERSECTS, ST_DISTANCE, H3, bbox overlap for partition pruning, etc.).
3. Cost check. On BigQuery, every query is dry-run first to estimate bytes scanned. A 10 GiB billing cap is enforced by default. Over-budget queries are rewritten cheaper (tighter bbox, lower H3 resolution, more filters) instead of executed.
4. Geometry validation. The agent computes total area (polygons) or total length (lines) as a sanity check, and cross-checks against domain knowledge.
5. Map feedback. When available, the agent renders the result through Dekart, looks at the rendered image, and corrects geometry mistakes that a text-only loop would miss. This is the loop that yields the 4x improvement.

The skill uses your local CLI authentication (bq, snow, dekart), so warehouse credentials never go to the agent.

Benchmarks

GeoSQL ships with a reproducible eval suite under evals/. Each case asserts specific behaviors (cost guardrails, validation steps, correct result), not just "did the agent answer." Current results on the included suite: 8 assertions across 3 cases, 100% pass rate. Average: 3,085 tokens per turn, 72 seconds duration per turn.

The 4x improvement chart compares the same task set with and without the map-in-loop step. Without maps, the agent's text-only validation misses geometry-class errors (mistaking a neighborhood polygon for a metro-area perimeter, double-counting overlapping features, picking the wrong join key on coordinate-reference systems). Adding the rendered map as a tool call lets the agent see those mistakes and self-correct.

Example Prompts

Real estate analysis:

/geosql Show buildings with low school accessibility in Ottawa, render as a map

Site selection:

/geosql Find the top 10 locations for Sporting Goods Store in Seattle based on POI co-location and distance to the nearest competitor. Create a map.

EV charging infrastructure:

/geosql create map EV charger density along major Romanian roads, highlighting how many charging stations are within 5 km of each motorway, trunk, or primary road segment.