Букмекерские коэффициенты
API возвращает коэффициенты двух уровней:
oddsBase— базовые рынки (1×2, Over/Under, Handicap). Бесплатно для всех тарифов.oddsBk— расширенные рынки от конкретных букмекеров. Поддерживаются пять букмекеров: Melbet (slugmelbet), Pari (slugpari), Marathon (slugmarathon), Betboom (slugbetboom) и Pinnacle (slugpinnacle). Параметр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[].suspended | dateUpdateMs цены | isBettingActive доски |
|---|---|---|---|
| Melbet | всегда open (активность только на уровне события) | реальное время изменения; у многих прематч-цен null | флаг события у источника |
| Pari | suspended у всех рынков при блокировке события целиком; при частичной блокировке — отдельные линии lines[].suspended и исходы suspended | время изменения цены, зафиксированное при обновлении линии (точность — несколько секунд) | событие, пропавшее из линии, — false |
| Marathon | suspended при приостановке рынка целиком; отдельные линии — lines[].suspended | = updatedAt доски (избыточно) | состояние события у источника; событие, пропавшее из линии, — false |
| BetBoom | всегда open; отключённые исходы удаляются из доски | = updatedAt доски (избыточно) | событие, пропавшее из линии, — false |
| Pinnacle | suspended, если рынок у источника не открыт; отдельные линии — lines[].suspended | changedAt рынка | до 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.