LANiS (Schulportal Hessen) API

Unofficial Python client and REST API integrations for Schulportal Hessen (SPH). The PyPI package contains the reusable Python client; the repository also includes the optional hosted API server and a terminal UI.

The client is actively developed against the portal's web interfaces. Portal changes can occasionally require a new package release.

Live Server

The hosted API is available at lanis-backend.joancode.dev, with interactive documentation at /documentation.

Components

This monorepo contains the following components:

1. sph_client / schulportal_hessen contains the reusable Python client
2. api wraps the client in a REST API with caching and additional services
3. TUI contains a terminal interface that is currently not actively maintained

Supported Modules:

The portal modules are referred to as applets because SPH is built on top of Moodle.

• login — authenticate and manage session credentials
• benutzer — user profile and class information
• mein_unterricht — courses, content, assignments, and attachments
• kalender — calendar events
• nachrichten — conversations, recipients, sending, and replies
• stundenplan — timetable data
• lerngruppen — study groups
• school_list — school names and IDs for login and school selection

Installation

API Server

# Install from source
git clone https://github.com/joan-code6/lanis_api.git
pip install -r requirements.txt

Python package

python -m pip install sph-client

Quick Start

API Server

uvicorn api.api:app

The API is available at port 8000 with interactive docs at /docs.

Python package

from sph_client import SchulportalHessenAPI

api = SchulportalHessenAPI()

# Login
result = api.login("1234", "username", "password")
if result.get("success"):
    # Get available modules
    modules = api.get_available_modules()
    print(modules)

    # Fetch messages
    headers = api.nachrichten_get_headers()
    print(headers)

    # Get calendar events
    events = api.kalender_get_events()
    print(events)

    api.logout()

Caching and sessions

The hosted API uses caching and persistent sessions to reduce portal requests and keep navigation responsive.

• Session TTL: 1 hour inactivity timeout per session
• Response cache: 10 minutes for most endpoints
• Long cache (30 days): /modules, /apps, /benutzer
• School list cache: 2 days with 3-day auto-refresh
• File cache: SHA-256 hashed, stored in data/files/
• Background revalidation: stale entries are refreshed asynchronously

Message push notifications

Authenticated users can opt in to daytime message polling from the Lanis UI settings. The default polling window is 07:00–21:00 in the user's configured timezone, with a 15-minute interval. The first poll creates a baseline so enabling the feature does not send old messages as notifications.

Web Push requires these environment variables on the API server:

• VAPID_PUBLIC_KEY
• VAPID_PRIVATE_KEY
• VAPID_SUBJECT (for example, mailto:admin@example.org)

The pywebpush dependency is included in requirements.txt. Users can configure the active window, interval, timezone, and whether notification previews contain the sender and subject in Settings → Nachrichten-Benachrichtigungen.

Deployment

A systemd service file is provided at lanis-api.service:

# Deploy using the provided script
./deploy.sh

API reference

See the generated Python API reference for the complete client surface and method documentation.

License

This project is released under the MIT License.