WebSocket — Realtime API

API-SPORT.ru предоставляет WebSocket-канал для подписки на live-обновления матчей. Это главный способ получать данные в реальном времени — без polling и без нагрузки на REST.

Endpoint

wss://ws.api.api-sport.ru

Авторизация

API-ключ передаётся в query-параметре при установлении соединения:

wss://ws.api.api-sport.ru/?apiKey=YOUR_API_KEY

Поддерживается также синоним ?api_key=YOUR_API_KEY.

Если ключ отсутствует или невалиден — сервер закроет соединение с кодом 1008 и текстом причины (Unauthorized: Missing API key или Unauthorized: Invalid API key).

Первое сообщение от сервера

Сразу после успешной авторизации сервер шлёт приветствие:

{
  "type": "connected",
  "message": "Successfully connected to Sport API WebSocket server",
  "connectionId": "conn_1714123200000_1",
  "timestamp": 1714123200000
}

connectionId имеет вид conn_<unixMs>_<counter> и используется только для логирования на стороне сервера — клиенту достаточно сохранить его при дебаге, никакой бизнес-логики на нём строить не нужно.

Принцип работы

1. Подключение к wss://ws.api.api-sport.ru/?apiKey=....
2. Получаем connected-сообщение.
3. Подписка на топик через сообщение { "action": "subscribe", ... } — см. Subscribe.
4. Если подписка на конкретный матч — приходит match_snapshot (полное состояние).
5. По мере изменений — приходят match_snapshot или match_delta (см. Snapshot vs Delta).

Heartbeat

Сервер каждые 30 секунд отправляет native WebSocket ping-frame (через ws.ping()). Стандартные WebSocket-клиенты автоматически отвечают pong без участия прикладного кода.

Если сервер не получает никакой активности (ping-pong или сообщения) в течение 120 секунд — соединение закрывается с кодом 1000 и причиной Connection timeout due to inactivity.

Кроме native heartbeat, поддерживается прикладной ping:

// client → server
{ "action": "ping" }

// server → client
{ "type": "pong", "timestamp": 1714123200000 }

Лимиты

• Максимум 5 одновременных WebSocket-соединений на один API-ключ. При попытке открыть 6-е соединение — сервер закроет самое старое соединение пользователя с кодом 1008 и причиной Connection limit exceeded. Oldest connection closed..
• Количество подписок внутри одного соединения не ограничено.
• WebSocket-трафик не учитывается в REST dailyRequestLimit тарифного плана.

На что можно подписаться

Топик	Описание
sport:football	Все live-матчи футбола
sport:tennis	Все live-матчи тенниса
match:football:12345678	Конкретный матч

См. Subscribe и Snapshot vs Delta.