distributor/md/DOCS.md

IEM Alerter WebSocket API Documentation

WebSocket Endpoint: /iem

This WebSocket endpoint allows clients to subscribe to weather-related channels, receive real-time updates, and manage their subscriptions.

Legal Disclaimer

This system is not intended to be used for, or as a supplement for information regarding life or death situations. For critical weather-related information, please rely on official sources such as National Weather Service radio stations, local radio or news outlets, and local emergency management agencies.

Connection

Upon connecting to the /iem WebSocket endpoint, the server will send a connection-info message containing the following details:

{
  "type": "connection-info",
  "state": true,
  "uuid": "<unique-identifier>",
  "host": "<server-hostname>"
}

Supported Message Types

1. Subscribe to a Channel

Clients can subscribe to a specific channel or all channels.

Request:

{
  "type": "subscribe",
  "channel": "<channel-name>" // Optional, subscribe to all channels if omitted
}

Response:

• Success:

{
  "type": "internal-response",
  "code": 200,
  "data": {
    "message": "Subscribed to <channel-name>"
  }
}

• Failure (Invalid Channel):

{
  "type": "internal-response",
  "code": 404,
  "data": {
    "error": "Invalid channel."
  }
}

2. Unsubscribe from a Channel

Clients can unsubscribe from a specific channel or all channels.

Request:

{
  "type": "unsubscribe",
  "channel": "<channel-name>" // Optional, unsubscribe from all channels if omitted
}

Response:

• Success:

{
  "type": "internal-response",
  "code": 200,
  "data": {
    "message": "Unsubscribed from <channel-name>"
  }
}

• Failure (Invalid Channel):

{
  "type": "internal-response",
  "code": 404,
  "data": {
    "error": "Invalid channel."
  }
}

3. Get Current Subscriptions

Clients can request a list of their current subscriptions.

Request:

{
  "type": "get-subscriptions"
}

Response:

{
  "type": "internal-response",
  "code": 200,
  "data": {
    "subscriptions": ["<channel-name-1>", "<channel-name-2>"]
  }
}

4. Get Room List

Clients can request a list of available rooms.

Request:

{
  "type": "room-list"
}

Response:

• Success:

{
  "type": "room-list",
  "code": 200,
  "count": <number-of-rooms>,
  "data": ["<room-name-1>", "<room-name-2>"]
}

• Failure (No Rooms Available):

{
  "type": "room-list",
  "code": 503,
  "count": 0,
  "data": {
    "error": "Room list is currently empty. Please try again later."
  }
}

Real-Time Updates

When subscribed to a channel, clients will receive real-time updates in the following format:

Message:

{
  "type": "iem-message",
  "data": {
    "channel": {
      "location": "<location-name>",
      "room": "<room-name>"
    },
    "event": {
      "name": "<event-name>",
      "priority": <priority-level>,
      "code": "<event-code>"
    },
    "body": "<message-body>",
    "timestamp": "<timestamp>",
    "wmo": "<wmo-code>",
    "pil": "<pil-code>",
    "station": "<station-name>",
    "raw": "<raw-product-id>",
    "rawBody": "<raw-message-body>",
    "image": "<image-url>", // Optional
    "productText": "<product-text>" // Optional
  }
}

The Priority level is a number from 1 to 5, 1 being the loest priority and 5 being the highest. These priority levels are defined per alert type by the developers of the IEM alerter system.

Error Handling

If an error occurs, the server will send an error response:

{
  "type": "internal-response",
  "code": 500,
  "data": {
    "error": "Internal server error."
  }
}