Earth Copilot: Query Geospatial Data Using Natural Language

Earth Copilot is an AI agent designed for geospatial analysis. It allows users to interact with data using natural language, automatically identifying the necessary satellite imagery, constructing STAC queries, and generating map visualizations. This eliminates the need for manual catalog searches.

The system is built on a specialized AI agent framework. It interprets complex scientific inquiries, selects appropriate datasets from over 126 public STAC collections within the Microsoft Planetary Computer, and integrates with private data sources. Beyond visual maps, it provides explanations of environmental events and trends by applying Retrieval-Augmented Generation (RAG) over stored datasets.

What It Does

Map Queries Users submit questions through the React UI. The system routes these requests via Azure Functions to the Semantic Kernel, which interfaces with the Microsoft Planetary Computer STAC APIs to render the requested map.

Contextual Answers For inquiries regarding environmental trends or impacts, the system provides context directly to the LLM. The resulting analysis is displayed in the chat window without requiring a map visualization.

Private Data + RAG Users can specify a data catalog to begin their search. The query is then processed alongside the NASA VEDA AI search index and the LLM, blending public datasets with private information to generate a comprehensive response.

Core Architecture

API Management Manages request routing and implements rate limiting (throttling).

Azure AI Foundry The central intelligence engine. It hosts the LLM (GPT-5) and facilitates natural language understanding.

App Service Manages authentication and managed identity protocols.

Router Function App The translation layer. It converts plain English into STAC parameters, resolves geographic place names into coordinates, parses time-based expressions, selects the appropriate satellite collections, and communicates with the Microsoft Planetary Computer.

Microsoft Planetary Computer (MPC) The primary data source, providing STAC APIs to access petabytes of Earth science imagery.

Azure Maps Provides geocoding services and map rendering.

Azure AI Search Handles vector search and document indexing.

Key Code Modules

• React UI (earth-copilot/react-ui/): Includes the unified search bar, chat interface, map components, and the data catalog panel.
• Router Function App (earth-copilot/router-function-app/): Manages semantic translation, multi-strategy geocoding, time parsing, collection mapping, and STAC integration.
• Core Infrastructure (earth-copilot/core/): Manages configurations, structured logging, and error recovery processes.

Setup and Usage

Prerequisites

To deploy and maintain this system, proficiency in the following is required:

• Azure services (AI Foundry, Maps, Functions, and AI Search)
• Python backend development and Azure Functions
• React and TypeScript with Vite
• LLMs, Semantic Kernel, and basic Natural Language Processing (NLP)
• Geospatial data structures and the SpatioTemporal Asset Catalog (STAC)
• Bicep templates for Azure infrastructure deployment
• Environment variable and secrets management

Deployment Options

The application can be run locally in VS Code using a proxy, through your preferred IDE, or via GitHub Codespaces with a single-click setup.

Azure Services Setup

Refer to the AZURE_SETUP_GUIDE.md for a detailed walkthrough. The core required services include:

Required

• Azure AI Foundry (GPT-5 deployment)
• Azure Maps
• Azure Function App
• Azure AI Search

Optional

• Application Insights for system monitoring
• Key Vault for secure secrets management
• Static Web Apps for production-grade hosting

Data Sources

• Microsoft Planetary Computer STAC APIs: A global catalog for satellite imagery.
• NASA VEDA: Earth science datasets derived from NASA missions and research projects.

Environment Variables

Configuration is required in three specific locations. Copy the provided example files and input your Azure credentials.

Root Directory: Create a .env file from .env.example for backend API credentials.

React UI: Create a .env file in earth-copilot/react-ui/ from .env.example. Ensure variables are prefixed with VITE_.

Function App: Configure local.settings.json in earth-copilot/router-function-app/ using local.settings.json.example.

Start the Application

1. Create Azure Services: Follow the steps in AZURE_SETUP_GUIDE.md.
2. Launch: Use STARTUP_GUIDE.md for automated, VS Code-based, or manual startup procedures.
3. Troubleshoot: Refer to SYSTEM_REQUIREMENTS.md for information on dependencies and compatibility.

Common Commands

Earth Copilot uses Semantic Kernel version 1.36.2. The setup script manages this dependency automatically.

# Initial setup after Azure services are provisioned
./setup-all-services.sh

# Start all services (recommended)
./run-all-services.sh

# Manual development (requires two terminals)
# Terminal 1: Backend
cd earth-copilot/router-function-app && func host start

# Terminal 2: Frontend
cd earth-copilot/react-ui && npm run dev

# Access the application at http://localhost:5173

Before starting, run python verify-requirements.py to ensure environment compatibility.

Data Catalog

Based on current Microsoft Planetary Computer availability, the following datasets are optimized for use: