Skip to main content

Real-Time Strikes (WebSocket)

WebSocket URL​

wss://api.lightning.metservice.com/strikes/realtime

Connection & Authentication Flow​

Recommended sequence using short-lived token:

  1. Establish WebSocket connection
  2. Authenticate using token
  3. Wait for server confirmation
  4. Set preferences
  5. Receive real-time strike events

Connection Messages​

Authenticate Payload​

{
  "type": "AUTHENTICATE",
  "token": "YOUR_SHORT_LIVED_TOKEN"
}

ℹ️ Note

Authentication can be performed using either:

  • a short-lived token generated via /auth/token (recommended), or
  • the API key directly (in this case, the apiKey field is accepted instead of token).

Server response

{
  "type": "AUTHENTICATED"
  "message": "Successfully authenticated",
  "ts": 1769487828946
}

Once the WebSocket connection is established, the client has 10 seconds to send a valid AUTHENTICATE message. If authentication is not completed within this window, the server will automatically close the connection.

Set Preferences​

After successful authentication, the client must define its data preferences, including the bounding box and selected providers. Without this configuration, the server will not send any real-time strike events.

Payload

{
  "type": "SET_PREFERENCES",
  "bbox": [155, -55, 190, -25],
  "providers": [
    "transpower",
    "simulation"
  ]
}

Provider Notes​

  • transpower → Live New Zealand lightning data
  • toa → Global lightning data
  • simulation → Generates random strikes every second within the bounding box (useful for testing)

ℹ️ Note

At any point during an active WebSocket session, the client can send a new SET_PREFERENCES message to modify the requested bounding box or selected providers. The updated preferences are applied immediately, without requiring the connection to be re-established.

Events​

New Strike Events​

After authentication and preference configuration, the server continuously monitors lightning activity and emits a NEW_STRIKES event in real time whenever new strikes occur within the client’s configured bounding box and providers.

Server Response

{
  "type": "NEW_STRIKES",
  "ts": 1768442096640,
  "data": {
    "total": 1,
    "strikes": [
      {
        "id": "160a620a-1f0f-474e-9a21-818757d95e42",
        "strikeType": "GROUND",
        "latitude": -38.3343109,
        "longitude": 150.412377,
        "unixEpochSeconds": 1768442092,
        "kA": -30.1
      }
    ]
  }
}

---

## Connection Health & Reliability

### Server Keep-Alive
The server periodically sends heartbeat messages **every 20 seconds** to ensure connectivity. No action is required on your side.

```json
{
  "type": "KEEP_ALIVE",
  "data": {
    "ts": 1769485835778
  },
  "message": "Server heartbeat",
  "ts": 1769485835778
}

To help maintain a stable and healthy WebSocket connection, clients may periodically send PING messages to the server.

Although the WebSocket protocol already includes a native ping/pong mechanism implemented by our server, application-level heartbeat messages can be useful to:

  • Detect silent disconnections caused by intermediate components (firewalls, proxies, load balancers, etc…)
  • Prevent idle connections from being closed by network infrastructure
  • Monitor connection health at the application level
  • Reduce the risk of delayed data delivery due to stale connections
{
  "type": "PING"
}

Server response

{
  "type": "PONG",
  "ts": 1769487832151
}

We recommend sending a PING message every 25 seconds.

Reconnection Strategy​

While we take all necessary measures to ensure stable service availability, continuous connectivity cannot be guaranteed due to external factors (network issues, firewalls, load balancers, etc.).

Clients should therefore:

  • Detect connection drops
  • Automatically re-establish the WebSocket connection
  • Re-authenticate and re-apply preferences after reconnection