Geosql: A Claude/Codex skill for geospatial data
GeoSQL: Empowering AI Agents with Geospatial Intelligence
GeoSQL is a specialized skill designed to transform LLMs—specifically Claude, Codex, and GitHub Copilot—into proficient geospatial analytics agents. It bridges the gap between natural language and complex spatial databases like PostGIS, BigQuery, Snowflake, and Wherobots.
🚀 Getting Started
To integrate GeoSQL into your workflow, follow these steps:
Installation Checklist
- Install the core package via Python:
pip install geosql - Deploy to your preferred AI agent:
- For Claude:
geosql install claude - For Codex:
geosql install codex - For Copilot:
geosql install copilot
- For Claude:
- Alternatively, if using Claude Code:
/plugin marketplace add dekart-xyz/geosql /plugin install geosql
Once installed in VS Code Copilot or the Copilot CLI, you can trigger the skill using the /geosql command.
Example Prompt:
/geosql Show EV charger density along major roads and render a map
🗺️ Visualizing Data with Dekart
GeoSQL leverages Dekart, an open-source backend for Kepler.gl, to handle map rendering and database connectivity. You have three hosting options:
- Dekart Cloud: No setup required.
- Self-Hosted: Deploy on your own infrastructure.
- Local Docker: Run the following command:
docker run -p 8080:8080 dekartxyz/dekart
To finalize the connection, install the CLI and initialize:
pip install dekart && dekart init
🛠️ Core Capabilities & Nuances
GeoSQL doesn't just "guess" how to write queries; it employs a sophisticated operational loop:
- Schema Awareness: Instead of
guessing schemas, the skill actively explores your warehouse metadata (columns, types, and tables). - Engine Optimization: It generates dialect-specific spatial SQL, utilizing functions like
ST_INTERSECTS,ST_DISTANCE,H3indexing, and bounding box (bbox) overlaps for efficient partition pruning. - Budgetary Guardrails: On BigQuery, the agent performs a dry-run to estimate data consumption. If a query is too expensive, the agent automatically rewrites it to be leaner (e.g., by reducing H3 resolution or tightening the
bbox). - Validation Logic: The agent performs sanity checks by calculating total length for lines or total area for polygons to ensure results align with domain knowledge.
- Security First: Credentials are never sent to the LLM. GeoSQL utilizes your local CLI authentication (e.g.,
bq,snow,dekart).
The "Map-in-Loop" Workflow
The true power of GeoSQL lies in its visual feedback loop.
📊 Performance & Benchmarks
GeoSQL includes a rigorous evaluation suite located in evals/. Unlike simple Q&A tests, these assert specific behaviors, including cost-guarding and validation steps.
Evaluation Results
| Case | Assertions | Pass Rate |
|---|---|---|
london-boroughs | 4 | 100% |
berlin-create-map | 3 | 100% |
paris-boundaries | 1 | 100% |
| Total | 8 | 100% |
Metrics:
- Avg. Tokens/Turn: 3,085
- Avg. Duration/Turn: 72s
The Visual Advantage
The integration of map rendering provides a improvement in accuracy.
![Placeholder for 4x Improvement Chart]
Without visual feedback, agents often commit "geometry-class errors," such as:
- Confusing a neighborhood polygon with a city perimeter.
- Double-counting overlapping features.
- Selecting incorrect join keys due to Coordinate Reference System (CRS) mismatches.
💡 Example Use Cases
You can challenge your agent with complex spatial requests:
Real Estate:
/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.
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.
📁 Repository Details
- License: MIT
- Language Composition:
- Python:
86.2% - Makefile:
12.1% - Shell:
1.7%
- Python:
- Testing: Run the suite via
python evals/run.py(seeevals/RUNBOOK.mdfor setup).