Actinia — The GRASS GIS REST API

Software Article

Project Overview

Actinia is an open-source REST API for scalable, distributed, high-performance processing of geographical data that mainly uses GRASS GIS for computational tasks.

Key Features:

• REST API for processing satellite images, raster and vector data, including time-series.
• Access and manipulate GRASS GIS database via HTTP GET, PUT, POST, and DELETE requests.
• Process cloud-based data, including Landsat 4-9 and Sentinel-2 scenes.
• Output raster data results as GeoTIFF files as resources or in object storage.
• Output vector data results as GeoPackage files as resources or in object storage.

Links:

• Software DOI
• Article DOI
• API Documentation
• Discussion forum
• Tutorial
• Docker

Prerequisites

To use actinia, ensure you have the following installed:

• Alpine Linux: apk add python3 py3-pip
• Ubuntu: apt install -y python3 python3-pip

Additional system packages required for Alpine:

apk add python3-dev gcc musl-dev linux-headers build-base gdal gdal-tools gdal-dev proj proj-util proj-dev geos-dev py3-numpy-dev

Installation Steps

Option 1: Manual Installation

Install actinia from PyPI:

pip install actinia-core

Option 2: Using Docker

Pull the Docker image:

docker pull mundialis/actinia-core

For custom deployments or local setups, refer to the docker/ subfolder.

Verification

To verify a successful installation, check API accessibility via the provided endpoints or the swagger.json.

API Documentation

The full API documentation is available under actinia API documentation.

Examples

Data management

• List all projects that are available in the actinia persistent database:

curl -u 'demouser:gu3st!pa55w0rd' -X GET "https://actinia.mundialis.de/api/v3/projects"

• List all mapsets in the project latlong_wgs84:

curl -u 'demouser:gu3st!pa55w0rd' -X GET "https://actinia.mundialis.de/api/v3/projects/latlong_wgs84/mapsets"

• List all space-time raster datasets (STRDS) in project latlong_wgs84 and mapset Sentinel_timeseries:

curl -u 'demouser:gu3st!pa55w0rd' -X GET "https://actinia.mundialis.de/api/v3/projects/latlong_wgs84/mapsets/modis_ndvi_global/strds"

• List all raster map layers of the STRDS:

curl -u 'demouser:gu3st!pa55w0rd' -X GET "https://actinia.mundialis.de/api/v3/projects/latlong_wgs84/mapsets/modis_ndvi_global/strds/ndvi_16_5600m/raster_layers"

Landsat and Sentinel-2 NDVI computation

• Compute NDVI for a specific Landsat scene:

curl -u 'demouser:gu3st!pa55w0rd' -X POST "https://actinia.mundialis.de/api/v3/landsat_process/<scene_id>/TOAR/NDVI"

• Compute NDVI for a specific Sentinel-2A scene:

curl -u 'demouser:gu3st!pa55w0rd' -X POST "https://actinia.mundialis.de/api/v3/sentinel2_process/ndvi/<scene_id>"

The results of the asynchronous computations are available as GeoTIFF file in a cloud storage for download.

List of available endpoints

To see a simple list of endpoints (and more), consult the "paths" section in the API JSON.

To list the available endpoints on command line, run

# sudo npm install -g json
curl -u 'demouser:gu3st!pa55w0rd' -X GET https://actinia.mundialis.de/api/v3/swagger.json | json paths | json -ka

Development

Pre-Commit Hooks

Install pre-commit for automated code checks and formatting before submitting any new or modified code. Pre-commit installs all necessary tools in a virtual environment upon first use:

pip install pre-commit

# activate pre-commit in the code repository
cd <actinia-core_source_dir>
pre-commit install

Pre-commit will then be automatically triggered by the git commit command. If it finds any problem it will abort the commit and try to solve it automatically. In that case review the changes and run again git add and git commit.

It is also possible to run pre-commit manually, e.g:

pre-commit run flake8 --all-files
pre-commit run black --all-files
# pre-commit run yamllint --all-files
# pre-commit run markdownlint --all-files

The pre-commit hook set is defined in .pre-commit-config.yaml.

External Documents

• actinia is also available on OSGeoLive

Contributors

Thanks to all contributors ❤