Actinia Grass GIS Getting Started: API Access & First Request (2026)

Getting started overview

Actinia Grass GIS provides a RESTful API that allows developers to execute GRASS GIS and GDAL functions remotely, enabling server-side geospatial processing. This guide focuses on the initial steps required to access the Actinia API, obtain necessary credentials, and make a successful first API call. The process involves contacting Mundialis for API access, receiving authentication details, and then formulating a request to execute a GRASS GIS module.

Actinia is designed for developers who need to integrate powerful geospatial analysis capabilities into their applications without managing the underlying GRASS GIS environment directly. It supports complex geodata analysis and is suitable for cloud-native geospatial application development.

Here's a quick reference for getting started with Actinia Grass GIS:

Create an account and get keys

To begin using Actinia Grass GIS, direct API access is required, which is managed through Mundialis, the primary provider of the hosted Actinia service. Unlike many public APIs with self-service signup, Actinia operates on a custom enterprise pricing model without an explicit free tier for the hosted service. Therefore, obtaining an account and API keys involves a direct engagement process.

1. Contact Mundialis: Navigate to the Actinia homepage and locate the contact information. You will need to reach out to Mundialis directly to discuss your specific use case and request API access. This initial contact is crucial for understanding the service's capabilities in relation to your needs and for initiating the account setup process.

2. Discuss Pricing and Service Level: During your communication with Mundialis, you will discuss the custom enterprise pricing model. This step often involves defining the scope of your usage, expected processing load, and specific GRASS GIS functionalities you intend to utilize. Mundialis will provide details on the available service levels and associated costs.

3. Receive API Credentials: Upon agreement and account setup, Mundialis will provide you with the necessary API credentials. These typically include an API key, which is used to authenticate your requests to the Actinia API. The method of delivery (e.g., email, secure portal) will be communicated by Mundialis.

4. Secure Your Keys: Once you receive your API key, it is critical to store it securely and prevent unauthorized access. Best practices for API key management include using environment variables, dedicated secrets management services, or secure configuration files, rather than hardcoding them directly into your application code. For general security principles regarding API keys, refer to Google Cloud's API key security guidelines.

The Actinia API reference provides detailed information on how to use these credentials in your API requests once obtained. It is recommended to review the Actinia API documentation thoroughly after receiving your keys to understand the authentication mechanisms and endpoint structures.

Your first request

After obtaining your API key, you can make your first request to the Actinia API. A common initial step is to query the server status or list available GRASS GIS modules to confirm connectivity and authentication. This example uses curl, a command-line tool for making HTTP requests, but you can adapt it to any HTTP client library in your chosen programming language.

The Actinia API endpoint for server status is typically /actinia_modules, which can list available modules and their descriptions. For this example, replace YOUR_API_KEY with the actual API key provided by Mundialis.

Example: Listing available GRASS GIS modules

This request fetches a list of all GRASS GIS modules available through the Actinia API. It's a good way to verify your API key and connectivity.

curl -X GET \
  "https://actinia.mundialis.de/api/v1/actinia_modules" \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Explanation:

• -X GET: Specifies the HTTP GET method.
• "https://actinia.mundialis.de/api/v1/actinia_modules": The target URL for the Actinia API endpoint that lists modules.
• -H "accept: application/json": Requests the response in JSON format.
• -H "Authorization: Bearer YOUR_API_KEY": Provides your API key for authentication. The Actinia API typically uses a Bearer token scheme for authentication, where YOUR_API_KEY is the token.

Expected Response

A successful response will return a JSON array containing objects, each representing a GRASS GIS module. The structure will be similar to this (truncated for brevity):

[
  {
    "id": "r.mapcalc",
    "name": "r.mapcalc",
    "description": "Raster map calculator. Allows complex map calculations.",
    "keywords": [
      "raster",
      "mapcalc",
      "calculator"
    ],
    "parameters": [
      {
        "name": "expression",
        "description": "Map calculation expression",
        "type": "string",
        "required": true
      },
      // ... more parameters
    ]
  },
  {
    "id": "v.buffer",
    "name": "v.buffer",
    "description": "Creates a buffer around vector features.",
    "keywords": [
      "vector",
      "buffer",
      "analysis"
    ],
    "parameters": [
      {
        "name": "input",
        "description": "Name of input vector map",
        "type": "string",
        "required": true
      },
      // ... more parameters
    ]
  }
  // ... more modules
]

This response confirms that your API key is valid, your request was authenticated, and the Actinia service is accessible and returning data. You can then proceed to execute specific GRASS GIS modules with appropriate input parameters as detailed in the Actinia API documentation.

Common next steps

After successfully making your first request to the Actinia API, consider these common next steps to deepen your integration and leverage Actinia's full capabilities:

1. Explore Specific GRASS GIS Modules: Review the comprehensive Actinia API documentation to identify the GRASS GIS and GDAL modules most relevant to your geospatial processing needs. The documentation details each module's parameters, expected input formats, and output structures. You can use the /actinia_modules/{module_id} endpoint to get specific details about a module.

2. Upload Data for Processing: For many GRASS GIS operations, you will need to upload geospatial data (e.g., raster files, vector shapefiles) to the Actinia server. Actinia provides endpoints for data management, allowing you to upload, list, and manage your datasets before processing. Understand the supported data formats and the process for data ingestion.

3. Execute Processing Chains: Actinia supports the creation and execution of complex processing chains, where the output of one GRASS GIS module serves as the input for another. This capability is essential for multi-step geospatial workflows. Learn how to define and execute these chains using the API.

4. Handle Asynchronous Operations: Many complex geospatial processing tasks are time-consuming and are executed asynchronously. Actinia provides mechanisms to submit a processing job, monitor its status, and retrieve the results once completed. Familiarize yourself with job management endpoints and polling strategies.

5. Integrate with a Programming Language: While curl is useful for testing, integrate Actinia into your application using an HTTP client library in your preferred programming language (e.g., Python's requests, Node.js axios, Java HttpClient). This allows for programmatic control over API requests, error handling, and data parsing.

6. Error Handling and Logging: Implement robust error handling in your application to manage potential API errors, such as invalid parameters, authentication failures, or processing job failures. Actinia's API responses typically include informative error messages. Effective logging of API requests and responses can aid in debugging and monitoring.

7. Optimize Performance: For high-volume or performance-critical applications, consider strategies such as batch processing, efficient data transfer, and optimizing your GRASS GIS module parameters to minimize execution time and resource consumption on the Actinia server.

Troubleshooting the first call

When making your first API call to Actinia Grass GIS, you might encounter issues. Here are common problems and their potential solutions:

• 401 Unauthorized:

  • Problem: This usually means your API key is missing, incorrect, or expired.
  • Solution: Double-check that you included the Authorization: Bearer YOUR_API_KEY header correctly in your request. Ensure there are no typos in the key. If the key was recently provided, confirm its validity period with Mundialis.

• 403 Forbidden:

  • Problem: Your API key might be valid but lacks the necessary permissions for the requested operation or endpoint.
  • Solution: Review your account's permissions with Mundialis. Some endpoints might require specific access levels. Ensure you are trying to access a publicly available endpoint or one you have been granted access to.

• 404 Not Found:

  • Problem: The requested API endpoint does not exist or the URL is incorrect.
  • Solution: Verify the URL against the Actinia API reference. Pay close attention to the version number (e.g., /v1/) and the exact path of the endpoint (e.g., /actinia_modules vs. /actinia_modules/).

• 5xx Server Error:

  • Problem: These indicate an issue on the Actinia server side.
  • Solution: These errors are typically not within your control. Wait a few minutes and try the request again. If the issue persists, check the Actinia service status page (if available) or contact Mundialis support with the exact timestamp and details of your request.

• CORS (Cross-Origin Resource Sharing) Issues:

  • Problem: If you are making requests from a web browser (e.g., via JavaScript), you might encounter CORS errors preventing the browser from accessing the API response.
  • Solution: Actinia is primarily designed for server-side integration. If direct browser-based calls are necessary, you might need to configure a proxy on your server or discuss CORS requirements with Mundialis to ensure your origin is whitelisted. For more information on CORS, consult MDN Web Docs on CORS.

• Incorrect Request Body/Parameters:

  • Problem: If you are executing a GRASS GIS module, incorrect or missing parameters in the request body can lead to processing failures.
  • Solution: Refer to the Actinia API documentation for the specific module you are trying to run. Ensure all required parameters are present and correctly formatted according to their data types (e.g., string, integer, boolean, JSON object).

When troubleshooting, always check the full API response, including status codes and any error messages in the response body, as they provide critical clues for diagnosis.