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_KEY

WebSocket: 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

Message Format

Each push message includes both Field Mode and Plan Mode probabilities, plus the full space weather context:

{
  "type": "prediction",
  "conditions": {
    "solarWind": { "speed": 420, "density": 5.2 },
    "imf": { "bz": -8.5, "bt": 12.3 },
    "hemisphericPower": { "value": 42 },
    ...
  },
  "prediction": {
    "score": 72,
    "auroraProbabilityField": 0.72,
    "auroraProbabilityPlan": 0.45,
    "confidence": "Volatile",
    "worthDriving": true,
    "upcomingCmeImpacts": [...],
    "magnetotailEnergyState": { "energyRatio": 1.4, "state": "loading" },
    ...
  },
  "sqm": 21.3,
  "ts": 1719000000000
}

The prediction object contains the same full enriched prediction data as the Lumina dashboard. Key fields:

The server also sends {"type":"heartbeat","ts":...} every 30 seconds to keep the connection alive.

JavaScript Example

let retryDelay = 1000

function connect() {
  const ws = new WebSocket(
    'wss://lumina.observer/api/v1/stream?lat=65.0&lng=-147.0&x-api-key=lumina_YOUR_KEY'
  )

  ws.onopen = () => {
    retryDelay = 1000 // reset on successful connection
  }

  ws.onmessage = (event) => {
    const msg = JSON.parse(event.data)
    if (msg.type === 'prediction') {
      console.log('Field prob:', msg.prediction.auroraProbabilityField)
      console.log('Plan prob:', msg.prediction.auroraProbabilityPlan)
      console.log('Score:', msg.prediction.score)
    }
  }

  ws.onclose = () => {
    setTimeout(connect, retryDelay)
    retryDelay = Math.min(retryDelay * 2, 30000) // exponential backoff
  }
}

connect()

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