Перейти к основному содержимому

Букмекерские коэффициенты

API возвращает коэффициенты двух уровней:

  • oddsBase — базовые рынки (1×2, Over/Under, Handicap). Бесплатно для всех тарифов.
  • oddsBk — расширенные рынки от конкретных букмекеров. Поддерживаются пять букмекеров: Melbet (slug melbet), Pari (slug pari), Marathon (slug marathon), Betboom (slug betboom) и Pinnacle (slug pinnacle). Параметр bookmaker_ids принимает melbet, pari, marathon, betboom, pinnacle (можно через запятую). Дополнительные букмекеры будут добавлены в следующих версиях — следите за Changelog.

Pari (slug pari) доступен для всех семи видов спорта — футбол, хоккей, баскетбол, теннис, настольный теннис (с v2.0.32), волейбол, киберспорт. Набор рынков базовый: исход (1×2 / 2 исхода), двойной шанс, фора, тотал; в настольном теннисе — исход, фора и тотал по очкам. В теннисе дополнительно — фора по сетам (sets_handicap), в киберспорте — фора по картам (maps_handicap), в Dota 2 и LoL фора и тотал — по убийствам (kills_handicap / total_kills); в баскетболе исход Pari — победитель с учётом овертайма (result_including_overtime).

Marathon (slug marathon) доступен для всех семи видов спорта — футбол, хоккей, баскетбол, теннис, настольный теннис, волейбол, киберспорт. Набор рынков (зависит от вида спорта): исход (1×2 / 2 исхода), двойной шанс, фора, тотал, индивидуальные тоталы команд, «обе забьют», тотал чёт/нечёт. В теннисе, настольном теннисе и волейболе — также фора и тотал по сетам/партиям (sets_handicap / total_sets), в киберспорте — фора и тотал по раундам (handicap / total) и по картам (maps_handicap / total_maps), в баскетболе — победитель с учётом овертайма (result_including_overtime).

Betboom (slug betboom) доступен для всех семи видов спорта — футбол, хоккей, баскетбол, теннис, настольный теннис, волейбол, киберспорт. Набор рынков (зависит от вида спорта): исход (1×2 — для видов спорта с ничьей), фора, тотал. Для футбола дополнительно доступны те же рынки по таймам (1-й и 2-й тайм) — слаги вида 1st_half_total, 2nd_half_handicap, 1st_half_result.

Pinnacle (slug pinnacle) — пока только футбол, прематч и лайв. Рынки полного матча: исход (1×2), азиатская фора (asian_handicap, все линии, включая четвертные), тотал (total, все линии), индивидуальные тоталы (total_team_1 / total_team_2), двойной шанс (double_chance), обе забьют (btts), победа с возвратом при ничьей (draw_no_bet). Коэффициенты — десятичные (конвертация из американского формата, 3 знака). Дополнительные поля в строках и исходах: changedAt — момент последнего изменения цены (мс), limit — максимальная ставка Pinnacle по рынку (сигнал ликвидности). updatedAt доски — время формирования данных источником (котировки гостевого API Pinnacle могут отставать на несколько минут). Доска oddsBk.pinnacle доступна с v2.0.27; hasBkOdds.pinnacle показывает наличие котировок Pinnacle для матча.

Фильтрация матчей с коэффициентами​

# Только матчи с букмекерскими коэффициентами
curl -H "Authorization: YOUR_KEY" \
"https://api.api-sport.ru/v2/football/matches?has_bk_odds=true"

# Включить рынки конкретных букмекеров в payload
curl -H "Authorization: YOUR_KEY" \
"https://api.api-sport.ru/v2/football/matches/12345678?with_bk_odds=true&bookmaker_ids=melbet,pari,marathon,betboom,pinnacle"

Структура oddsBk​

oddsBk — объект, где ключи — слаги букмекеров (melbet, pari, marathon, betboom, pinnacle). Значение — данные букмекера (BookmakerOddsData):

{
"oddsBk": {
"melbet": {
"slug": "melbet",
"name": { "en": "Melbet", "ru": "Мелбет" },
"updatedAt": 1717000000000,
"isBettingActive": true,
"markets": {
"result": {
"name": { "en": "Result", "ru": "Исход" },
"hasArgument": false,
"status": "open",
"stakeKeys": ["w1", "x", "w2"],
"stakes": {
"w1": { "name": { "en": "Win1", "ru": "П1" }, "factor": 1.85, "dateUpdateMs": 1717000000000 },
"x": { "name": { "en": "X", "ru": "X" }, "factor": 3.40, "dateUpdateMs": 1717000000000 },
"w2": { "name": { "en": "Win2", "ru": "П2" }, "factor": 4.20, "dateUpdateMs": 1717000000000 }
}
},
"total": {
"name": { "en": "Total", "ru": "Тотал" },
"hasArgument": true,
"unit": "goals",
"status": "open",
"stakeKeys": ["over", "under"],
"stakes": {
"over": { "name": { "en": "Over", "ru": "Больше" }, "lines": [ { "argument": 2.5, "factor": 1.95, "dateUpdateMs": 1717000000000 } ] },
"under": { "name": { "en": "Under", "ru": "Меньше" }, "lines": [ { "argument": 2.5, "factor": 1.88, "dateUpdateMs": 1717000000000 } ] }
}
}
}
},
"pari": {
"slug": "pari",
"name": { "en": "Pari", "ru": "Пари" },
"updatedAt": 1717000000000,
"isBettingActive": true,
"markets": {
"result": {
"name": { "en": "Result", "ru": "Исход" },
"hasArgument": false,
"status": "open",
"stakeKeys": ["w1", "x", "w2"],
"stakes": {
"w1": { "name": { "en": "Win1", "ru": "П1" }, "factor": 1.80, "dateUpdateMs": 1717000000000 },
"x": { "name": { "en": "X", "ru": "X" }, "factor": 3.50, "dateUpdateMs": 1717000000000 },
"w2": { "name": { "en": "Win2", "ru": "П2" }, "factor": 4.40, "dateUpdateMs": 1717000000000 }
}
}
}
},
"marathon": {
"slug": "marathon",
"name": { "en": "Marathon", "ru": "Марафон" },
"updatedAt": 1717000000000,
"isBettingActive": true,
"markets": {
"result": {
"name": { "en": "Result", "ru": "Исход" },
"hasArgument": false,
"status": "open",
"stakeKeys": ["w1", "x", "w2"],
"stakes": {
"w1": { "name": { "en": "Win1", "ru": "П1" }, "factor": 2.40, "dateUpdateMs": 1717000000000 },
"x": { "name": { "en": "X", "ru": "X" }, "factor": 3.30, "dateUpdateMs": 1717000000000 },
"w2": { "name": { "en": "Win2", "ru": "П2" }, "factor": 2.90, "dateUpdateMs": 1717000000000 }
}
},
"total": {
"name": { "en": "Total", "ru": "Тотал" },
"hasArgument": true,
"unit": "goals",
"status": "open",
"stakeKeys": ["over", "under"],
"stakes": {
"over": { "name": { "en": "Over", "ru": "Больше" }, "lines": [ { "argument": 2.5, "factor": 1.92, "dateUpdateMs": 1717000000000 }, { "argument": 3.5, "factor": 3.10, "dateUpdateMs": 1717000000000, "suspended": true } ] },
"under": { "name": { "en": "Under", "ru": "Меньше" }, "lines": [ { "argument": 2.5, "factor": 1.88, "dateUpdateMs": 1717000000000 }, { "argument": 3.5, "factor": 1.35, "dateUpdateMs": 1717000000000, "suspended": true } ] }
}
}
}
},
"betboom": {
"slug": "betboom",
"name": { "en": "BetBoom", "ru": "БетБум" },
"updatedAt": 1717000000000,
"isBettingActive": true,
"markets": {
"result": {
"name": { "en": "Result", "ru": "Исход" },
"hasArgument": false,
"status": "open",
"stakeKeys": ["w1", "x", "w2"],
"stakes": {
"w1": { "name": { "en": "Win1", "ru": "П1" }, "factor": 1.90, "dateUpdateMs": 1717000000000 },
"x": { "name": { "en": "X", "ru": "X" }, "factor": 3.60, "dateUpdateMs": 1717000000000 },
"w2": { "name": { "en": "Win2", "ru": "П2" }, "factor": 3.90, "dateUpdateMs": 1717000000000 }
}
},
"1st_half_total": {
"name": { "en": "1st Half: Total", "ru": "1-й тайм: Тотал" },
"hasArgument": true,
"unit": "goals",
"status": "open",
"stakeKeys": ["over", "under"],
"stakes": {
"over": { "name": { "en": "Over", "ru": "Больше" }, "lines": [ { "argument": 1.5, "factor": 1.85, "dateUpdateMs": 1717000000000 } ] },
"under": { "name": { "en": "Under", "ru": "Меньше" }, "lines": [ { "argument": 1.5, "factor": 1.90, "dateUpdateMs": 1717000000000 } ] }
}
}
}
}
}
}

Ключевые моменты (схемы BookmakerOdds / BookmakerOddsData / BkOddsMarket / BkOddsStake / BkOddsLine):

  • Один ключ — один рынок у всех букмекеров. В пределах вида спорта ключ рынка означает одно и то же у каждого букмекера, включая единицу линий (поле unit, см. Единицы линий): например рынок result с исходами w1 / x / w2, рынок total с over / under. Поэтому коэффициенты разных букмекеров сравниваются по ключу рынка.
  • Стороны привязаны к командам матча API, а не к порядку участников у букмекера: сторона 1 (w1, 1x, handicap_1, total_team_1) — всегда homeTeam матча, сторона 2 (w2, x2, handicap_2, total_team_2) — awayTeam. Если букмекер перечисляет команды в другом порядке (например, гостевая команда первой), доска приводится к ориентации матча. У гандикапов argument — собственная линия той стороны, к которой относится исход, со знаком с её точки зрения: handicap_1 — фора homeTeam, handicap_2 — фора awayTeam. Сравнимая пара — handicap_1 с -1.5 и handicap_2 с +1.5; соглашение одинаково у всех букмекеров.
  • markets — это объект, ключи которого — слаги рынков (result, total, handicap, double_chance, …; у некоторых букмекеров — также рынки по периодам/таймам, напр. 1st_half_total, 2nd_half_handicap), а не массив. Порядок исходов — в stakeKeys.
  • stakes — тоже объект, ключи — слаги исходов (w1, over, …).
  • hasArgument: false → у исхода поле factor (коэффициент).
  • hasArgument: true → вместо factor у исхода массив lines[]: каждый элемент имеет argument (значение тотала/гандикапа), factor (коэффициент) и dateUpdateMs. lines отсортирован по argument. У таких рынков есть поле unit — единица измерения argument.
  • name везде — мультиязычный объект { en, ru }.
  • updatedAt — время последнего обновления доски (timestamp в мс); isBettingActive — активны ли ставки сейчас. Как судить о свежести — Свежесть данных.
  • status рынка — open | suspended: приём ставок по рынку приостановлен у источника, цены при этом сохраняются. Приостановку передают Marathon, Pinnacle и Pari; у Melbet и BetBoom значение всегда open — снятый рынок или исход у них просто исчезает из доски (у BetBoom отключённые исходы удаляются). Отдельного состояния «закрыт» нет: при активной доске закрытого рынка в markets нет. Рынок ставибелен, только если status: "open" и его стадия активна (isBettingActive / isBettingActiveByStage).
  • suspended: true у линии (lines[]) — приостановлена отдельная линия тотала/форы (Marathon, Pinnacle и Pari приостанавливают по линиям); у исхода простого рынка (hasArgument: false) — приостановлен отдельный исход (Pari). status рынка — агрегат: suspended, только когда приостановлены все линии или все исходы; при status: "open" отдельные линии и исходы могут нести suspended: true — такие цены не действуют. У открытых линий и исходов поля нет.
  • dateUpdateMs у исходов простых рынков (hasArgument: false) — как у lines[]: момент последнего изменения цены у источника (Melbet, Pinnacle), момент, когда изменение цены зафиксировано при обновлении линии (Pari), либо updatedAt доски (Marathon, BetBoom). См. Свежесть данных.

⚠️ Не путайте с oddsBase: там другой формат — массив OddsMarket[] с choices[].decimal. У oddsBk коэффициенты лежат в markets → stakes → factor / lines[].factor, как показано выше.

Единицы линий (unit)​

У рынков с линиями (hasArgument: true) поле unit указывает, в чём измеряется argument: goals — голы, points — очки, games — геймы, sets — сеты/партии, maps — карты, rounds — раунды, kills — убийства. В пределах вида спорта один и тот же ключ имеет одну единицу у всех букмекеров:

Вид спортаhandicap, total, total_team_1 / total_team_2, рынки периодов (1st_half_*, 1st_set_*, …)Отдельные ключи
Футбол, хоккейголы—
Баскетболочки—
Теннисгеймы (1st_set_* — геймы 1-го сета)sets_handicap, total_sets — сеты
Настольный теннис, волейболочкиsets_handicap, total_sets — партии
Киберспортраунды (CS2, Valorant, Rainbow Six и др.)maps_handicap, total_maps — карты; kills_handicap, total_kills — убийства (Dota 2, LoL)

Рынок есть только у тех букмекеров, кто его предлагает. Например, в Dota 2 и LoL нет рынков по раундам, поэтому handicap / total там отсутствуют: фора и тотал приходят в kills_handicap / total_kills, фора по картам — в maps_handicap.

Исход в баскетболе и хоккее. result — исход основного времени (1×2, ничья возможна). В баскетболе победитель с учётом овертайма (2 исхода) — отдельный ключ result_including_overtime, победитель 1-й четверти без ничьей (2 исхода) — 1st_quarter_winner. «1-й сет / матч» в теннисе, настольном теннисе и волейболе — 1st_set_full_time.

Свежесть данных​

  • updatedAt доски — когда данные букмекера последний раз получены от источника (у Pinnacle — время формирования данных источником). При odds_stage=all — по стадиям в updatedAtByStage. Линии, которые букмекер снял, исчезают из доски при следующем обновлении, поэтому всё, что есть на доске, — действующие линии на момент updatedAt.
  • dateUpdateMs цены (у линий lines[] и у исходов простых рынков) — когда эта цена последний раз изменилась у источника. Такая отметка есть у Melbet (у многих прематч-цен — null) и Pinnacle (там же changedAt, время изменения рынка); у Pari — момент, когда изменение цены зафиксировано при обновлении линии букмекера (точность — несколько секунд); у Marathon и BetBoom она равна updatedAt доски. Если dateUpdateMs старше updatedAt на часы — цена просто не менялась, линия актуальна.
  • status рынка, lines[].suspended и suspended исхода — suspended означает приостановку приёма ставок у источника при сохранении цен (рынок целиком, отдельная линия или отдельный исход); закрытый рынок из активной доски исчезает.
  • Как определять устаревание: по возрасту updatedAt, флагу isBettingActive и status рынка. Рекомендуем считать устаревшей прематч-доску старше ~30 минут; к лайв-доске, не обновлявшейся несколько минут, относиться осторожно — рынок мог быть приостановлен.
  • WebSocket: дельта oddsBk приходит при изменении содержимого доски — цен, набора рынков и линий, признаков активности и status рынков (у Pinnacle — и limit), но не при подтверждении доски без изменений; актуальный возраст доски можно получить запросом REST.

Что передаёт источник по каждому букмекеру:

Букмекерstatus рынка / lines[].suspendeddateUpdateMs ценыisBettingActive доски
Melbetвсегда open (активность только на уровне события)реальное время изменения; у многих прематч-цен nullфлаг события у источника
Parisuspended у всех рынков при блокировке события целиком; при частичной блокировке — отдельные линии lines[].suspended и исходы suspendedвремя изменения цены, зафиксированное при обновлении линии (точность — несколько секунд)событие, пропавшее из линии, — false
Marathonsuspended при приостановке рынка целиком; отдельные линии — lines[].suspended= updatedAt доски (избыточно)состояние события у источника; событие, пропавшее из линии, — false
BetBoomвсегда open; отключённые исходы удаляются из доски= updatedAt доски (избыточно)событие, пропавшее из линии, — false
Pinnaclesuspended, если рынок у источника не открыт; отдельные линии — lines[].suspendedchangedAt рынкадо cutoff прематча / пока событие активно

Объединение прематча и лайва (odds_stage=all)​

По умолчанию oddsBk содержит одну доску каждого букмекера — текущей стадии: до начала матча это прематчевые коэффициенты, после начала — лайв. Параметр odds_stage=all (работает только вместе с with_bk_odds=true) объединяет обе стадии в одну доску по рынкам:

  • рынок есть в лайв-доске букмекера → отдаётся его лайв-версия целиком (stage: "live");
  • рынка в лайве нет → остаётся прематчевая версия (stage: "prematch") — так после начала матча доступен и прематчевый набор рынков (обычно он заметно шире лайвового);
  • смешения внутри рынка не бывает: каждый рынок всегда одностадийный.

Дополнительные поля этого режима:

{
"updatedAt": 1717000000000,
"updatedAtByStage": { "prematch": 1716990000000, "live": 1717000000000 },
"isBettingActive": true,
"isBettingActiveByStage": { "prematch": false, "live": true },
"markets": {
"result": { "stage": "live", "остальное": "лайв-версия рынка целиком" },
"btts": { "stage": "prematch", "остальное": "прематч-рынок без лайв-аналога" }
}
}
  • stage у рынка — из какой стадии его коэффициенты.
  • updatedAtByStage — время обновления каждой стадии (null — этой стадии у букмекера нет); updatedAt доски в этом режиме — максимум по стадиям.
  • isBettingActiveByStage — принимает ли букмекер ставки по каждой стадии. Правило актуальности: рынок ставибелен, только если его стадия активна. Прематч-рынки после начала матча всегда неактивны — это архив (в том числе закрывающая линия), а не действующие цены.

Без odds_stage формат и поведение прежние — существующие интеграции не затронуты.

Поле hasBkOdds​

Всегда присутствует в Match — по флагу на каждого букмекера:

{ "hasBkOdds": { "melbet": true, "pari": false, "marathon": true, "betboom": true, "pinnacle": true } }

Это позволяет быстро отфильтровать матчи без загрузки полных коэффициентов. Наличие коэффициентов у букмекеров независимо: у матча могут быть данные только одного из них, обоих или ни одного.

Словарь рынков​

Словарь слагов рынков — /v2/BkOddsDict.json: массив записей { "slug": "sets_handicap", "name": { "en": "Sets Handicap", "ru": "Фора по сетам" } }. Исходы в словарь не входят — их названия приходят в самих рынках (stakes.<ключ>.name), единица линий — в поле unit рынка.

curl https://api.api-sport.ru/v2/BkOddsDict.json

Это статический файл (~МБ), кэшируйте на 24 часа.

Изменение коэффициентов в реальном времени​

Коэффициенты приходят через WebSocket: match_snapshot включает oddsBk всех подключённых букмекеров, а при изменении кэфов подписчикам матча приходит match_delta с блоком changes.updated.oddsBk.<bookmaker> целиком (применять заменой блока, не deep-merge). Дельта отправляется только при реальном изменении значений. Подробнее — WebSocket → Snapshot vs Delta.