iddaai-be/mds/API_RESPONSE_SCHEMA.md

V20+ API Response Schema

Bu doküman POST /v20plus/analyze/{match_id} endpointinin döndürdüğü JSON yapısını açıklar.

1) Root Schema

Key	Type	Açıklama
model_version	string	Model/pipeline sürümü.
match_info	object	Maç kimlik ve temel bilgileri.
data_quality	object	Veri kalitesi etiketi, skoru ve eksik flag'ler.
risk	object	Risk seviyesi, risk skoru ve sürpriz sinyalleri.
engine_breakdown	object	Team/Player/Odds/Referee confidence kırılımı.
main_pick	object | null	Ana önerilen garanti market satırı.
value_pick	object | null	Oranı 1.60 ve üzeri olan değerli/sürpriz pick.
bet_advice	object	Genel oynanabilirlik kararı (playable, stake vb.).
bet_summary	array<object>	Tüm marketlerin kullanıcı dostu özet listesi.
supporting_picks	array<object>	Ana pick dışındaki destekleyici pickler.
aggressive_pick	object | null	Yüksek riskli fırsat pick'i (örn HT/FT).
scenario_top5	array<object>	En olası ilk 5 skor senaryosu.
score_prediction	object	FT/HT skor ve xG öngörüleri.
market_board	object	Market bazlı detay olasılık tablosu.
reasoning_factors	array<string>	Karar etiketleri/gerekçeler.

2) match_info

Key	Type
match_id	string
match_name	string
home_team	string
away_team	string
league	string
match_date_ms	number

3) data_quality

Key	Type	Not
label	"HIGH" | "MEDIUM" | "LOW"	Kalite etiketi
score	number	0-1 arası normalize skor
home_lineup_count	number	Home XI oyuncu sayısı
away_lineup_count	number	Away XI oyuncu sayısı
flags	array<string>	Örn: lineup_incomplete, missing_referee

4) risk

Key	Type
level	"LOW" | "MEDIUM" | "HIGH" | "EXTREME"
score	number
is_surprise_risk	boolean
surprise_type	string | null
warnings	array<string>

5) Pick Satırı Şeması (main_pick, supporting_picks[])

Key	Type	Açıklama
market	string	Örn: MS, OU25, BTTS
pick	string	Öneri metni
probability	number	Model olasılığı (0-1)
confidence	number	Ham confidence (%)
odds	number | null	Seçimin oranı
raw_confidence	number	Kalibrasyon öncesi confidence
calibrated_confidence	number	Kalibrasyon sonrası confidence
min_required_confidence	number	O market için minimum eşik
edge	number	Model olasılığı - implied probability
play_score	number	Nihai oynanabilirlik puanı (0-100)
playable	boolean	Oynanmalı mı?
bet_grade	"A" | "B" | "C" | "PASS"	Kullanıcı aksiyon notu
stake_units	number	Önerilen stake birimi
decision_reasons	array<string>	Kural bazlı karar nedenleri

6) bet_advice

Key	Type
playable	boolean
suggested_stake_units	number
reason	string

7) bet_summary[]

Kullanıcıya sade gösterim için üretilen satırlar.

Key	Type
market	string
pick	string
raw_confidence	number
calibrated_confidence	number
bet_grade	"A" | "B" | "C" | "PASS"
playable	boolean
stake_units	number
play_score	number
reasons	array<string>

8) score_prediction

Key	Type
ft	string
ht	string
xg_home	number
xg_away	number
xg_total	number

9) scenario_top5[]

Key	Type
score	string
prob	number

10) market_board

Market detayları:

• MS, DC, OU15, OU25, OU35, BTTS, HT:
  • pick: string
  • confidence: number
  • probs: object
• HTFT:
  • probs: { "1/1": number, "1/X": number, ... }

11) Minimal Örnek

{
  "model_version": "v20plus.1",
  "match_info": {
    "match_id": "abc123",
    "match_name": "Team A vs Team B",
    "home_team": "Team A",
    "away_team": "Team B",
    "league": "League",
    "match_date_ms": 1771207200000
  },
  "main_pick": {
    "market": "OU15",
    "pick": "Üst 1.5",
    "probability": 0.74,
    "confidence": 66.5,
    "raw_confidence": 66.5,
    "calibrated_confidence": 59.9,
    "min_required_confidence": 60.0,
    "edge": 0.08,
    "play_score": 63.0,
    "playable": true,
    "bet_grade": "B",
    "stake_units": 0.5,
    "decision_reasons": ["market_passed_all_gates"]
  },
  "bet_advice": {
    "playable": true,
    "suggested_stake_units": 0.5,
    "reason": "playable_pick_found"
  },
  "bet_summary": []
}