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

Общ преглед

Един договор за петте договорени букмейкърски източника, със scope за всеки източник. Coverage endpoint-ът е източникът на истина: той показва кои спортове, пазари, фази и historical depth са достъпни, без частичен feed да изглежда като пълен.

Odds и движения

Текуща цена, opening/closing, high/low, movement count и време до kickoff.

Player props

Всяка наблюдавана линия и цена, с player, team, stat, period и source labels.

Решения и bets

Fair probability, EV, model version, rejection reason и отделни paper/placed записи.

Качество и резултати

Freshness, пропуски, partial responses, settlement, корекции и provenance.

Само за четене

API-то не приема и не поставя залози, не управлява bookmaker accounts и не мести средства.

Автентикация

След onboarding получавате scoped API key. Изпращайте го като Bearer token през HTTPS и никога не го вграждайте в browser или mobile client.

curl --request GET \
  --url 'https://api.favouriteodds.com/data/v1/odds/current?odds_phase=pre_match&limit=100' \
  --header 'Authorization: Bearer fo_live_your_key' \
  --header 'Accept: application/json'

Ключовете могат да бъдат ограничени по dataset, source, environment и export capability. Ротирайте компрометиран ключ и не го записвайте в logs.

Ресурси и endpoints

Всички paths са спрямо reserved early-access base URL. Точният активен URL се предоставя с credentials.

GET/coverage

Договореното покритие и freshness за всеки source.

GET/odds/current

Последният наличен quote за всяка селекция.

GET/odds/changes

Подредени price, line, availability и status промени.

GET/odds/summaries

Opening, closing, high/low и movement metrics.

GET/markets/lifecycle

Market appearance, suspension, reopen, line move и disappearance.

GET/mappings

Версионирани canonical event, market и outcome mappings.

GET/decisions

Пълен audit на приети, отхвърлени и review value решения.

GET/bets/summary

Агрегати с отделни recommendation, paper и placed counts.

GET/bets

Cursor-paginated списък на всички достъпни bet записи.

GET/bets/{bet_id}

Един bet запис по стабилен FavouriteOdds ID.

GET/bets/{bet_id}/history

Audit trail на статус, цена и settlement промени.

GET/results

Последни резултати, player statistics, void/correction и provenance.

POST/exports

Създава асинхронен export job за голям dataset.

GET/exports/{export_id}

Статус, manifest и краткотраен download URL.

Филтри и cursor pagination

Филтрирайте с повтарящи се source_id, sport, league_id, event_id, market_type, market_scope, odds_phase, status и RFC 3339 UTC timestamps. Не смесвайте pre-match и live data: задавайте odds_phase изрично при анализ.

Cursor-ът е opaque: пазете и връщайте стойността без промяна.
Продължете, докато page.has_more стане false.
При 410 започнете нов snapshot или incremental window според use case-а.
Използвайте /exports за целия dataset, вместо огромен page size.

Ключови полета и семантика

Decimal odds са numbers, валутните стойности са decimal strings, а времето е UTC RFC 3339. Source IDs и оригиналните labels се запазват за audit.

{
  "data": [{
    "quote_id": "oq_01K2...",
    "source_id": "bookmaker_source",
    "event_id": "evt_01K2...",
    "market_type": "player_points",
    "market_scope": "player_prop",
    "period": "full_event",
    "player": { "name": "Source player label" },
    "line": "22.5",
    "outcome": "over",
    "decimal_odds": 1.91,
    "odds_phase": "pre_match",
    "observed_at": "2026-08-02T12:34:56Z"
  }],
  "page": { "next_cursor": "opaque_value", "has_more": true }
}

coverage_scope

full_market, selected_markets, player_props_only или unavailable. Betano soccer и tennis са selected_markets; soccer включва валидираната player-prop история от Players response. Обикновените match markets в същия response не се представят като player props. Стар или quality-rejected soccer snapshot се архивира, но не се връща като current по подразбиране.

Bet counts

recommendation_count включва всички оценени решения; paper_bet_count и placed_bet_count са отделни. Placed включва само записи с реален placement статус.

Market identity

Event, market type, period, player, line и outcome са част от identity. Line или period промяна създава различен market context, а не безусловен overwrite.

Пълен export на odds или bets

За пълния договорен online range или всички bet записи създайте export job. data/v1 връща gzip-компресиран NDJSON; дългосрочният Parquet архив, CSV и custom delivery са достъпни по договорка.

1
POST /exports с dataset и filters; изпратете Idempotency-Key при safe retry.
2
Запазете export_id и poll-вайте GET /exports/{export_id}.
3
При ready сравнете row_count и SHA-256 на uncompressed NDJSON от manifest-а.
4
Изтеглете краткотрайния Bearer-защитен URL; не го споделяйте или кеширайте публично.

Грешки и retries

Грешките следват application/problem+json и включват request_id за support.

400Невалиден filter или несъвместими параметри

Поправете заявката; не retry-вайте без промяна.

401 / 403Липсващ ключ или scope

Проверете secret storage и договорения access.

409Source/market coverage не е наличен

Прочетете /coverage или поискайте custom feed.

410Cursor или download URL е изтекъл

Създайте нов cursor/export.

429Rate limit

Спазете Retry-After и exponential backoff с jitter.

5xxВременна service грешка

Retry с ограничен exponential backoff; пазете request_id.

Документация за AI agents

Agent-ите трябва да използват OpenAPI файла като точен contract, а краткия plain-text guide — за operational правила и безопасна pagination логика.

OpenAPI 3.1 JSON

Endpoints, parameters, auth, examples и JSON schemas за tool generation.

AI agent guide

Кратки invariants, retry правила, export workflow и забранени действия.

Нуждаете се от различен source, schema или delivery model?

Изпратете use case, пазари, честота и формат. Ще върнем sample payload и честен coverage manifest.

Обсъдете интеграция