Skip to content

GeoAgent

image image image image Conda Recipe image Conda Downloads image

An AI agent for geospatial data analysis and visualization.

Features

  • Natural language interface for geospatial data workflows
  • 4-agent LangGraph pipeline: Planner, Data, Analysis, Visualization
  • Multi-LLM support (OpenAI, Anthropic, Google Gemini, Ollama)
  • Multi-catalog STAC search (Earth Search, Planetary Computer, USGS, NASA CMR)
  • Code transparency showing generated Python code at each step
  • Jupyter-native with interactive MapLibre maps via leafmap
  • DuckDB spatial SQL for GeoParquet and Overture Maps
  • Raster analysis with xarray, rioxarray, and rasterio
  • Vector operations with geopandas

Installation

1
pip install geoagent

With all optional dependencies:

1
pip install "geoagent[all]"

LLM Setup

GeoAgent supports multiple LLM providers. You need at least one configured to use the agent.

Supported Providers

Provider Default Model API Key Env Variable Install Extra
OpenAI gpt-4.1 OPENAI_API_KEY (included)
Anthropic claude-sonnet-4-5-20250929 ANTHROPIC_API_KEY pip install "geoagent[llm]"
Google Gemini gemini-2.5-flash GOOGLE_API_KEY pip install "geoagent[llm]"
Ollama (local) llama3.1 (none needed) pip install "geoagent[ollama]"

Setting API Keys

Set your API key as an environment variable:

1
2
3
4
5
6
7
8
# OpenAI (included by default)
export OPENAI_API_KEY="your-openai-key"

# Anthropic
export ANTHROPIC_API_KEY="your-anthropic-key"

# Google Gemini
export GOOGLE_API_KEY="your-google-key"

You can also add these to a .env file or your shell profile (~/.bashrc, ~/.zshrc).

Choosing a Provider

By default, GeoAgent auto-detects available providers by checking environment variables in order: OpenAI → Anthropic → Google → Ollama. The first available provider is used.

To specify a provider and model explicitly:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from geoagent import GeoAgent

# Use the default provider (auto-detected)
agent = GeoAgent()

# Use a specific provider
agent = GeoAgent(provider="anthropic")

# Use a specific provider and model
agent = GeoAgent(provider="openai", model="gpt-4o-mini")
agent = GeoAgent(provider="google", model="gemini-2.5-flash")

Using Ollama (Local LLMs)

To run GeoAgent with a local LLM via Ollama, no API key is needed:

1
2
3
4
5
# Install Ollama and pull a model
ollama pull llama3.1

# Install the Ollama extra
pip install "geoagent[ollama]"

1
agent = GeoAgent(provider="ollama", model="llama3.1")

Using a Custom LLM Instance

You can pass any LangChain-compatible chat model directly:

1
2
3
4
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o", temperature=0.0)
agent = GeoAgent(llm=llm)

Quick Start

1
2
3
4
5
6
from geoagent import GeoAgent

agent = GeoAgent()
result = agent.chat("Show NDVI for San Francisco in July 2024")
result.map   # displays interactive map in Jupyter
print(result.code)  # shows the generated Python code

Web UI

GeoAgent includes a Solara-based chat interface with a persistent, interactive map.

1
2
pip install "geoagent[ui]"
geoagent ui

The UI opens on a home page — click Chat to start querying. See Web UI for full details.

Architecture

GeoAgent uses a 4-agent pipeline orchestrated by LangGraph:

  1. Planner parses natural language into structured parameters
  2. Data Agent searches STAC catalogs and retrieves geospatial data
  3. Analysis Agent computes indices and statistics with transparent code generation
  4. Visualization Agent renders results on interactive leafmap MapLibre maps

License

MIT