Документация SportWire API

REST-интерфейс к спортивным данным: расписание, live, события, статистика, xG, составы, коэффициенты, таблицы, история и справочники. Базовый URL — https://api.sportwire.ru. Все ответы — JSON в UTF-8; даты — ISO-8601 (UTC).

Обзор

REST API поверх единой модели данных: эндпоинты /v1/…, ключ в заголовке X-API-Key.

Каждая сущность (матч, турнир, команда, игрок) — единая и недублированная; названия доступны на нескольких языках, включая русский (см. Локализация).

Аутентификация

API-ключ выдаётся мгновенно в личном кабинете (тариф Trial — бесплатно).

curl https://api.sportwire.ru/v1/sports \
  -H "X-API-Key: ВАШ_КЛЮЧ"

Для встраивания картинок в <img> ключ можно передать как ?key=.

Лимиты и тарифы

Текущий расход виден в личном кабинете. При превышении частоты запросов (запросов/сек) — ответ 429. Суточных и месячных лимитов нет.

Ошибки

Локализация (RU)

Названия лиг, турниров, команд и стран отдаются объектом name_i18n с ключами по локали — русский лежит рядом с оригиналом:

"name_i18n": { "en": "Premier League", "ru": "Премьер-лига" }

Берите name_i18n.ru для русского интерфейса или name_i18n.en для оригинала. Где русского ещё нет — поле может отсутствовать (заполнение идёт постоянно).

Виды спорта

Список видов спорта с идентификаторами и названиями.

{ "sports": [
  { "id": 1, "slug": "football",   "name_i18n": {"en":"Football","ru":"Футбол"} },
  { "id": 2, "slug": "basketball", "name_i18n": {"en":"Basketball","ru":"Баскетбол"} }
]}

Матчи и расписание

Матчи с фильтрами. Параметры:

GET /v1/events?sport=football&date=2026-06-02

{ "count": 312, "events": [{
    "id": 1662352, "scheduled_start": "2026-06-02T18:00:00Z",
    "status": "finished", "round_name": "Premier League",
    "tournament": "Premier League", "sport": "football",
    "participants": [
      {"participant_id": 4504, "name": "Liverpool", "side": "home",
       "score": 2, "image_url": "/v1/participant/4504/image"},
      {"participant_id": 4509, "name": "Arsenal", "side": "away",
       "score": 1, "image_url": "/v1/participant/4509/image"}
    ]
}]}

Live-матчи

Только идущие сейчас матчи (опционально ?sport=). Счёт и статус обновляются каждые ~20 секунд.

Детализация матча

Полная карточка матча со всей собранной детализацией:

{ "id": 1662352, "status": "finished", "sport": "football",
  "tournament": "Premier League", "season_label": "25/26",
  "venue": "Anfield", "venue_city": "Liverpool", "venue_capacity": 53394,
  "referee": "Michael Oliver", "attendance": 53221,
  "participants": [ … счёт по сторонам … ],
  "incidents":  [ {"minute":23,"kind":"goal","period":"1H","player_name":"…","assist_name":"…"} ],
  "statistics": [ {"period":"ALL","group_name":"Possession",
                   "stat_name":"Ball possession","home_value":58,"away_value":42} ],
  "lineups":    [ {"side":"home","player_participant_id":…,"position":"GK",
                   "shirt_number":"1","is_substitute":false,"formation":"4-3-3","stats":{…}} ],
  "player_stats":[ {"participant_id":…,"player_name":"…","side":"home","position":"M",
                    "stats":{"rating":8.1,"accuratePass":76,"keyPass":4,"totalTackle":1,
                             "expectedGoals":0.32,"expectedAssists":0.42,"touches":103}} ],
  "coaches":    [ {"side":"home","coach_name":"…","coach_name_ru":"…"} ],
  "missing_players":[ {"side":"home","player_name":"…","position":"D",
                       "type":"missing","status":"…","reason_text":"…"} ],
  "shotmap":    [ {"player":{…},"xg":0.074,"shotType":"goal","situation":"assisted"} ],
  "momentum":   { "graphPoints":[…] },
  "odds":       [ {"market_name":"Full time","choice_name":"1","fractional_value":"1.73",
                   "bookmaker":"…","opening_value":"1.80","movement":"down"} ],
  "odds_bookmakers":[ {"bookmaker":"…","market":"1x2","side":"home","odds":2.77,
                       "opening":2.80,"is_live":false} ],
  "odds_best":  { "1x2":{"home":{"odds":2.77,"bookmaker":"…"},"draw":{…},"away":{…}},
                  "total_2_5":{…}, "btts":{…}, "double_chance":{…} },
  "best_players":[ {"side":"home","rating":"7.6","player_name":"…","position":"M"} ],
  "win_probability": { "homeWin":52, "draw":27, "awayWin":21 },
  "votes":      { "vote":{"vote1":…,"voteX":…,"vote2":…} },
  "highlights": [ {"title":"…","url":"…","thumbnail":"…"} ],
  "average_positions": { "home":[{"player_name":"…","x":51.2,"y":33.0}], "away":[…] },
  "tv_channels": { "ES":[663], "BR":[7548] },
  "points_history": [ {"tab":"Set 1","points":[…]} ],
  "fight":      { "method":"TKO", "finish_round":3 },
  "weather":    { "temperature_c":18, "conditions":"…" },
  "commentary": [ {"minute":45,"text":"Гол! …","text_en":"Goal! …","type":"goal","side":"home","player_name":"…"} ],
  "meta":       { "last_detail_at":"…", "last_checked_at":"…", "completeness":{…} }
}

Состав полей зависит от вида спорта и наличия данных у матча. Ключевые блоки: player_stats[].stats — полная статистика по каждому игроку (рейтинг, передачи, отборы, xG/xA, касания, спорт-специфичные метрики); coaches — тренеры сторон; missing_players — травмы/дисквалификации (type + reason_text); referee, venue_city, venue_capacity, attendance — справка о матче; best_players (MVP), win_probability, votes, highlights (видео), average_positions, tv_channels, points_history (по очкам — теннис/снукер/дартс), fight (метод/раунд — ММА). Коэффициенты: odds — усреднённые рыночные линии (включая зарубежные конторы) с движением и опенингом; odds_bookmakers — отдельные линии ряда лицензированных в РФ (ЦУПИС) букмекеров по каждому рынку; odds_best — лучшая цена по каждому исходу (line-shopping). Пре-матч и лайв; отдельный подключаемый модуль «Коэффициенты БК».

Жизненный цикл линий БК. Пре-матч линии появляются заранее — как только контора открывает роспись на событие (обычно за несколько дней до старта). Лайв-линии приходят с началом матча (доступны не у всех контор — часть отдаёт только пре-матч). Цена обновляется по мере движения рынка; стартовая цена (opening_value) и направление движения (movement) сохраняются на протяжении всего времени. Снятые/приостановленные конторой линии из ответа исчезают. После завершения матча линии контор по нему удаляются вскоре после финала — актуальны только события в игре и предстоящие. Блок meta.completeness показывает, какие секции заполнены. Глубина зависит от уровня лиги.

Турнирные таблицы новое

Таблица сезона: позиция, игры, В/Н/П, забито/пропущено, очки. type = total (по умолч.) · home · away · form; season — id сезона (иначе самый свежий).

{ "tournament":"Premier League", "season_label":"25/26", "standing_type":"total",
  "table": [ {"position":1,"participant_id":42,"name":"Arsenal","played":38,
              "wins":26,"draws":7,"losses":5,"scores_for":71,"scores_against":27,"points":85} ] }

Бомбардиры новое

Таблица бомбардиров сезона: ранг, игрок, команда, голы. season — id сезона (иначе самый свежий); limit ≤ 500.

{ "tournament_id":47325, "count":20,
  "scorers": [ {"rank":1,"participant_id":…,"player_name":"…","team_name":"…","goals":8} ] }

Турнирная сетка (кубки) новое

Сетка плей-офф для кубковых турниров: раунды → пары (команды, счёт, результат, сыграно). season — id сезона (иначе самый свежий). Доступно для футбольных/баскетбольных кубков.

{ "tournament":"FA Cup 25/26", "rounds": [
   { "name":"...", "matchups": [
      {"finished":true,"result":"1:0","home_score":"1","away_score":"0",
       "teams":[{"name":"Blackpool","code":"BLP"},{"name":"Scunthorpe United","code":"SCU"}]} ] } ] }

Рейтинги новое

kind: fifa · uefa_clubs · uefa_countries · atp_singles · atp_doubles · atp_singles_race · atp_doubles_race · wta_singles · wta_doubles · wta_singles_race · wta_doubles_race. Каждая запись: ранг, участник, очки, movement (со знаком, где источник даёт прошлый срез).

{ "kind":"fifa", "count":211,
  "rankings": [ {"rank":1,"participant":{"id":…,"name":"Argentina","name_ru":"Аргентина",
                 "country":"ARG"},"points":1877.3,"movement":2} ] }

Трансферы beta

История трансферов участника. Для игрока — его переходы (откуда/куда, дата, тип, сумма); для команды — входящие и исходящие. type = transfer · loan · loan_return · other. Beta — глубина и полнота зависят от лиги.

{ "participant_id":…, "type":"player", "count":3,
  "transfers": [ {"date":"2025-08-16","type":"transfer","player_name":"…",
                  "from_team":"…","to_team":"…","fee":12.5,"fee_currency":"EUR"} ] }

Глубина покрытия по лигам

Базовые данные — расписание, счёт, статус, участники — есть по всем матчам всех видов спорта. Глубина детализации (статистика, составы, шотмап/xG, предматчевая модель) зависит от уровня лиги: по топ-лигам доступно всё, по низшим дивизионам обычно только счёт и ключевые события. Это отражает наличие данных у источника, а не пробел в нашем сборе — глубокой статистики низших дивизионов и молодёжных турниров не существует ни у одного провайдера.

Проценты — реальное измеренное покрытие среди уже детализированных матчей (футбол): топ-лиги — ~95% статистика / ~95% составы / ~30–40% шотмап; остальные — 12% / 11% / 6%. Для live и недавних матчей топ-лиг детализация полная; исторический архив покрыт на измеренную выше глубину и пополняется регламентными до-сборами. Предматч-составы, травмы/дисквалификации и xG по игрокам доступны там же, где собираются составы и шотмапы. * Предматчевая модель считается автоматически, когда у обеих команд достаточно истории (≥ 4 матча на сторону) — для редких или молодёжных команд её может не быть (поле model = null).

Лиги с расширенными данными (составы / предматч-составы / травмы / статистика; для футбола ещё шотмап, xG, xG по игрокам): футбол — АПЛ, Ла Лига, Серия A, Бундеслига, Лига 1, Эредивизи, Лига Чемпионов / Европы / Конференций, Saudi Pro League, Бразилейрао, Чемпионшип, MLS и др.; баскетбол — NBA, WNBA, Евролига, Еврокубок, ABA, NCAA, NBB и др.; хоккей — NHL, КХЛ; бейсбол — MLB; плюс топ-турниры по регби, гандболу и волейболу. Точный текущий список и покрытие по каждой лиге — через GET /v1/tournaments.

Детальное покрытие по ведущим лигам

✓ — полное покрытие (≈90%+ finished-матчей) · % — доля finished-матчей с этим типом данных · — — данные этого типа у источника не существуют (напр. шотмап/xG есть только для футбола; моментум — для футбола и баскетбола). Окно — последние 365 дней; для live и недавних матчей детализация полная.

Срез по матчам за последние 365 дней (на момент генерации). Шотмап, xG и xG по игрокам — футбольные метрики; моментум доступен для футбола и баскетбола. Для live и недавних матчей топ-лиг детализация полная. Полный машиночитаемый список лиг и покрытие — через GET /v1/tournaments.

Турниры и лиги

Список турниров/лиг (опционально ?sport=), с количеством матчей, страной и полом.

{ "count": 18, "tournaments": [
  { "id": 17, "name": "Premier League",
    "name_i18n": {"en":"Premier League","ru":"Премьер-лига"},
    "sport": "football", "gender": "M", "country": "EN", "events": 14023 }
]}

Поиск

Нечёткий поиск команд и игроков по названию (с транслитерацией). Параметры: q, sport, type (team|player), limit.

GET /v1/participants/search?q=зенит&type=team

Команда / игрок

Профиль: тип, вид спорта, страна, пол, дата рождения (для игроков), name_i18n, image_url и дополнительные поля (стадион, амплуа, рост — где доступно).

Персональная статистика ИГРОКА: агрегат по всем матчам с детализацией (голы, удары, удары в створ, xG, xGOT) и последние матчи с per-match числами. Модуль «xG · shotmap».

{ "participant_id": 543227, "type": "player", "available": true,
  "totals": { "matches": 19, "goals": 18, "shots": 92, "shots_on_target": 44, "xg": 10.90, "xgot": 11.58 },
  "matches": [
    { "event_id": 10982017, "scheduled_start": "2026-07-04T…", "goals": 1, "shots": 9, "xg": 1.33,
      "home": "Argentina", "away": "Cabo Verde", "home_score": 3, "away_score": 2 } ] }

Изображения

Готовое изображение (логотип команды / фото игрока), 150×150. Можно встраивать напрямую:

<img src="https://api.sportwire.ru/v1/participant/4504/image?key=ВАШ_КЛЮЧ">

Матчи участника

Матчи конкретной команды/игрока (прошедшие и будущие), с пагинацией.

Страны

Список стран (ISO) с числом лиг и набором видов спорта. Категории вида «Amateur / Women / Youth» сведены к одной стране. Опционально ?sport=.

{ "count": 221, "countries": [
  { "iso": "BR", "name": "Brazil", "name_ru": "Бразилия",
    "leagues": 1266, "sports": ["basketball","football","volleyball"] },
  { "iso": "EN", "name": "England", "name_ru": "Англия", "leagues": 699, "sports": ["football"] }
]}

Лиги по странам

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

→ /leagues.html — более 43 000 лиг и турниров, 221 страна.

Программный доступ — через /v1/tournaments с фильтрами:

Предматчевая аналитика новое

Готовый аналитический пакет по матчу: форма и тренды обеих команд, очные встречи, турнирный контекст, математическая модель (Пуассон) с вероятностями исходов, «справедливыми коэффициентами» и value-сигналами против рынка, а также готовые трендовые ярлыки. Всё считается из исторических данных (≈2,9 млн матчей со счётом) — без чьих-либо «прогнозов».

{ "event_id": 1651128, "sport": "football",
  "tournament": { "id": 31384, "name": "Serie A", "name_ru": "Серия А" },
  "home": {
    "name": "Torino", "name_ru": "Торино",
    "form": {
      "last10": { "matches":10, "ppg":1.0, "gf_avg":1.0, "over_2_5":60.0,
                  "btts":60.0, "clean_sheet":20.0, "form":"DLWLL" },
      "home":   { "matches":10, "ppg":1.4, "gf_avg":1.3, "over_2_5":50.0 } },
    "discipline": { "matches":10, "cards_avg":2.3 },
    "standing": { "position":12, "played":38, "points":45, "goals_for":44, "goals_against":63 } },
  "away": { "name":"Juventus", "name_ru":"Ювентус", "form": { … }, "standing": { … } },
  "h2h": { "matches":3, "team_a_wins":0, "draws":2, "team_b_wins":1, "goals_avg":1.33, "btts":33.3,
           "recent":[{"date":"2025-11-09","score":"1:1"}] },
  "model": {
    "expected_goals": { "home":1.78, "away":1.51, "total":3.29 },
    "probabilities":  { "home_win":44.4, "draw":22.8, "away_win":32.8,
                        "over_2_5":63.9, "under_2_5":36.1, "btts":64.8 },
    "fair_odds":      { "home_win":2.25, "draw":4.38, "away_win":3.05, "over_2_5":1.56, "btts":1.54 },
    "likely_scorelines":[ {"score":"1:1","prob":10.0}, {"score":"2:1","prob":8.9} ] },
  "value_bets": [ {"market":"Full time","selection":"1","market_odds":2.50,"fair_odds":2.25,"edge_pct":11.1} ],
  "trends": [
    {"label":"Тотал больше 2.5","detail":"Торино: 60% из 10","side":"home"},
    {"label":"Обе забивают","detail":"Торино: 60% из 10","side":"home"} ],
  "disclaimer":"Статистические оценки на основе исторических данных. Не является ставкой, прогнозом или инвестиционной рекомендацией." }

Блоки формы — form.overall / last5 / last10 / home / away

Каждый блок формы — один и тот же набор метрик на разной выборке матчей (все / последние 5 / последние 10 / только дома / только в гостях). Для предстоящего матча выборка берётся строго ДО его даты — результат самого матча в расчёт не попадает (нет «подглядывания» в будущее).

Модель — model (методология)

Модель Пуассона. Для каждой команды считается сила атаки и обороны относительно среднего по лиге (отдельно для домашних и гостевых матчей); из них — ожидаемые голы (λ хозяев и гостей), а из распределения Пуассона — матрица вероятностей счёта, и уже из неё все вероятности, «справедливые» коэффициенты и наиболее вероятные счета. Доступна для футбола и хоккея.

value_bets сравнивает fair_odds с реальными коэффициентами рынка и показывает исходы с положительным перевесом: edge_pct = на сколько % рынок «щедрее» модели.

Очные встречи — h2h

Тренды команды и профиль лиги новое

Форма и тренды команды отдельно (общие / дома / в гостях / последние N), дисциплина и последние матчи.

Профиль лиги: средние голы, доля П1/Х/П2, % тоталов и ОЗ — за последние ~2,5 года.

{ "tournament_id":31384, "name":"Serie A", "name_ru":"Серия А", "sport":"football",
  "matches":772, "avg_goals":2.52, "avg_home_goals":1.32, "avg_away_goals":1.19,
  "home_win_pct":39.4, "draw_pct":28.1, "away_win_pct":32.5,
  "over_2_5_pct":47.3, "over_3_5_pct":24.5, "btts_pct":49.5 }

Live-тренды (in-play вероятности) новое

Живая вероятностная картина матча — отдельный виджет-фид: после каждого значимого эпизода (гол, удаление, пенальти) модель пересчитывает вероятности всех исходов — 1x2, двойной шанс, тоталы 0.5–6.5, форы, «обе забьют», следующий гол — и отдаёт вероятность + fair-коэффициент (1/p), рассчитанный независимо от букмекерских линий, движение вероятностей с прошлого пересчёта и краткий ИИ-комментарий (text_ru + highlights). Live-футбол топ-лиг (tier 1–2); пересчёт по инцидентам и каждые ~2,5 минуты. Списочный /v1/live-trends отдаёт все живые матчи с трендами одним ответом (limit ≤ 200) — удобно для ленты. Отдельный подключаемый модуль «Live-тренды».

{ "event_id": 10977319, "minute": 78, "phase": "2H", "score": { "home": 1, "away": 0 },
  "trigger": { "kind": "goal", "minute": 76, "side": "home" },
  "expected_remaining_goals": { "home": 0.21, "away": 0.35 },
  "outcomes": [
    { "market": "1x2", "selection": "home", "p": 0.82, "fair_odds": 1.22 },
    { "market": "double_chance", "selection": "1x", "p": 0.93, "fair_odds": 1.08 },
    { "market": "total", "line": 2.5, "selection": "over", "p": 0.18, "fair_odds": 5.56 },
    { "market": "handicap", "line": -1.5, "selection": "home", "p": 0.14, "fair_odds": 7.14 },
    { "market": "next_goal", "selection": "away", "p": 0.27, "fair_odds": 3.70 } ],
  "movement": [ { "market": "1x2", "selection": "home", "p_prev": 0.55, "p": 0.82, "delta": 0.27 } ],
  "prematch_1x2": { "home": 0.44, "draw": 0.27, "away": 0.29 },
  "ai": { "text_ru": "Гол на 76-й перевернул матч: хозяева ведут и контролируют темп…",
          "highlights": [ { "market": "total", "line": 2.5, "selection": "under",
                            "note": "низовой сценарий заметно укрепился" } ] },
  "model": "lt-poisson-1.0", "updated_at": "2026-07-03T14:20:07+00:00" }

Погода на стадионе новое

Погода в момент матча по координатам стадиона: температура и «ощущается», осадки и их вероятность, ветер и порывы, влажность, облачность, текстовое описание. Также доступна в блоке weather карточки матча /v1/event/{id}. Собирается для предстоящих матчей (прогноз) и доступна по сыгранным (архив), где известна площадка.

{ "event_id":1651128, "available":true,
  "weather": {
    "stadium":"Stadio Olimpico Grande Torino", "city":"Turin",
    "temperature_c":28.8, "feels_like_c":29.0, "conditions":"Ясно",
    "wind_speed_ms":1.5, "wind_gusts_ms":5.8, "precipitation_mm":0.0,
    "precipitation_prob_pct":null, "humidity_pct":39, "cloud_cover_pct":6,
    "weather_code":0, "is_forecast":false, "observed_hour_utc":"2026-05-24T19:00" } }

Виджеты новое

Готовые встраиваемые виджеты — серверный рендер в <iframe>, ключ остаётся на нашей стороне (ничего не светится в браузере, CORS не нужен). Имена команд и турниров — на русском.

Турнирная таблица

<iframe src="https://sportwire.ru/widget/standings?tournament=17"
        width="100%" height="520" frameborder="0"></iframe>

Профиль / тренды лиги

<iframe src="https://sportwire.ru/widget/trends?tournament=17"
        width="100%" height="190" frameborder="0"></iframe>

Демо и конструктор кода — на странице Продукты → Виджеты.

Способы доставки данных

beta Доступно по запросу — напишите info@sportwire.ru. Тарифы: Pro и выше.

SportWire отдаёт данные двумя способами — выбирайте под свою задачу:

Все каналы едины: один формат конверта и один event-bus. Доставка построена на транзакционном outbox: каждое каноническое изменение матча записывается в шину событий в той же транзакции, что и сами данные — поэтому событие не теряется даже при сбое. Отдельный воркер разбирает шину и доставляет её подписчикам с подписью и повторами; те же события можно читать стримом (SSE/WS) или добрать через API повторной выдачи (replay).

Сверка полноты (reconciliation). Для REST-режима и для «двойного прогона» при миграции есть две сверочные точки: GET /v1/tournament/{id}/events — полный календарь турнира одним запросом (cron-diff вашей БД против нашей, без обхода ленты по дням), и GET /v1/sync — дельта-синхронизация изменённых матчей по курсору (since, since_id). Подробнее — в разделе «Миграция».

Вебхуки (push-доставка) beta

Зарегистрируйте URL — и мы будем присылать на него подписанный JSON при каждом изменении подписанных вами матчей: смена статуса, изменение счёта, гол/карточка, подтверждение состава. Управление — в личном кабинете или через API кабинета (нужна сессия кабинета).

1. Регистрация вебхука

{ "url": "https://your-app.example.com/hooks/sportwire",
  "event_types": ["match.goal","match.score_changed"],   // [] = все типы
  "sports":  ["football","basketball"],                    // [] = все виды
  "leagues": [34, 35072] }                                 // id турниров, [] = все

// Ответ (secret показывается ОДИН раз — сохраните его):
{ "ok": true, "id": 12, "secret": "whsec_…", "event_types": ["match.goal","match.score_changed"],
  "sports": ["football","basketball"], "leagues": [34,35072] }

Ещё эндпоинты кабинета: GET /account/api/webhooks — список (со статусом и здоровьем доставки) · DELETE /account/api/webhooks/{id} — удалить · POST /account/api/webhooks/{id}/test — тестовый webhook.ping · POST …/{id}/rotate-secret — сменить secret · POST …/{id}/pause и …/{id}/resume — пауза/возобновление · GET …/{id}/deliveries — лог доставки · GET /account/api/webhooks/catalog — каталог событий.

Безопасность URL. Адрес вебхука обязан быть публичным https://…. Частные, loopback, link-local и метадата-адреса (10/8, 172.16/12, 192.168/16, 127/8, 169.254/16, ::1, fc00::/7, 169.254.169.254 и т.п.) отклоняются при регистрации и повторно проверяются перед каждой отправкой; редиректы не выполняются. Если ваш endpoint N раз подряд уходит в dead-letter, подписка автоматически ставится на паузу («предохранитель»). Дальше мы сами пробуем восстановиться: подписанный пробный webhook.ping через 15 мин, затем реже (до 1 раза в 6 ч). Как только endpoint ответил 2xx — подписка снова активна, а пропущенные за время разрыва события доотправляются автоматически (по порядку sequence). Ручной resume делает то же самое сразу. Обычный деплой consumer-сервиса на 10–20 минут, таким образом, не требует никаких действий с вашей стороны. Изредка (только в «тихие» периоды, когда реальных доставок нет) может прийти проверочный webhook.ping — просто ответьте 2xx.

2. Каталог событий

Opt-in типы. Высокочастотные match.detail_changed и odds.changed доставляются только если явно перечислены в event_types подписки — пустой список («все события») их не включает. Это защита от неожиданного потока на существующие подписки. Паттерн использования: по match.detail_changed перечитайте /v1/event/{id} один раз — вместо пулла детали по каждому голу (деталь может не успеть измениться) и вместо слепых периодических пуллов (статистика меняется и без голов).

3. Формат доставки (payload)

POST https://your-app.example.com/hooks/sportwire
Content-Type: application/json
User-Agent: SportWire-Webhooks/1.0
X-SportWire-Timestamp: 1793456789
X-SportWire-Signature: sha256=<hex>
X-SportWire-Event-Id: evt_1662352_12
Idempotency-Key: evt_1662352_12

{ "id": "evt_1662352_12",                 // стабильный ключ идемпотентности
  "type": "match.goal",
  "created_at": "2026-07-10T18:03:18Z",
  "sequence": 12,                          // порядковый номер В РАМКАХ матча
  "data": {
    "match": { "id": 1662352, "sport": "football", "status": "live",
               "tournament": { "id": 34, "name": "Premier League" },
               "home": { "name": "Arsenal" }, "away": { "name": "Chelsea" },
               "last_detail_at": "2026-07-10T18:03:11Z",  // watermark реального изменения детали
               "has_detail": true },                       // есть ли лента событий вообще
    "delta":    { "kind": "goal", "side": "home", "minute": 23, "player": "…", "assist": "…" },
    "snapshot": { "home_score": 1, "away_score": 0 }   // состояние на момент события
  } }

Нужно ли пуллить деталь? Сравните data.match.last_detail_at с тем, что вы уже применяли: не изменился — деталь перечитывать не нужно. has_detail=false — ленты у матча (пока) нет вовсе.

delta — что изменилось, snapshot — состояние сразу после изменения (зафиксировано в момент события, а не при доставке). Маркеры источника данных в payload не передаются.

4. Проверка подписи (обязательно)

Подпись — HMAC-SHA256 над строкой «{timestamp}.{тело}» вашим secret. Проверяйте её на каждом запросе и сверяйте, что X-SportWire-Timestamp не старше ~5 минут (защита от повторной отправки).

Ротация без простоя. Заголовок может содержать несколько подписей через запятую: X-SportWire-Signature: sha256=<новая>,sha256=<старая> — так происходит в течение ~24 ч после rotate-secret. Проверяйте любой из токенов (как в примерах ниже) — тогда смена секрета не рвёт доставку: обновите secret у себя в удобный момент внутри окна.

# Python
import hmac, hashlib
def verify(secret: str, headers, raw_body: bytes) -> bool:
    ts  = headers["X-SportWire-Timestamp"]
    expect = hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    for tok in headers["X-SportWire-Signature"].split(","):     # 1..2 подписи (окно ротации)
        if hmac.compare_digest(tok.strip().removeprefix("sha256="), expect):
            return True
    return False

// Node.js
const crypto = require("crypto");
function verify(secret, headers, rawBody /* Buffer */) {
  const ts  = headers["x-sportwire-timestamp"];
  const expect = crypto.createHmac("sha256", secret)
                       .update(ts + "." + rawBody.toString()).digest("hex");
  return (headers["x-sportwire-signature"] || "").split(",")   // 1..2 подписи (окно ротации)
    .some(tok => {
      const sig = tok.trim().replace("sha256=", "");
      return sig.length === expect.length &&
             crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expect));
    });
}

# Shell / curl-приёмник — та же проверка через openssl (RAW_BODY — сырое тело запроса как есть)
TS="$HTTP_X_SPORTWIRE_TIMESTAMP"          # заголовок X-SportWire-Timestamp
SIG="$HTTP_X_SPORTWIRE_SIGNATURE"         # заголовок X-SportWire-Signature (1..2 подписи через запятую)
EXPECT=$(printf '%s.%s' "$TS" "$RAW_BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
case ",$SIG," in *",sha256=$EXPECT,"*) echo ok ;; *) echo REJECT ;; esac

5. Порядок, идемпотентность, повторы

Все доставки (и повторы, и dead-letter) видны в логе доставки — в кабинете и через API кабинета.

Стриминг — SSE beta

Одно длинное HTTP-соединение вместо своего вебхук-эндпоинта: те же события того же event-bus приходят потоком (Server-Sent Events) по мере поступления. Тариф Pro и выше. Формат конверта — тот же, что у вебхуков (см. «Формат доставки»).

Авторизация — вашим API-ключом: заголовок x-api-key или, для браузерного EventSource, параметр ?key=. Фильтры (необязательно, через запятую): sport=football,basketball · league=34,35072 (id турниров) · event_type=match.goal,match.score_changed. Отдаются только виды спорта из вашего тарифа.

# поток (флаг -N = без буферизации curl)
curl -N -H "x-api-key: YOUR_KEY" \
  "https://api.sportwire.ru/v1/stream?sport=football&event_type=match.goal,match.score_changed"

# то, что приходит:
: connected cursor=845213
retry: 1000

id: 845214
event: match.goal
data: {"id":"evt_1662352_12","type":"match.goal","created_at":"2026-07-10T18:03:18Z","sequence":12,
       "data":{"match":{"id":1662352,"sport":"football","status":"live",
               "tournament":{"id":34,"name":"Premier League"},
               "home":{"name":"Arsenal"},"away":{"name":"Chelsea"}},
               "delta":{"kind":"goal","side":"home","minute":23},"snapshot":{"home_score":1,"away_score":0}}}

: keep-alive 1793456800 cursor=845214

Докачка (resume). В строке id: каждого события — курсор (глобальный, монотонный). При обрыве переподключитесь с заголовком Last-Event-Id: <курсор> (или ?last_event_id=) — мы доотдадим всё, что новее (в пределах окна свежести; для большого догона — Replay API ниже). Без курсора поток начинается «с текущего момента». Строки-комментарии : keep-alive раз в ~15 с держат соединение живым.

// Браузер — EventSource сам присылает Last-Event-Id при переподключении → докачка автоматическая
const es = new EventSource("https://api.sportwire.ru/v1/stream?key=YOUR_KEY&sport=football");
es.onmessage = (e) => { const evt = JSON.parse(e.data); /* e.lastEventId = курсор */ };
es.addEventListener("match.goal", (e) => { /* именованный тип */ });

Стриминг — WebSocket beta

Тот же поток по WebSocket. Тариф Pro и выше.

Авторизация — ?key=YOUR_KEY (или заголовок x-api-key для серверных клиентов). Те же фильтры sport/league/event_type. Докачка — ?cursor=<курсор>. Каждое событие — JSON-кадр {"cursor": <id>, …тот же конверт…}; служебные кадры {"type":"connected"|"heartbeat","cursor":…}.

const ws = new WebSocket("wss://api.sportwire.ru/v1/stream/ws?key=YOUR_KEY&sport=football&cursor=845214");
ws.onmessage = (e) => {
  const m = JSON.parse(e.data);
  if (m.type === "heartbeat" || m.type === "connected") return;
  // применяйте m (m.cursor — последний курсор для докачки)
};

API повторной выдачи (replay) beta

Догон/реконсиляция после простоя: страницами вернуть события из шины начиная с курсора. Ограничено по объёму и глубине (окно свежести). Тариф Pro и выше.

Авторизация API-ключом (x-api-key/?key=). Параметры: since — курсор (число) или ISO-время (2026-07-10T18:00:00Z); limit (с потолком); те же sport/league/event_type. Есть и вариант из кабинета по сессии: GET /account/api/webhooks/events.

GET /v1/stream/replay?since=845000&limit=200&sport=football
{ "events": [ { …тот же конверт… }, … ],
  "count": 200, "since": 845000, "next_cursor": 845200, "has_more": true }

# Догон без потерь: страницами по next_cursor, пока has_more=false,
# затем откройте SSE/WS с этого же курсора (Last-Event-Id / ?cursor=) — стык без дыр.

MCP-сервер — для Claude, ChatGPT, Cursor новое

Наш API втыкается в LLM напрямую по протоколу MCP (Model Context Protocol). Ваш ассистент (Claude Desktop, ChatGPT, Cursor, Gemini) получает 16 типизированных инструментов — искать матчи, брать карточку матча с картой ударов, таблицы, бомбардиров, статистику игрока, трансферы, модель Пуассона — и отвечает на обычном языке, сам ходя за данными. Один endpoint, ваш API-ключ.

Авторизация — тем же API-ключом в заголовке Authorization: Bearer <ключ>. Данные и покрытие ограничены вашим тарифом ровно как в REST: недоступный модуль вернёт ошибку с пометкой о тарифе. Инструменты: list_sports, search, list_leagues, live_matches, list_matches, match_details, match_shotmap, match_live_widget, match_predictions, league_standings, league_scorers, league_matches, entity, player_stats, entity_matches, transfers.

Claude Desktop / Cursor — добавьте в конфиг MCP (мост mcp-remote проксирует HTTP):

{
  "mcpServers": {
    "sportwire": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.sportwire.ru/mcp",
               "--header", "Authorization: Bearer ВАШ_API_КЛЮЧ"]
    }
  }
}

Клиенты с нативной поддержкой удалённого MCP (без моста) — просто URL и заголовок:

{ "mcpServers": { "sportwire": {
    "url": "https://api.sportwire.ru/mcp",
    "headers": { "Authorization": "Bearer ВАШ_API_КЛЮЧ" }
} } }

Проверка вручную (без клиента) — обычный JSON-RPC:

curl -X POST https://api.sportwire.ru/mcp \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"search","arguments":{"query":"Холанд","type":"player"}}}'

Миграция с enetpulse / другого провайдера гайд

Переходите с XML-фида enetpulse (или другого провайдера)? Наш путь — не «мост XML», а те же события, только чище: тот же поток изменений приходит через вебхуки или стриминг, но с канонизированными сущностями — без дубликатов, с единым i18n-именем (ru/en) и устойчивым id. Ниже — карта соответствия сущностей, соответствие событий и схема «двойного прогона» для проверки паритета без потерь.

1. Соответствие сущностей (field mapping)

2. Соответствие событий (их push → наш каталог)

3. Кросс-уолк идентификаторов

У нас единый канонический id матча / команды / турнира — не привязанный к провайдеру и без дублей-твинов. На время миграции сопоставьте свои прежние id с нашими по натуральным ключам (дата матча + команды + турнир) и сохраните нашу id рядом со своей; дальше работайте по нашей — она стабильна. Полный список матчей для сопоставления — /v1/tournament/{id}/events (весь календарь турнира одним запросом, с count_total для проверки полноты).

4. Двойной прогон и проверка паритета

Безопасный переход — параллельно принимать оба фида и сверять, пока расхождений не станет ноль:

1. Подключите вебхуки (или SSE/WS) на наши события параллельно текущему провайдеру.
2. Полнота: ночным cron сверяйте свою БД против GET /v1/tournament/{id}/events — так вы ловите пропущенные/лишние матчи без обхода ленты по дням.
3. Дельта: GET /v1/sync?since=…&since_id=… отдаёт матчи, чья деталь изменилась после курсора — удобно догонять расхождения по счёту/статусу.
4. Догон после простоя: GET /v1/stream/replay добирает пропущенные события из шины (страницами по next_cursor), затем открываете стрим с того же курсора — стык без дыр.
5. Когда расхождения на нуле N дней подряд — отключаете старый фид.

Итог: вы получаете те же события оперативнее (push вместо опроса XML) и чище (канонизированные сущности, единый i18n, устойчивые id), а сверочные эндпоинты гарантируют, что при переключении ничего не потеряется. Нужна помощь с маппингом под ваш прежний фид — info@sportwire.ru.

Схема данных

Модель данных SportWire — основные сущности и связи. Матч (EVENT) связан с турниром, сезоном и сторонами (со счётом) и обогащается событиями, статистикой, составами, коэффициентами, картой ударов с xG, графиком моментума и погодой. Названия — мультиязычные (name_i18n: EN/RU); сущности единые и недублированные.

Полный инвентарь данных

Что именно доступно — по каждому типу данных, до отдельного поля. Состав полей зависит от вида спорта и наличия детализации у конкретного матча; состав полей для конкретного матча отражают флаги полноты в ответе.

Матч — event

Стороны и счёт — participants

События матча — incidents

Голы, карточки (жёлтые/красные), замены, VAR, пенальти, начало/конец таймов и др. — по всей истории.

Статистика матча — statistics

Владение, удары (всего/в створ), угловые, фолы, офсайды, передачи, отборы, сейвы и десятки метрик; по таймам и за весь матч.

Составы — lineups

Коэффициенты — odds

Карта ударов + xG — shotmap

GET /v1/event/{id}/shotmap — по каждому удару, отсортировано по минуте:

momentum — график моментума по ходу матча (футбол, баскетбол).

Погода — weather

Турниры и таблицы — tournament / standings

Команды и игроки — participant

Аналитика (вычисляемое)

Поверх данных доступны вычисляемые блоки — форма и тренды, очные встречи, профиль лиги, модель Пуассона с вероятностями и «справедливыми» кэфами, value-сигналы. См. Предматчевую аналитику и Тренды.