README.md

---
title: GeoQuery
emoji: 🌍
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
app_port: 7860
---

# GeoQuery
 🌍🤖

**Territorial Intelligence Platform** - Natural language interface for geospatial data analysis powered by LLMs and DuckDB Spatial.

![Status](https://img.shields.io/badge/Status-Active-success) ![Python](https://img.shields.io/badge/Python-3.11+-blue) ![Next.js](https://img.shields.io/badge/Next.js-15-black) ![License](https://img.shields.io/badge/License-MIT-green)

---

## ✨ What is GeoQuery?

GeoQuery transforms geographic data analysis by combining **Large Language Models** with **spatial databases**. Simply ask questions in natural language and get instant maps, charts, and insights.

**Example**: *"Show me hospitals in Panama City"* → Interactive map with 45 hospital locations, automatically styled with 🏥 icons.

### Key Capabilities

- 🗣️ **Conversational Queries** - Natural language instead of SQL or GIS interfaces
- 🗺️ **Auto-Visualization** - Smart choropleth maps, point markers, and heatmaps
- 📊 **Dynamic Charts** - Automatic bar, pie, and line chart generation
- 🔍 **Semantic Discovery** - Finds relevant datasets from 100+ options using AI embeddings
- 🧩 **Multi-Step Analysis** - Complex queries automatically decomposed and executed
- 💡 **Thinking Transparency** - See the LLM's reasoning process in real-time
- 🎨 **Custom Point Styles** - Icon markers for POI, circle points for large datasets

---

## 🎬 Quick Demo

### Try These Queries

| Query | What You Get |
|-------|--------------|
| "Show me all provinces colored by area" | Choropleth map with size-based gradient |
| "Where are the universities?" | Point map with 🎓 icons |
| "Compare hospital count vs school count by province" | Multi-step analysis with side-by-side bar charts |
| "Show intersections in David as circle points" | 1,288 traffic intersections as simple colored circles |
| "Population density in Veraguas" | H3 hexagon heatmap (33K cells) |

---

## 🏗️ Architecture

```
┌──────────────────────────────────────────────────────────┐
│                    Frontend (Next.js)                    │
│   Chat Interface  │  Leaflet Maps  │  Data Explorer     │
└────────────────────────┬─────────────────────────────────┘
                         │ (SSE Streaming)
┌────────────────────────┴─────────────────────────────────┐
│                  Backend (FastAPI)                       │
│  Intent Detection → Semantic Search → SQL Generation     │
│         ↓                ↓                  ↓             │
│    Gemini LLM    DataCatalog (Embeddings) DuckDB Spatial │
└──────────────────────────────────────────────────────────┘
```

It supports dynamic dataset discovery via semantic embeddings + LLM-generated spatial SQL.

📖 **[Detailed Architecture](ARCHITECTURE.md)**

---

## 🚀 Quick Start

### Prerequisites

- **Python 3.11+**
- **Node.js 18+**
- **Google AI API Key** ([Get one free](https://aistudio.google.com/app/apikey))

### Installation

```bash
# 1. Clone repository
git clone https://github.com/GerardCB/GeoQuery.git
cd GeoQuery

# 2. Backend setup
cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

# 3. Configure API key
export GEMINI_API_KEY="your-api-key-here"

# 4. Start backend
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

# 5. Frontend setup (new terminal)
cd frontend
npm install
npm run dev
```

### 🎉 Done!

Open **http://localhost:3000** and start querying!

📘 **[Detailed Setup Guide](SETUP.md)**

---

## 📂 Project Structure

```
GeoQuery/
├── backend/
│   ├── api/                    # FastAPI endpoints
│   │   └── endpoints/          # /chat, /catalog, /schema
│   ├── core/                   # Core services
│   │   ├── llm_gateway.py      # Gemini API integration
│   │   ├── geo_engine.py       # DuckDB Spatial wrapper
│   │   ├── semantic_search.py  # Embedding-based discovery
│   │   ├── data_catalog.py     # Dataset metadata management
│   │   ├── query_planner.py    # Multi-step query orchestration
│   │   └── prompts.py          # LLM system instructions
│   ├── services/               # Business logic
│   │   ├── executor.py         # Query pipeline orchestrator
│   │   └── response_formatter.py # GeoJSON/chart formatting
│   ├── data/                   # Datasets and metadata
│   │   ├── catalog.json        # Dataset registry
│   │   ├── embeddings.npy      # Vector embeddings
│   │   ├── osm/                # OpenStreetMap data
│   │   ├── admin/              # Administrative boundaries
│   │   ├── global/             # Global datasets (Kontur, etc.)
│   │   └── socioeconomic/      # World Bank, poverty data
│   └── scripts/                # Data ingestion scripts
│       ├── download_geofabrik.py
│       ├── download_hdx_panama.py
│       └── stri_catalog_scraper.py
├── frontend/
│   └── src/
│       ├── app/                # Next.js App Router pages
│       └── components/
│           ├── ChatPanel.tsx   # Chat interface with SSE
│           ├── MapViewer.tsx   # Leaflet map with layers
│           └── DataExplorer.tsx # Tabular data view
└── docs/                       # Technical documentation
    ├── backend/                # Backend deep-dives
    ├── frontend/               # Frontend architecture
    └── data/                   # Data system docs
```

---

## 🔧 Technology Stack

| Layer | Technology | Purpose |
|-------|-----------|---------|
| **LLM** | Google Gemini 2.0 | Intent detection, SQL generation, explanations |
| **Backend** | Python 3.11 + FastAPI | Async HTTP server with SSE streaming |
| **Database** | DuckDB with Spatial | In-memory spatial analytics |
| **Frontend** | Next.js 15 + React 18 | Server-side rendering + interactive UI |
| **Maps** | Leaflet 1.9 | Interactive web maps |
| **Embeddings** | sentence-transformers | Semantic dataset search |
| **Data** | GeoJSON + Parquet | Standardized geospatial formats |

---

## 📊 Available Datasets

GeoQuery currently includes 100+ datasets across multiple categories:

### Administrative
- Panama provinces, districts, corregimientos (HDX 2021)
- Comarca boundaries
- Electoral districts

### Infrastructure
- Roads and highways (OpenStreetMap)
- Hospitals and health facilities (986 locations)
- Universities and schools (200+ institutions)
- Airports, ports, power plants

### Socioeconomic
- World Bank development indicators
- Multidimensional poverty index (MPI)
- Population density (Kontur H3 hexagons - 33K cells)

### Natural Environment
- Protected areas (STRI GIS Portal)
- Forest cover and land use
- Rivers and water bodies

📖 **[Full Dataset List](docs/data/DATASET_SOURCES.md)** | **[Adding New Data](docs/backend/SCRIPTS.md)**

---

## 💡 How It Works

1. **User Query**: "Show me hospitals in Panama City"
2. **Intent Detection**: LLM classifies as MAP_REQUEST
3. **Semantic Search**: Finds `panama_healthsites_geojson` via embeddings
4. **SQL Generation**: LLM creates: `SELECT name, geom FROM panama_healthsites_geojson WHERE ST_Intersects(geom, (SELECT geom FROM pan_admin2 WHERE adm2_name = 'Panamá'))`
5. **Execution**: DuckDB Spatial runs query → 45 features
6. **Visualization**: Auto-styled map with 🏥 icons
7. **Explanation**: LLM streams natural language summary

**Streaming**: See the LLM's thinking process in real-time via Server-Sent Events.

📖 **[Detailed Data Flow](docs/DATA_FLOW.md)** | **[LLM Integration](docs/backend/LLM_INTEGRATION.md)**

---

## 🗺️ Advanced Features

### Choropleth Maps
Automatically detects numeric columns and creates color gradients:
- **Linear scale**: For area, count
- **Logarithmic scale**: For population, density

### Point Visualization Modes
- **Icon markers** 🏥🎓⛪: For categorical POI (<500 points)
- **Circle points** ⭕: For large datasets like intersections (>500 points)

### Spatial Operations
- Intersection: "Find hospitals within protected areas"
- Difference: "Show me areas outside national parks"
- Buffer: "Show 5km radius around hospitals"

### Multi-Step Queries
Complex questions automatically decomposed:
- "Compare population density with hospital coverage by province"
  1. Calculate population per province
  2. Count hospitals per province
  3. Compute ratios
  4. Generate comparison chart

---

## 📚 Documentation

| Document | Description |
|----------|-------------|
| **[ARCHITECTURE.md](ARCHITECTURE.md)** | System design, components, decisions |
| **[SETUP.md](SETUP.md)** | Development environment setup |
| **[docs/backend/CORE_SERVICES.md](docs/backend/CORE_SERVICES.md)** | Backend services reference |
| **[docs/backend/API_ENDPOINTS.md](docs/backend/API_ENDPOINTS.md)** | API endpoint documentation |
| **[docs/frontend/COMPONENTS.md](docs/frontend/COMPONENTS.md)** | React component architecture |
| **[docs/DATA_FLOW.md](docs/DATA_FLOW.md)** | End-to-end request walkthrough |

---

## 📄 License

MIT License - see **[LICENSE](LICENSE)** for details.

---

## 🙏 Acknowledgments

**Data Sources**:
- [OpenStreetMap](https://www.openstreetmap.org/) - Infrastructure and POI data
- [Humanitarian Data Exchange (HDX)](https://data.humdata.org/) - Administrative boundaries
- [World Bank Open Data](https://data.worldbank.org/) - Socioeconomic indicators
- [Kontur Population Dataset](https://data.humdata.org/organization/kontur) - H3 population grid
- [STRI GIS Portal](https://stridata-si.opendata.arcgis.com/) - Environmental datasets

**Technologies**:
- [Google Gemini](https://ai.google.dev/) - LLM API
- [DuckDB](https://duckdb.org/) - Fast in-process analytics
- [Leaflet](https://leafletjs.com/) - Interactive maps
- [Next.js](https://nextjs.org/) - React framework