GeoAI

A lightweight JavaScript library for running Geo AI models in frontend applications.

Caption: example of feature extraction using the transformerjs version of dino v3, see examples at docs.geobase.app/geoai-live

Quick install

NPM Package

npm i geoai

📦 Package Links:

• npm package
• jsDelivr CDN

CDN (Browser)

You can also use GeoAI directly in the browser via CDN:

Unpkg CDN

<script src="https://unpkg.com/geoai@1.0.3/geoai.js"></script>

jsDelivr CDN

<script src="https://cdn.jsdelivr.net/npm/geoai@1.0.3/geoai.min.js"></script>

When using CDN, the library is available globally as geoai.

Get Started: Follow the Quickstart Guide or clone the quick start example.

git init
touch README.md
git add .
git commit -m "Initial commit"
git subtree add --prefix=examples/01-quickstart https://github.com/decision-labs/geoai.js main --squash

Usage

Core Library (Node.js and Browser)

NPM Installation

import { geoai } from "geoai";

// Initialize the pipeline with ESRI provider (no API key required)
const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
  provider: "esri",
});

// Run inference
const result = await pipeline.inference({
  inputs: {
    polygon: geoJsonFeature,
  },
  mapSourceParams: {
    zoomLevel: 18,
  },
});

CDN Usage

// When using CDN, geoai is available globally
const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
  provider: "esri",
});

const result = await pipeline.inference({
  inputs: {
    polygon: geoJsonFeature,
  },
  mapSourceParams: {
    zoomLevel: 18,
  },
});

React Hooks

import { useGeoAIWorker } from "geoai/react";

function MyComponent() {
  const { inference, isLoading, error } = useGeoAIWorker({
    tasks: ["object-detection"],
    provider: "esri", // No API key required for ESRI
  });

  const handleInference = async () => {
    const result = await inference({
      inputs: { polygon: geoJsonFeature },
      mapSourceParams: { zoomLevel: 18 },
    });
  };

  return (
    <div>
      <button onClick={handleInference} disabled={isLoading}>
        {isLoading ? "Processing..." : "Run Detection"}
      </button>
      {error && <div>Error: {error.message}</div>}
    </div>
  );
}

Features

• Multiple AI Tasks: Object detection, segmentation, classification, and more
• Map Provider Support: Geobase, Mapbox, ESRI, TMS, and Google Maps
• React Integration: Hooks for easy React integration
• TypeScript Support: Full TypeScript definitions
• Web Worker Support: Run AI models in background threads
• Optimized Performance: Efficient model loading and inference
• CDN Ready: Available via npm and popular CDNs (unpkg, jsDelivr)

Supported Tasks

• Object Detection
• Building Detection
• Car Detection
• Ship Detection
• Solar Panel Detection
• Oil Storage Tank Detection
• Land Cover Classification
• Wetland Segmentation
• Building Footprint Segmentation
• Mask Generation
• Zero-shot Object Detection
• Zero-shot Segmentation
• Image Feature Extraction

For more see the supported tasks

Map Providers

GeoAI.js supports multiple map tile providers:

TMS (Tile Map Service)

TMS is a tile-based map specification that uses a bottom-left origin coordinate system. Perfect for custom tile servers and OpenAerialMap.

// Option 1: Using URL template with placeholders (recommended)
const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
  provider: "tms",
  baseUrl: "https://tile.example.com/tiles/{z}/{x}/{y}.png",
  apiKey: "your-api-key", // optional
  tileSize: 256, // optional, defaults to 256
  attribution: "Custom TMS Provider", // optional
});

// Option 2: Using base URL (legacy format, still supported)
const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
  provider: "tms",
  baseUrl: "https://tile.example.com/tiles",
  extension: "png", // optional, defaults to "png"
  apiKey: "your-api-key", // optional
  tileSize: 256, // optional, defaults to 256
  attribution: "Custom TMS Provider", // optional
});

ESRI

ESRI World Imagery - no API key required.

const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
  provider: "esri",
});

Mapbox

Requires a Mapbox API key.

const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
  provider: "mapbox",
  apiKey: "your-mapbox-api-key",
  style: "mapbox://styles/mapbox/satellite-v9",
});

Geobase

Requires Geobase project credentials.

const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
  provider: "geobase",
  projectRef: "your-project-ref",
  apikey: "your-api-key",
  cogImagery: "https://path-to-your-cog.tif",
});

Links

• Documentation: docs.geobase.app/geoai - Comprehensive documentation, examples, and API reference
• Live Examples: docs.geobase.app/geoai-live - Interactive examples and demos
• Community: GitHub Discussions - Ask questions, share ideas, and connect with other developers
• Code: GitHub Repository - Source code and contributions
• Issues: GitHub Issues - Report bugs and request features

Contributing

We welcome contributions! Please see our contributing guide for details.

License

MIT License - see LICENSE.md for details.