REST, SSE или WebSocket — как получать данные

Задача → канал

Начните отсюда. Большинству хватает первых двух строк, и держать соединение вообще не нужно.

Что вы делаете	Чем брать	Почему так
Страница матча, таблица, расписание на сайте	GET /v1/event/{id} GET /v1/events	Обычные запросы плюс ваш кэш. Соединение держать не нужно, отладка — обычным curl.
Первая заливка истории к себе в базу	GET /v1/sync	Матчи с полной деталью порциями до 500 и курсор на следующую страницу.
Ночная сверка «у меня то же, что у вас»	GET /v1/sync	Тот же запрос с сохранённым курсором отдаёт только изменившееся — заливка и сверка одним кодом.
Счёт меняется прямо в открытой вкладке	GET /v1/stream	Поток событий (SSE). Браузер сам переподключается, и мы досылаем пропущенное.
Ваш сервер держит одно соединение и раздаёт всем	GET /v1/stream WS /v1/stream/ws	Одно соединение вместо тысячи опросов от каждого клиента.
Нужен двусторонний обмен	WS /v1/stream/ws	WebSocket: у соединения есть обратный канал, и курсор едет в каждом кадре.
Соединение держать не хотите вовсе	вебхуки	Мы сами приходим к вам подписанным запросом — как это устроено.
Догнать пропущенное после сбоя	GET /v1/stream/replay	События по курсору за 7 суток назад, до 500 за запрос.

Поток и вебхуки несут ОДИН И ТОТ ЖЕ конверт события — байт в байт. Перейти с одного канала на другой можно, не переписывая обработчик.

Поток событий (SSE)

Одно долгое HTTP-соединение, по которому идут события. Ключ передаётся заголовком x-api-key или параметром key — второе нужно браузерному EventSource, который своих заголовков ставить не умеет.

Фильтры прямо в адресе

sport, league, event_type — через запятую. Приедет только то, что попадает в фильтр и в ваш доступ.

Тишина не выглядит обрывом

Пока событий нет, раз в 15 секунд приходит служебная строка. Прокси не считает соединение мёртвым, и вы тоже.

Соединение обновляется само

Через 60 минут сервер просит переподключиться. Это нормальный цикл, а не сбой: он не даёт долгоживущему соединению тихо протухнуть.

После разрыва ничего не теряется

Клиент возвращает последний id заголовком Last-Event-ID, мы досылаем всё, что было после него — до 500 событий.

GET /v1/stream?sport=football

: connected cursor=98213152
retry: 1000

id: 98213377
event: match.goal
data: {"id":"evt_11220580_17","type":"match.goal", …}

: keep-alive 1785686355 cursor=98213377

// через час:
: server-cycle; reconnect with Last-Event-Id

WS /v1/stream/ws?key=…&sport=football

// первый кадр
{"type": "connected", "cursor": 98213152}

// событие: курсор + тот же конверт
{"cursor": 98213377, "id": "evt_11220580_17",
 "type": "match.goal", "data": { … }}

// в тишине
{"type": "heartbeat", "ts": 1785686355,
 "cursor": 98213377}

// через час
{"type": "reconnect", "cursor": 98213377}

WebSocket

Тот же поток, но кадрами JSON и с обратным каналом. Курсор едет в каждом кадре — хранить отдельный счётчик не нужно, при переподключении он передаётся параметром cursor.

Отказ виден по коду закрытия

4401 — ключ не принят, 4402 — канал не входит в тариф, 4422 — фильтр не разобран, 4429 — превышен лимит соединений. Не «просто закрылось».

Ключ параметром

Браузерный WebSocket заголовков не ставит, поэтому ключ передаётся в key. С сервера можно и заголовком x-api-key.

Лимиты

Чтобы посчитать нагрузку заранее, а не упереться в неё на живом туре.

5одновременных соединений на аккаунт — SSE и WebSocket вместе

60 минмаксимальная жизнь одного соединения, дальше переподключение

15 сслужебный кадр, пока событий нет

500событий досылается при переподключении

7 сутоквглубь дотягивается добор пропущенного

Тариф	Запросов в секунду	Поток и вебхуки
Free	500 запросов / мес	нет
Starter	5	нет
Pro	20	входят
Business	100	входят

Суточных ограничений на число запросов нет — только запросы в секунду. Полный состав тарифов — на странице тарифов.

Переподключение и добор

Разрыв соединения — обычное дело: мобильная сеть, перезапуск, часовой цикл. Порядок один и тот же.

Запомните курсор последнего события

В SSE это строка id:, в WebSocket — поле cursor кадра. Один целочисленный курсор на всё.

Подключитесь заново с ним же

SSE — заголовок Last-Event-ID (браузер ставит его сам) или параметр last_event_id. WebSocket — параметр cursor.

Пропущенное приедет первым

До 500 событий сразу после подключения, дальше поток идёт как обычно.

Если пропуск больше

Дозаберите его запросом: GET /v1/stream/replay?since={курсор}&limit=500. В ответе — next_cursor и has_more, листайте, пока не догоните.

Если пропуск ещё больше

Глубже 7 суток события уже не хранятся — сверяйтесь через GET /v1/sync, который идёт по самим матчам, а не по событиям.

Чего нет

Ограничения канала важнее его достоинств: по ним считается архитектура.

Неограниченного числа соединений. Их 5 на аккаунт; шестое получит отказ. Правильная схема — одно соединение на вашей стороне и раздача своим клиентам, а не соединение из каждой вкладки.
Вечного соединения. Через 60 минут придёт просьба переподключиться. Обработчик переподключения обязателен, он же спасёт при обрыве сети.
Строгого порядка и ровно одной доставки. Порядок восстанавливается по sequence внутри матча, повтор возможен — обработчик должен быть идемпотентным.
Потока «всех изменений подряд». В потоке идут события матчей из каталога — те же, что у вебхуков. Это не журнал всех правок базы.
Хранения дольше 7 суток. За более старым — обычные запросы к матчам.
Потока и вебхуков на младших тарифах. Они входят в Pro и Business.

Значения на странице сверены с боевой отдачей 5 августа 2026.

Другие разделы

КоэффициентыКниги, рынки, сегменты матча и привязка к нашим id. ВебхукиПодписанные POST-запросы, повтор и добор пропущенного. ИсторияС какого года и сколько матчей по каждому виду. Русские названияТурниры, команды и игроки по-русски рядом с оригиналом. ВиджетыГотовые блоки в iframe — таблица и профиль лиги.

REST, поток или вебхук