@openverb/gis

The open-source semantic action layer for AI-powered GIS applications.

OpenVerb GIS is a standardized, platform-independent collection of geospatial verbs, JSON schemas, and types designed to bridge AI agents to geospatial engines. Built on top of the OpenVerb standard, it establishes a common vocabulary for GIS operations.

Table of Contents

• Introduction
• Why a Universal GIS Action Layer?
• Architecture
• Installation
• Core API Usage
  • Loading the Library
  • Action Validation
• Platform Integration Guide
  • Mapbox Integration Example
  • PyQGIS / QGIS Integration Example
• Supported GIS Verbs
• Extending the Library
• Example AI Copilot Workflows
• License

Introduction

AI models excel at planning and communicating in terms of verbs (e.g., "buffer", "clip", "geocode"). Rather than custom-wiring ad-hoc tool interfaces for every GIS platform, OpenVerb GIS defines a deterministic execution contract.

This package does not perform GIS computations itself. Instead, it provides the standard definitions, schemas, and types. Platform-specific adapters (such as QGIS plugins, ArcGIS Pro extensions, or Mapbox frontends) implement these definitions as executors.

Why a Universal GIS Action Layer?

Traditionally, integrating AI agents with spatial platforms meant writing custom code for:

• Desktop GIS: PyQGIS for QGIS, ArcPy for ArcGIS Pro.
• Web GIS: Mapbox GL JS, Leaflet, OpenLayers, MapLibre.
• Database GIS: PostGIS SQL queries.

This fragmentation causes AI agents to be tightly coupled to specific execution environments. OpenVerb GIS acts as a universal abstraction layer:

                 AI Assistant
                      |
                      v
              OpenVerb GIS Package
          (standard GIS verbs + schemas)
                      |
        ---------------------------------
        |               |               |
       QGIS          ArcGIS          Mapbox
    Executor       Executor        Executor
        |               |               |
     PyQGIS          ArcPy          APIs

If the AI decides to buffer a layer by 100 feet, it outputs a standard buffer_geometry action. How that buffer is executed depends on whether the host application is running PyQGIS, ArcPy, Turf.js, or PostGIS.

Installation

npm install @openverb/gis

(Note: Requires openverb core library as a peer dependency).

Core API Usage

Loading the Library

To use the standard GIS action definitions in your application:

import { gisLibrary, verbs } from '@openverb/gis';

console.log(`Loaded library: ${gisLibrary.namespace} v${gisLibrary.version}`);
console.log(`Available GIS Verbs: ${verbs.map(v => v.name).join(', ')}`);

Action Validation

Verify that an incoming AI action conforms to standard GIS parameter and type requirements:

import { validateGISAction } from '@openverb/gis';

const incomingAction = {
  verb: 'buffer_geometry',
  params: {
    geometry: { type: 'Point', coordinates: [-74.006, 40.7128] },
    distance: 150,
    units: 'meters'
  }
};

const result = validateGISAction(incomingAction);
if (result.valid) {
  console.log('Action is valid!');
} else {
  console.error(`Invalid action: ${result.error}`);
}

Live Demo

Want to see OpenVerb GIS in action? Check out the OpenVerb GIS Demo App!

It is a live web application that uses Leaflet, Turf.js, and OpenAI to let you control a map using natural language via OpenVerb GIS.

Platform Integration Guide

Developers implement platform-specific executors by registering handlers for standard GIS verbs.

Mapbox Integration Example

In a web application using Mapbox GL JS and Turf.js:

import { createExecutor } from 'openverb';
import { gisLibrary } from '@openverb/gis';
import * as turf from '@turf/turf';

const executor = createExecutor(gisLibrary);

// Implement the buffer_geometry verb using Turf.js
executor.register('buffer_geometry', (params) => {
  const { geometry, distance, units } = params;
  
  // Map standard OpenVerb GIS units to Turf units
  const turfUnits = units === 'feet' ? 'feet' : units === 'meters' ? 'meters' : 'degrees';
  
  const buffered = turf.buffer(geometry, distance, { units: turfUnits });
  
  return {
    verb: 'buffer_geometry',
    status: 'success',
    data: {
      geometry: buffered
    }
  };
});

PyQGIS / QGIS Integration Example

In a QGIS Python plugin (mapping the JS types to Python):

from openverb import create_executor, load_library
from qgis.core import QgsGeometry, QgsUnitTypes

# Load the GIS library schema
library = load_library('path/to/openverb.gis.json')
executor = create_executor(library)

def handle_buffer(params):
    geom_json = params['geometry']
    distance = params['distance']
    units = params['units']
    
    # Instantiate QGIS Geometry
    geom = QgsGeometry.fromGeoJson(json.dumps(geom_json))
    
    # Calculate buffer planar/geodesic in QGIS
    buffered_geom = geom.buffer(distance, 8)
    
    return {
        "verb": "buffer_geometry",
        "status": "success",
        "data": {
            "geometry": json.loads(buffered_geom.asJson())
        }
    }

executor.register('buffer_geometry', handle_buffer)

Supported GIS Verbs

Standard GIS verbs are divided into logical categories:

1. Layer Operations (layer_operations)

• create_layer: Initialize a new vector (point, line, polygon) or raster layer.
• delete_layer: Remove a layer from the workspace.
• rename_layer: Rename an active layer.
• load_layer: Import external files (Shapefile, GeoPackage, WMS, GeoJSON) into the workspace.
• save_layer: Export active layers to standard formats (GPKG, SHP, GeoJSON, KML, CSV).
• list_layers: Retrieve a list of active layers in the workspace.
• get_layer_metadata: Get schema details, CRS projection, extent bounding box, and counts.

2. Feature Operations (feature_operations)

• create_feature: Add a new geometry feature with attribute columns.
• update_feature: Modify geometries or attribute properties on an existing feature.
• delete_feature: Remove features from a layer.
• query_features: SQL-like attribute queries combined with spatial boundaries.
• select_features: Select features interactively in the map viewport.
• filter_features: Mask layers to hide non-matching features.

3. Geometry Operations (geometry_operations)

• buffer_geometry: Compute buffers around geometries.
• clip_geometry: Clip geometries using intersecting boundaries.
• intersect_geometry: Compute overlapping areas of geometries.
• union_geometry: Combine multiple geometries into a single representation.
• difference_geometry: Subtract one geometry shape from another.
• simplify_geometry: Reduce complexity of vertices.
• calculate_area: Planar/geodesic calculation of polygons.
• calculate_length: Planar/geodesic calculation of perimeters or lines.
• calculate_centroid: Find geometric center.

4. Spatial Analysis (spatial_analysis)

• spatial_join: Merge layer attribute columns based on geometric intersections.
• nearest_feature: Identify the closest features from target layers.
• point_in_polygon: Determine if coordinate pairs reside in polygon boundaries.
• distance_analysis: Planar/geodesic shortest distances.
• network_analysis: Shortest/fastest path computations on linear network datasets.

5. Coordinate Reference Systems (coordinate_systems)

• transform_coordinates: Project coordinate arrays between different projections.
• reproject_layer: Reproject entire layers to target CRS systems.
• identify_crs: Fetch CRS metadata details from EPSG codes.
• convert_geometry: Convert individual geometries between CRS projections.

6. Raster Operations (raster_operations)

• load_raster: Import grid raster files.
• analyze_raster: Execute raster band calculations (e.g. NDVI).
• classify_raster: Map value thresholds to classes.
• clip_raster: Clip grid cells to vector polygons.
• export_raster: Output rasters to file formats (e.g. GeoTIFF).

7. Mapping & Layouts (mapping_visualization)

• create_map: Set up layout canvases.
• add_layer_to_map: Apply layers to maps.
• style_layer: Style points, lines, polygons, and rasters.
• create_layout: Layout maps with headers, scalebars, legends, and north arrows.
• export_map: Export mapping canvases to image (PNG, JPG) or document formats (PDF).

8. Geocoding (geocoding)

• geocode_address: Forward geocoding of textual descriptions to coordinates.
• reverse_geocode: Lookup physical address structures from coordinate parameters.
• search_places: Natural search of towns, points-of-interest, or landmarks.

Extending the Library

OpenVerb is designed to be extensible. If you need custom GIS workflows specific to your project, simply merge custom verbs into the registry:

import { gisLibrary } from '@openverb/gis';
import { loadLibrary } from 'openverb';

const myCustomGISLibrary = loadLibrary({
  ...gisLibrary,
  verbs: [
    ...gisLibrary.verbs,
    {
      name: 'calculate_solar_exposure',
      category: 'spatial_analysis',
      description: 'Calculate average daily solar radiation on a building roof geometry.',
      params: {
        roof_geometry: { type: 'object', description: 'Roof boundary polygon.', required: true },
        elevation_raster: { type: 'string', description: 'DEM raster layer name.', required: true }
      },
      returns: {
        avg_kwh_per_sq_meter: { type: 'number', description: 'Radiation index.' }
      }
    }
  ]
});

Example AI Copilot Workflows

Scenario 1: Natural Language Spatial Analysis

• User Query: "Find all commercial parcels within 500 meters of the new subway station, and save them as a GeoJSON file."
• AI Plan Generation:

[
  {
    "verb": "geocode_address",
    "params": {
      "address": "New Subway Station, NYC"
    }
  },
  {
    "verb": "buffer_geometry",
    "params": {
      "geometry": { "type": "Point", "coordinates": [-73.985, 40.748] },
      "distance": 500,
      "units": "meters"
    }
  },
  {
    "verb": "query_features",
    "params": {
      "layer": "nyc_parcels",
      "expression": "\"zoning\" = 'Commercial'",
      "spatial_filter": { "type": "Polygon", "coordinates": [...] }
    }
  },
  {
    "verb": "save_layer",
    "params": {
      "layer": "queried_features_result",
      "path": "./commercial_parcels_near_subway.geojson",
      "format": "geojson"
    }
  }
]

Scenario 2: Automated Cartographic Export

• User Query: "Generate a PDF map layout of the wetlands layer styled in blue, with a scale bar, legend, and name it 'Wetlands Preservation Area'."
• AI Plan Generation:

[
  {
    "verb": "style_layer",
    "params": {
      "layer": "wetlands",
      "style": { "fill_color": "#0000FF", "opacity": 0.6 }
    }
  },
  {
    "verb": "create_layout",
    "params": {
      "title": "Wetlands Preservation Area",
      "layers": ["wetlands", "roads_basemap"],
      "layout_template": "standard_a4"
    }
  },
  {
    "verb": "export_map",
    "params": {
      "map_or_layout": "layout_wetlands_preservation",
      "path": "./wetlands_map.pdf",
      "format": "pdf"
    }
  }
]

License

MIT © Roman Hancel