Documentation · Geospatial API
A Python library written to be used by agents.
The Geospatial API is a development of the Institut für holistische Technologieforschung GmbH within its research project on token-efficient geoprocessing with fault tolerance for AI agents. It is not part of the SpatialAgents but integrates with them; it was part of the benchmark test setup. This page describes it.
Purpose
One call instead of a script.
The library brings acquisition, processing and output of geodata into a single calling style. Whoever uses it describes the goal rather than the route: a vegetation index instead of band arithmetic, a slope instead of a neighbourhood window.
- Declarative
- A named call replaces the sequence of reading, computing and writing.
- Chainable
- Multi-step workflows read as one expression; intermediate results stay in memory.
- Count first
- Every download has a counting and a search call that state the volume beforehand.
- Errors with a way out
- A rejected input names the valid range and the call that fits instead.
Access
Research of the institute, deployment through GBD.
The institute researches and develops; it does not provide libraries or plugins directly. Anyone who wants to use the Geospatial API with SpatialAgents contacts Geoinformatikbüro Dassau GmbH (GBD), which provides projects, setup, training and support.
Objects
Raster, vector, time series.
Every acquisition returns one of three objects. They do not hold the data in memory but point at the files and read only on access.
| Object | Properties |
|---|---|
GeospatialRaster | Several tiles appear as one raster, even across differing reference systems and resolutions. Bands are addressed by their name rather than by a running number. |
GeospatialVector | Feature data with chained operations; the attribute table stays accessible. |
RasterCollection | A time series of rasters, with filters, aggregates and iteration along the time axis. |
Accessor pattern
The field of work as a namespace.
Processing hangs off the object, ordered by field: spectral for indices from satellite bands, terrain for derivatives of elevation models, cluster for point density. The namespace states which question is being answered.
ndvi = scene.spectral.ndvi()
slope = dem.terrain.slope()
groups = cafes.cluster.dbscan(eps=200, min_samples=3)Multi-step workflows read as one expression. The chain holds the intermediate result and releases it at the end:
vegetation_mask = (scene.pipe
.ndvi()
.focal_median(3)
.threshold(0.5)
.result)Count, search, download
Know the volume before it arrives.
Seven categories of feature data from OpenStreetMap — amenities, tourism, shops, natural features, highways, waterways and a generic point call — each have three calls: count, search, download.
number = osm.count_amenity("restaurant", place="Basel")
result = osm.search_amenity("restaurant", place="Basel")
if result.count < 1000:
data = osm.download_amenity("restaurant", place="Basel")The counting call returns a number, the search call a number plus context, the download call the data. Counting first avoids pulling down a whole city area only to find twelve features in it.
Data sources
Nine sources, two of them with a key.
All nine sources are publicly reachable and need no infrastructure of your own. An access key is required for two of them: NASA FIRMS issues it free of charge, Tavily requires one.
| Subject | Source | Key |
|---|---|---|
| Feature data | OpenStreetMap | no |
| Satellite imagery and elevation models | Microsoft Planetary Computer | no |
| Weather | Open-Meteo | no |
| Fire hotspots | NASA FIRMS | yes |
| German weather stations | Bright Sky, data of the Deutscher Wetterdienst | no |
| Soil properties | ISRIC SoilGrids | no |
| European statistics | Eurostat | no |
| Climate projections | ReKliEs-De, CORDEX, CMIP6 | no |
| Web search | Tavily | yes |
The Planetary Computer carries, among others, Sentinel-2 at 10 to 60 metres, Landsat at 30 metres, the Copernicus elevation model at 30 or 90 metres and the ESA WorldCover land cover at 10 metres. Across tile boundaries these become one raster.
Algorithms
Thirteen categories, more than a hundred methods.
The numbers come from the overview of the library, section algorithm catalogue. Where a plus sign appears, the source states a lower bound.
| Category | Methods | Examples |
|---|---|---|
| Terrain | 27 | Slope, aspect, hillshade, curvature, landforms, erosion factor |
| Hydrology | 18+ | Flow direction, catchments, stream ordering, height above drainage, infiltration |
| Climate and heat stress | 17 | Heat index, wet-bulb globe temperature, urban heat island, drought index, frost |
| Visibility | 11 | Viewshed, sky view factor, solar radiation, horizon angles, radio line of sight |
| Spectral indices | 6 | Vegetation, water, built-up land, soil-adjusted vegetation, free band arithmetic |
| Hazard indices | 6 | Flash flood, erosion, groundwater recharge, construction and agricultural suitability |
| Wildfire | 4 | Spread model, Canadian fire weather index and its components |
| Vector analysis | 14+ | Building height, landscape metrics, accessibility, facility location |
| Spatial statistics | 3 | Hotspot analysis, spatial autocorrelation, point pattern analysis |
| Interpolation | 3 | Inverse distance weighting, kriging, Voronoi tessellation |
| Networks | 4 | Centrality, isochrones, service areas, routing |
| Focal statistics | 9 | Mean, median, standard deviation, extremes, edge filters, percentile |
| Further | — | Change detection, reclassification, least-cost path, trend analysis |
Error messages
The message names the next step.
An error message that only states the failure costs a round of guessing. The messages of the library therefore name the actual state, the permitted values and the call that leads to the goal.
AttributeError: 'OSMApi' has no method 'download_cafes()'.
Hint: Use download_amenity('cafe', place=...)The second line names the call that does the job. The same holds for an extent: the check runs before the computation and states the expected order.
ValueError: BBox validation failed:
west (7.61) > east (7.57). The format is (west, south, east, north).
Did you swap min/max longitude?Where it belongs
Alongside GDAL and QGIS Processing, not in their place.
GDAL remains the route for format conversion, reprojection and tiling; QGIS Processing remains the route for the algorithms that QGIS already carries. The library sits above them, where a domain question would otherwise take ten separate steps.
- GDAL
- Formats, reference systems, mosaics. The library uses the same substrate and reads through its tile index.
- QGIS Processing
- The toolbox of QGIS, callable from the command line and readable as a list through the bridge.
- Geospatial API
- Domain questions in one call: hazard indices, terrain derivatives, accessibility, time series.
- Route of the result
- What the library writes is an ordinary file and is loaded into QGIS through the bridge.