<!-- block-id: concept -->

## OpenWeather Lightning real-time data API

The **OpenWeather Lightning real-time data API** provides access to lightning strike data in real time. Our streaming service continuously collects lightning records from our data hub and broadcasts them the moment they are processed.

- **Data type:** As soon as a new strike is detected, it is pushed over a persistent WebSocket connection. Each message is delivered in JSON format.
- **Update frequency:** This is a real-time live stream
- **Historical range:** Historical lightning data are not available via WebSocket API. For accessing historical lightning data, use the **OpenWeather Lightning API** .

<!-- block-id: step -->

## Connection flow

To start receiving lightning data, follow these three steps:

1. **Connect** to the WebSocket endpoint using your API key as the `apikey` query parameter.
2. **Send** the stream-type message `all_lightnings` within 60 seconds of connecting.
3. **Receive** - you're now subscribed and will start getting live lightning records as they're detected.

To stop receiving data, simply close the connection.

<!-- block-id: subscribe -->

## Subscribe to a stream type

First, connect to the WebSocket endpoint using your API key:

`wss://<stream-host>/?apikey=YOUR_OWM_API_KEY`

Once the connection is established, send a message specifying the stream type. You must send this message within 60 seconds of connecting.

> Please note: if you do not send this message, you will receive a timeout error after 60 seconds of waiting and the connection will be closed.

Supported value:

`all_lightnings` - enables you to receive the full stream of lightning strikes as they happen in real time.

> Please note that this stream does not support any filtering: you receive every detected strike.
>
> Any other value is rejected with *"Not supported streaming type"*.

### Python example

```text
import asyncio  
import json  
import websockets  
API_KEY = "YOUR_OWM_API_KEY"  
#locally, port 8004 (docker-compose); in prod, your WSS host behind the gateway

URI = f"wss://<stream-host>/?apikey={API_KEY}"  
async def stream_lightnings():  
    async with websockets.connect(URI, ping_interval=20, ping_timeout=20) as ws:  
        # the mandatory first step is to select the stream type  
        await ws.send("all_lightnings")  
        async for raw in ws:                 # endless stream  
            rec = json.loads(raw)  
            print(rec["date"], rec["lat"], rec["lon"],  
                  rec["quality"], rec["error"])  
asyncio.run(stream_lightnings())
```

### JS example

```text
const API_KEY = "YOUR_OWM_API_KEY";

const ws = new WebSocket(`wss://<stream-host>/?apikey=${API_KEY}`);

ws.onopen = () => ws.send("all_lightnings");   // select a stream

ws.onmessage = (e) => {

const rec = JSON.parse(e.data);

console.log(rec.date, rec.lat, rec.lon, rec.quality, rec.error);

};

ws.onclose = (e) => console.log("closed", e.code, e.reason);
```

<!-- block-id: param -->

## Query Parameters

### Connection endpoint

> `wss://<stream-host>/?apikey={API_KEY}`

### Field Descriptions

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| apikey | string | OpenWeather API key |

<!-- block-id: stream -->

### Stream response

> Each message pushed is a single lightning record (LightningRecordMessage) in JSON format.

```json
{
  "id": "7829b824-880f-5354-badc-7705ab7a0395",
  "date": "07/08/2026 13:50:47",
  "lat": 50.89287,
  "lon": 35.231313,
  "quality": "good",
  "error": 5.0
}
```

<!-- block-id: descriptions -->

### JSON format API response fields

- `id`  Unique record identifier
- `date` Detection time of lightning strike (always returned in UTC, ISO-8601)
- `lon` Longitude of the location
- `lat` Latitude of the location
- `quality` Quality level of detection (good, medium, bad, undefined)
- `error` Estimated horizontal location uncertainty, km

<!-- block-id: errors -->

### Error Handling

`APIKeyValidationError` — the apikey parameter is missing or invalid.

`ExceededConnectionsLimitError` — too many concurrent connections for the key.

`Not supported streaming type` — an unsupported stream type was requested.