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"
}

info

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"
  ]
}

Supported Providers

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

info

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
}

Client Ping (Optional but Recommended)

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