Hugging Face's logo

Spaces:
GerardCB
/
GeoQuery
Running

App Files Community
GeoQuery / README.md
GerardCB's picture
GerardCB
Deploy to Spaces (Final Clean)
4851501
preview code
|
raw
history blame contribute delete
10.6 kB
metadata
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 Python Next.js License

✨ 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

🚀 Quick Start

Prerequisites

Installation 

# 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

📂 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 | Adding New Data

💡 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 | LLM Integration

🗺️ 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 System design, components, decisions
SETUP.md Development environment setup
docs/backend/CORE_SERVICES.md Backend services reference
docs/backend/API_ENDPOINTS.md API endpoint documentation
docs/frontend/COMPONENTS.md React component architecture
docs/DATA_FLOW.md End-to-end request walkthrough

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Data Sources:

Technologies: