🌍 GeoAI SDK

The AI-powered geospatial toolkit for JavaScript developers

Build intelligent geospatial applications with natural language queries

🎥 See It In Action

Watch the streaming AI agent in action - each step appears in real-time!

🚀 What is GeoAI SDK?

GeoAI SDK is a powerful JavaScript library that combines AI agents with geospatial tools to create intelligent location-based applications. Ask questions in plain English and get structured geospatial data back!

// 🤖 Ask in natural language
const result = await agent.processNaturalLanguageQuery(
  "Find interesting places to visit in Berlin Mitte"
);

// 🎯 Get structured results
console.log(result.data.places); // 10+ landmarks with descriptions
console.log(result.data.location); // Geocoded coordinates
console.log(result.data.reasoning); // AI's step-by-step plan

✨ Why Choose GeoAI SDK?

Feature	GeoAI SDK	Traditional GIS Libraries
Natural Language	✅ "Find restaurants near Times Square"	❌ Complex API calls
AI Planning	✅ Multi-step workflows	❌ Manual orchestration
Universal	✅ Node.js + Browser	❌ Server-only
TypeScript	✅ Full type safety	❌ Often untyped
Extensible	✅ Plugin architecture	❌ Monolithic

🎯 Perfect For

• 🗺️ Location Intelligence Apps - Find POIs, analyze areas
• 🛰️ Satellite Imagery Analysis - Search and process STAC data
• 🏛️ Tourism & Travel - Discover landmarks and attractions
• 📊 Geospatial Analytics - Combine multiple data sources
• 🤖 AI-Powered Maps - Natural language map interactions

🚀 Quick Start

Installation

npm install geoai-sdk
# or
pnpm add geoai-sdk
# or  
yarn add geoai-sdk

30-Second Demo

import { GeoAgent } from 'geoai-sdk';

const agent = new GeoAgent({
  anthropicApiKey: 'your-api-key' // Get from https://console.anthropic.com/
});

// 🎯 One line to find places!
const result = await agent.processNaturalLanguageQuery(
  "Find landmarks around the Eiffel Tower"
);

console.log(`Found ${result.data.places.length} landmarks!`);
result.data.places.forEach(place => {
  console.log(`📍 ${place.name} (${place.distance}m away)`);
});

🛰️ STAC Satellite Imagery Search

// Search satellite imagery with natural language
const result = await agent.processNaturalLanguageQuery(
  'Find Sentinel-2 images of the Amazon rainforest from June 2023'
);

console.log(`Found ${result.data.stacResults.features.length} satellite images!`);
result.data.stacResults.features.forEach(image => {
  console.log(`🛰️ ${image.id} - ${image.properties.datetime}`);
});

🛠️ Available Tools

🗺️ Geocoding Tool

Convert addresses ↔ coordinates using OpenStreetMap

const result = await agent.executeTool('geocoding', {
  operation: 'geocode',
  address: '1600 Pennsylvania Ave NW, Washington, DC'
});
// → { coordinates: { lat: 38.8977, lng: -77.0365 }, address: "White House..." }

🛰️ STAC Search Tool

Find satellite imagery and geospatial assets

const result = await agent.executeTool('stac_search', {
  bbox: { west: -122.5, south: 47.5, east: -122.4, north: 47.6 },
  datetime: '2023-06-01/2023-06-30',
  collections: ['sentinel-2-l2a']
});
// → Array of satellite images with metadata

📖 Wikipedia Geosearch Tool

Discover points of interest near any location

const result = await agent.executeTool('wikipedia_geosearch', {
  coordinates: { latitude: 52.52, longitude: 13.405 }, // Berlin
  radius: 1000,
  limit: 10
});
// → Array of Wikipedia articles about nearby landmarks

🏪 POI Search Tool

Find points of interest using OpenStreetMap data

const result = await agent.executeTool('poi_search', {
  query: 'restaurants',
  location: { latitude: 52.52, longitude: 13.405 }, // Berlin
  radius: 1000,
  limit: 10
});
// → Array of restaurants with addresses and distances

🛣️ Routing Tool

Calculate optimal paths between locations

const result = await agent.executeTool('routing', {
  locations: [
    { latitude: 52.52, longitude: 13.405 }, // Berlin
    { latitude: 52.5185, longitude: 13.4081 } // Nearby point
  ],
  costing: 'auto',
  units: 'kilometers'
});
// → Route with distance, time, and turn-by-turn directions

⏱️ Isochrone Tool

Calculate accessible areas within time/distance limits

const result = await agent.executeTool('isochrone', {
  location: { latitude: 52.52, longitude: 13.405 }, // Berlin
  contours: [{ time: 10 }], // 10 minutes
  costing: 'pedestrian'
});
// → Geojson polygon showing accessible area

🎨 Real-World Examples

🏛️ Tourism App

// "Show me museums near the Louvre in Paris"
const museums = await agent.processNaturalLanguageQuery(
  "Find museums near the Louvre in Paris"
);

🛰️ Satellite Analysis

// "Get recent satellite images of downtown Seattle"
const imagery = await agent.processNaturalLanguageQuery(
  "Find recent satellite imagery of downtown Seattle"
);

🍕 Local Discovery

// "Find pizza places near Central Park"
const restaurants = await agent.processNaturalLanguageQuery(
  "Find pizza restaurants near Central Park in New York"
);

🌐 Browser Usage

Works seamlessly in browsers with the UMD build:

<script src="https://unpkg.com/geoai-sdk/dist/umd/geoai-sdk.umd.js"></script>
<script>
  const agent = new GeoAI.GeoAgent({
    anthropicApiKey: 'your-api-key'
  });
  
  agent.processNaturalLanguageQuery("Find coffee shops in San Francisco")
    .then(result => console.log(result.data.places));
</script>

🎮 Interactive Demo

🚀 Try It Yourself

# Start the demo server
cd examples/web
node backend.js

# Open http://localhost:3002 in your browser
# Ask questions like:
# - "Find landmarks around the Eiffel Tower"
# - "Show me interesting places in Berlin Mitte"

Features you'll see:

• 🤖 Real-time AI reasoning - Watch the agent think through each step
• 📍 Progressive geocoding - Location appears as it's found
• 🏛️ Streaming place discovery - Places appear one by one on the map
• 🎨 Smooth animations - Each step has beautiful transitions

📝 Command Line Examples

# STAC satellite imagery search
node examples/stac-search-demo.js

# Simple STAC demo
node examples/simple-stac-demo.js

# Berlin Mitte places demo
node examples/berlin-mitte-demo.js

🏗️ Architecture

graph TD
    A[Natural Language Query] --> B[GeoAgent]
    B --> C[AI Planning]
    C --> D[Tool Selection]
    D --> E[Geocoding Tool]
    D --> F[STAC Tool] 
    D --> G[Wikipedia Tool]
    D --> H[POI Search Tool]
    D --> I[Routing Tool]
    D --> J[Isochrone Tool]
    E --> K[Shared Utilities]
    F --> K
    G --> K
    H --> K
    I --> K
    J --> K
    K --> L[Structured Results]
    L --> M[JSON Response]

Loading

🔧 Development

Prerequisites

• Node.js 18+
• pnpm (recommended)

Setup

git clone https://github.com/decision-labs/geoai-sdk.git
cd geoai-sdk
pnpm install

Testing

# Unit tests (mocked) - 102 tests
pnpm test:unit

# Live integration tests (real APIs) - 60 tests
pnpm test:live

# LLM integration tests (AI agent) - 5 tests
pnpm test:live:llm

# All tests (167 total)
pnpm test:all

Building

pnpm run build    # Build all formats
pnpm run lint     # Check code quality
pnpm run format   # Format code

📚 Documentation

• 📖 API Reference - Complete API documentation
• 🚀 Getting Started - Step-by-step tutorial
• 🏗️ Architecture - Technical details
• 🎯 Examples - Use cases and patterns
• 📋 Roadmap - Future development plans
• ✅ Testing Guide - Testing strategies and best practices

🗺️ Roadmap

✅ v0.1.0 - Foundation (Current)

• Geocoding & Reverse Geocoding
• STAC Search
• Wikipedia Geosearch
• AI Agent Integration
• TypeScript Support
• Browser Compatibility

🚧 v0.2.0 - Enhanced AI (Coming Soon)

• Advanced Natural Language Processing
• Multi-step Workflow Planning
• Custom Tool Integration
• Local Model Support

🔮 v0.3.0 - Advanced GIS

• H3 Hexagonal Indexing
• S2 Spherical Geometry
• Spectral Indices (NDVI, NDWI)
• Raster Processing

🌟 v0.4.0 - Enterprise

• Geobase Integration
• Supabase Real-time Features
• Performance Optimizations
• Enterprise Support

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Test thoroughly: pnpm test:all
5. Commit with conventional commits: git commit -m "feat: add amazing feature"
6. Push to your branch: git push origin feature/amazing-feature
7. Open a Pull Request

Development Guidelines

• Follow TDD principles
• Maintain 90%+ test coverage
• Use TypeScript strict mode
• Follow conventional commits
• Update documentation

📊 Performance

Operation	Time	Notes
Geocoding	~200ms	OpenStreetMap Nominatim
STAC Search	~500ms	Element84 Earth Search
Wikipedia Search	~300ms	Wikipedia API
AI Planning	~2-5s	Anthropic Claude

🛡️ Security

• ✅ No API keys stored in code
• ✅ Environment variable configuration
• ✅ Input validation and sanitization
• ✅ Rate limiting compliance
• ✅ HTTPS-only external calls

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

GeoAI SDK is built on top of amazing open-source services and APIs. We're grateful to the following organizations and communities:

🌐 Data & API Providers

• OpenStreetMap - Global mapping data and Nominatim geocoding service
• Element84 - STAC (SpatioTemporal Asset Catalog) API for satellite imagery
• Wikipedia - Geosearch API for points of interest and landmarks
• Valhalla - Open-source routing engine (via OSM public instance)
• Overpass API - OpenStreetMap data querying service for POI search

🤖 AI & Technology

• Anthropic - Claude AI for natural language processing and tool orchestration
• Axios - HTTP client for API communications
• Universal Geocoder - Geocoding abstraction library

🛠️ Development Tools

• TypeScript - Type-safe JavaScript development
• Jest - Testing framework
• Rollup - Module bundler
• ESLint - Code linting and quality
• Prettier - Code formatting

📚 Standards & Protocols

• STAC Specification - SpatioTemporal Asset Catalog standard
• GeoJSON - Geographic data format
• OpenStreetMap - Open data licensing

---

📞 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: shoaib@decision-labs.com
• 📖 Docs: Full Documentation
• 📋 Changelog: Release History
• 🤖 Agents: AI Agent Guidelines

---

Built with ❤️ by Decision Labs

⭐ Star us on GitHub • 📦 Install from NPM • 🐦 Follow us