How to Integrate GeoLibre with Other Geospatial Tools: A Complete Developer Guide

GeoLibre integrates with external geospatial tools through a store-driven, plugin-centric architecture that supports data consumption, processing APIs, and embeddable components for seamless interoperability.

GeoLibre (opengeos/GeoLibre) is designed from the ground up to bridge the gap between desktop GIS workflows and modern web-based geospatial stacks. Whether you need to pull data from cloud platforms, embed maps in external dashboards, or offload heavy processing to Python tools, its modular architecture provides clear integration points. This guide covers the core mechanisms for connecting GeoLibre with Jupyter notebooks, GIS servers, cloud data platforms, and custom web applications.

---

Data Source Plugins: The Primary Integration Layer

GeoLibre loads geospatial data through built-in plugins that wrap common APIs and services. Registration happens in apps/geolibre-desktop/src/hooks/usePlugins.ts, with individual plugin implementations under packages/plugins/src/plugins/.

Supported Data Sources

Source	Plugin Location	Authentication
Planetary Computer	packages/plugins/src/plugins/planetary-computer.ts	OAuth 2.0
Google Earth Engine	packages/plugins/src/plugins/earth-engine.ts	OAuth 2.0
Overture Maps	packages/plugins/src/plugins/overture.ts	None required
Generic Web Services	packages/plugins/src/plugins/wms.ts, packages/plugins/src/plugins/wmts.ts	Token-based

Each plugin conforms to a standard interface defined in the core store (@geolibre/core), enabling uniform layer management regardless of data origin.

---

File and Remote Data Ingestion

Browser-Side Parsing with DuckDB-WASM

Local files (Shapefile, GeoJSON, GeoParquet, FlatGeobuf) are parsed directly in the browser using DuckDB-WASM via the ST_Read spatial extension. The fallback to shpjs handles legacy Shapefiles when needed.

Remote File Handling

Remote files pass through packages/plugins/src/plugins/remote-file-formats.ts, which enforces a size limit (MAX_REMOTE_FILE_BYTES) to prevent memory exhaustion.

// Internal pattern for remote file registration
// From: packages/plugins/src/plugins/remote-file-formats.ts

const MAX_REMOTE_FILE_BYTES = 500 * 1024 * 1024; // 500 MB default

export async function fetchRemoteLayer(url: string, options: RemoteOptions) {
  const head = await fetch(url, { method: 'HEAD' });
  const size = parseInt(head.headers.get('content-length') || '0');
  
  if (size > MAX_REMOTE_FILE_BYTES) {
    throw new Error(`Remote file exceeds size limit: ${size} bytes`);
  }
  
  // Stream to DuckDB-WASM or delegated download
  return loadToStore(url, options.format);
}

---

Python FastAPI Side-Car for Heavy Processing

CPU-intensive operations—WhiteboxTools geoprocessing, rasterio workflows, large vector operations—run in a separate Python process accessible via REST API.

Architecture

Component	Path	Purpose
Side-car server	backend/geolibre_server/	FastAPI application
API definitions	backend/geolibre_server_api/README.md	OpenAPI specification
Frontend proxy	/sidecar/* routes	CORS-handled bridge

Endpoints

• POST /sidecar/vector/upload — Ingest vector files for processing
• POST /sidecar/raster/upload — Ingest raster files
• POST /sidecar/whitebox/run — Execute WhiteboxTools algorithms
• GET /sidecar/layers/{id}/export — Retrieve processed results

Jupyter Notebook Integration

# Using the side-car from a Jupyter notebook

import requests
import json

# Upload a raster to the side-car for processing

files = {'file': open('elevation.tif', 'rb')}
resp = requests.post(
    'http://localhost:8765/sidecar/raster/upload', 
    files=files
)
layer_id = resp.json()['layerId']

# Run a Whitebox hillshade tool via the side-car

payload = {
    "layerId": layer_id, 
    "tool": "hillshade",
    "azimuth": 315,
    "altitude": 45
}
resp = requests.post(
    'http://localhost:8765/sidecar/whitebox/run', 
    json=payload
)
result = resp.json()
print("Hillshade saved to:", result['outputPath'])

The side-car enables bidirectional workflow: Python tools can push data into GeoLibre for visualization, and GeoLibre can trigger processing pipelines that return results to Python environments.

---

SQL Workspace for Query Interoperability

The SQL workspace (docs/user-guide/sql-workspace.md) exposes loaded layers through SQLite/Spatialite-compatible syntax, making GeoLibre interoperable with any tool that understands SQL-based geospatial queries.

-- Example: Querying layers from the SQL workspace
SELECT 
    name, 
    ST_Area(geometry) as area_sqm,
    population / ST_Area(geometry) * 1000000 as density
FROM 
    cities_layer
WHERE 
    ST_Within(geometry, ST_GeomFromText('POLYGON((...))')) 
    AND population > 100000;

The workspace communicates with the central store in @geolibre/core, ensuring query results reflect live layer state and trigger appropriate UI updates.

---

Embedding GeoLibre in External Applications

The @geolibre/embed package provides a drop-in iframe component for web integration.

React Component Usage

// Embedding GeoLibre in a React application
// Install: npm install @geolibre/embed

import { GeoLibreEmbed } from '@geolibre/embed';

function DashboardMap() {
  return (
    <GeoLibreEmbed
      configUrl="https://mydomain.com/geolibre-config.json"
      height="600px"
      width="100%"
      onLayerSelect={(layer) => console.log('Selected:', layer.id)}
    />
  );
}

Plain HTML Usage

<!-- Direct script embedding -->
<script src="https://unpkg.com/@geolibre/embed@latest/dist/embed.js"></script>
<div id="map-container"></div>
<script>
  GeoLibreEmbed.init({
    container: '#map-container',
    config: {
      layers: [
        { type: 'remote-geojson', url: 'https://...', name: 'Live Feed' }
      ]
    }
  });
</script>

The embedded map maintains two-way synchronization: host page events can trigger layer changes, and map interactions can broadcast selection events to the parent window.

---

Import and Export Formats

GeoLibre supports standard exchange formats for tool-to-tool data flow:

Format	Export Location	Use Case
GeoPackage	packages/processing/src/wasm-convert.ts	QGIS, ArcGIS interoperability
PMTiles	packages/processing/src/wasm-convert.ts	Web-optimized visualization
GeoJSON	packages/processing/src/wasm-convert.ts	Universal exchange, web APIs
FlatGeobuf	packages/processing/src/wasm-convert.ts	Streaming large datasets

UI handling resides in apps/geolibre-desktop/src/lib/whitebox-distance-params.ts for export parameter configuration.

---

Custom Plugin Development

External developers can extend GeoLibre without modifying core code. Plugins are distributed as ZIP archives containing:

my-plugin.zip
├── plugin.json          # Manifest with metadata, entry point

├── index.js             # Main plugin code

└── assets/              # Icons, stylesheets

The plugin.json schema is documented in docs/plugin-api.md. Plugins register data sources, processing steps, or UI panels through the same APIs used by built-in providers.

---

Common Integration Scenarios

Scenario 1: Jupyter ↔ GeoLibre Round-Trip

1. Launch GeoLibre with side-car enabled (docker compose up backend)
2. From notebook: upload raster via /sidecar/raster/upload
3. Trigger Whitebox processing, retrieve result path
4. Load result back into notebook with rasterio
5. Push new analysis output to GeoLibre for visualization

Scenario 2: Live Dashboard with Embedded Map

1. Deploy @geolibre/embed in React/Vue/Svelte dashboard
2. Configure configUrl pointing to dynamic JSON endpoint
3. Dashboard updates JSON; embedded map auto-refreshes layers
4. Map selections trigger dashboard detail panel updates via onLayerSelect callback

Scenario 3: Custom Data Feed Integration

# Add a remote GeoJSON source via CLI

npx geolibre add-layer \
  --type remote-geojson \
  --url "https://services.example.com/api/live-tracks.geojson" \
  --name "Live Vehicle Tracks" \
  --refresh-interval 30

---

Summary

• Plugin architecture (usePlugins.ts) enables cloud platform integration without core changes
• DuckDB-WASM and remote-file-formats.ts handle diverse file formats browser-side
• FastAPI side-car (backend/geolibre_server) bridges to Python geoprocessing stacks
• SQL workspace provides standards-based query interoperability
• @geolibre/embed package allows map embedding in any web application
• Standard export formats (GeoPackage, PMTiles, GeoJSON) ensure tool compatibility
• Plugin API (docs/plugin-api.md) supports third-party extensions via ZIP manifests

---

Frequently Asked Questions

How do I connect GeoLibre to Google Earth Engine?

Enable the Earth Engine plugin in the data sources panel, complete OAuth authentication, and browse the catalog directly. The plugin implementation in packages/plugins/src/plugins/earth-engine.ts handles token refresh and image collection conversion to GeoLibre layers.

Can I use GeoLibre processing from Python without the desktop app?

Yes. Run the FastAPI side-car independently (cd backend/geolibre_server && uvicorn main:app), then interact with endpoints at http://localhost:8765/sidecar/. The full API specification is in backend/geolibre_server_api/README.md.

What is the maximum file size for remote data sources?

The default limit is 500 MB (MAX_REMOTE_FILE_BYTES in remote-file-formats.ts). This prevents browser memory issues with DuckDB-WASM. For larger datasets, use the side-car upload endpoint which streams to disk.

How do I create a custom plugin for my organization's internal data API?

Create a ZIP with a plugin.json manifest pointing to your JavaScript entry file. Implement the standard plugin interface to register a data source that fetches from your API. See docs/plugin-api.md for the full specification and example implementations in packages/plugins/src/plugins/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}