API Reference (v1)
Lumina offers a public WebSocket API for real-time aurora visibility probabilities. Create an API key in your Settings → API Keys (requires an account) to get started.
Authentication
Pass your API key as a query parameter during the WebSocket handshake. Authentication is validated before the connection is established — invalid keys receive HTTP 401, not a WebSocket error.
wss://lumina.observer/api/v1/stream?lat=65.0&lng=-147.0&x-api-key=lumina_YOUR_KEYWebSocket: Real-Time Stream
GET /api/v1/stream
Connect via WebSocket to receive pushed probability updates minutes — no polling required. This uses the same infrastructure as the Lumina dashboard. The server pushes new data whenever new data is available (approximately once per minute).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
lat | number | Yes | Geographic latitude (-90 to 90) |
lng | number | Yes | Geographic longitude (-180 to 180) |
Message Payload
Each message is a JSON object. The primary field is prediction, which contains the enriched aurora probability data. The key probability fields are:
| Field | Type | Description |
|---|---|---|
type | string | prediction for data messages, heartbeat for keep-alive pings |
prediction.auroraProbabilityFinal | number (0–1) | Drive-horizon aurora probability at your location — the best single-number proxy for "is it worth going out?" |
prediction.intensityColourField | string | Hex colour for the field (short-horizon) probability, derived from auroraProbabilityField. Ready for CSS. |
prediction.intensityColourPlan | string | Hex colour for the plan (drive-horizon) probability, derived from auroraProbabilityFinal. Ready for CSS. |
prediction.score | number (0–100) | Geospace strength summary |
prediction.confidence | string | Stable, Volatile, or Uncertain |
prediction.worthDriving | boolean | High-level go/no-go recommendation |
conditions | object | Current solar wind, IMF, pressure, Kp, and hemispheric power readings |
sqm | number | null | Sky brightness at your location (mag/arcsec²). Higher = darker sky |
ts | number | Unix timestamp (ms) when the message was generated |
Intensity Colour Scale
Each prediction message includes two colour fields — prediction.intensityColourField (short-horizon) and prediction.intensityColourPlan (drive-horizon). Both are hex strings ready to drop into any CSS color or background property and match the colours the Lumina dashboard uses. They are derived from their respective probabilities using Oklab perceptual colour space interpolation between six named stops:
| Band | Probability | Hex | Swatch |
|---|---|---|---|
quiet | 0.00–0.15 | #7a8599 | grey-blue |
low | 0.16–0.30 | #2bb3a8 | teal |
medium | 0.31–0.50 | #6edc6e | green |
strong | 0.51–0.70 | #ffc857 | gold |
very-strong | 0.71–0.85 | #ff5fa2 | pink |
extreme | 0.86–1.00 | #b36cff | purple |
Interpolation means a probability of 0.62 produces a colour between gold and pink, not a discrete band colour.
Rate Limits
API key authentication is rate-limited. Repeated failed authentication attempts will be throttled. Once connected, the WebSocket stream has no request-based rate limit — you receive updates as they happen without any polling overhead.
Reconnection
The WebSocket may disconnect due to network issues or server restarts. Implement exponential backoff reconnection (eg. 1s → 2s → 4s → max 30s).
Error Responses
| Status | Error Code | Description |
|---|---|---|
| 400 | missing_params | lat and/or lng not provided |
| 400 | invalid_lat | Latitude out of range (-90 to 90) |
| 400 | invalid_lng | Longitude out of range (-180 to 180) |
| 401 | missing_api_key | No API key provided |
| 401 | invalid_api_key | API key is invalid |
Client Libraries & Integrations
Lumina Observer for Home Assistant — Real-time aurora metrics in Home Assistant via the WebSocket API. Installable via HACS (custom repository). Provides 14 sensors covering aurora probability (field & plan), solar wind, IMF Bz/Bt, hemispheric power, sky quality, magnetotail energy state, incoming CME count, and a binary_sensor.lumina_observer_worth_driving go/no-go recommendation for automations.
Configuration: enter your coordinates and API key in the Home Assistant integration setup. The addon maintains a persistent WebSocket connection with automatic reconnection and heartbeat monitoring.