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

• 🗺️ 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

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

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)`);
});

// 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}`);
});

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..." }

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

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

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

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

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

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

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

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

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>

# 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

# 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

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]

• Node.js 18+
• pnpm (recommended)

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

# 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

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

• 📖 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

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

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

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

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

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

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

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

MIT License - see LICENSE file for details.

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

• 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

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

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

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

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [email protected]
• 📖 Docs: Full Documentation
• 📋 Changelog: Release History
• 🤖 Agents: AI Agent Guidelines