ASOasis - All about Tech ASOasis
Contact
AI

AI Sports Analytics API Tutorial: From Live Win Probability to Player Projections

Build an end‑to‑end AI sports analytics API: real-time win probability, player projections, streaming, training, evaluation, and deployment.

ASOasis
6 min read
AI Sports Analytics API Tutorial: From Live Win Probability to Player Projections

Image used for representation purposes only.

Overview

AI has transformed sports analytics from post-game summaries into real-time, decision-grade insights. In this tutorial, you’ll build an end‑to‑end AI sports analytics API workflow that powers two concrete use cases:

  • Live in-game win probability
  • Player performance projections (e.g., points, shots, workloads)

You’ll learn how to fetch data, engineer features, call prediction endpoints, stream live events, evaluate model quality, and ship a production-grade microservice with caching, monitoring, and security.

What You’ll Build

  • A minimal service that exposes two endpoints: /win-probability and /player-projection
  • Batch and real-time pipelines powered by a generic AI sports analytics API
  • An evaluation harness with Brier score, log loss, and calibration checks

Prerequisites

  • Comfortable with Python or JavaScript/TypeScript
  • An API key from your analytics provider (exported as SPORTS_AI_API_KEY)
  • Basic familiarity with REST and WebSockets
  • Data licensing that permits predictive modeling and downstream use

Reference Architecture

  • Data ingest: historical schedules, play-by-play, box scores
  • Feature layer: rolling team/player stats, context (venue, rest days, injuries)
  • Model layer: hosted models for win probability and player projections
  • Serving layer: Flask/Express microservice with caching and rate limiting
  • Monitoring: request success, latency, prediction drift, calibration

Data Model (Example)

You can map your provider’s schema to a normalized shape like below.

{
  "game": {
    "game_id": "2025-10-18-LAL-DEN",
    "league": "NBA",
    "season": 2025,
    "home_team": "DEN",
    "away_team": "LAL",
    "start_time_utc": "2025-10-18T01:00:00Z",
    "status": "in_progress",
    "score": {"DEN": 78, "LAL": 74},
    "clock": {"period": 3, "time_remaining": "02:15"}
  },
  "players": [
    {"player_id": "2544", "team": "LAL", "pos": "F", "minutes": 26, "pts": 22, "shots": 14},
    {"player_id": "201142", "team": "DEN", "pos": "C", "minutes": 25, "pts": 18, "shots": 10}
  ],
  "plays": [
    {"ts": "2025-10-18T02:22:11Z", "event": "made_shot", "team": "DEN", "value": 2},
    {"ts": "2025-10-18T02:22:45Z", "event": "turnover", "team": "LAL"}
  ]
}

Getting Set Up

Export your API key and choose an endpoint base URL from your provider.

export SPORTS_AI_API_KEY="sk_live_xxx"
export SPORTS_AI_BASE_URL="https://api.sportsai.example.com/v1"

Install dependencies.

# Python
pip install requests websockets pandas scikit-learn

# Node
npm i axios ws express pino

First Call: Health Check and Metadata

Verify connectivity and inspect available models.

curl -H "Authorization: Bearer $SPORTS_AI_API_KEY" \
  "$SPORTS_AI_BASE_URL/models"

Example response:

{
  "models": [
    {"id": "win-probability-v3", "task": "binary_prob", "sport": "basketball", "features": ["score_diff","time_remaining","possession","elo"]},
    {"id": "player-points-v2", "task": "regression", "sport": "basketball"}
  ]
}

Predict Win Probability (Batch)

You can request predictions with a minimal feature set. Most providers compute advanced features server-side.

curl -X POST "$SPORTS_AI_BASE_URL/predict" \
  -H "Authorization: Bearer $SPORTS_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "win-probability-v3",
    "records": [
      {
        "game_id": "2025-10-18-LAL-DEN",
        "home_team": "DEN",
        "away_team": "LAL",
        "score_home": 78,
        "score_away": 74,
        "period": 3,
        "time_remaining_sec": 135,
        "possession": "DEN"
      }
    ]
  }'

Response:

{
  "predictions": [
    {
      "game_id": "2025-10-18-LAL-DEN",
      "home_win_prob": 0.64,
      "confidence": 0.87,
      "explanations": {"score_diff": 0.31, "time_remaining": 0.22, "possession": 0.11}
    }
  ]
}

Python Helper

import os, requests
BASE = os.environ["SPORTS_AI_BASE_URL"]
HEADERS = {"Authorization": f"Bearer {os.environ['SPORTS_AI_API_KEY']}"}

def win_prob(game):
    payload = {
        "model_id": "win-probability-v3",
        "records": [game]
    }
    r = requests.post(f"{BASE}/predict", json=payload, headers=HEADERS, timeout=10)
    r.raise_for_status()
    return r.json()["predictions"][0]

example = {
    "game_id": "2025-10-18-LAL-DEN",
    "home_team": "DEN",
    "away_team": "LAL",
    "score_home": 78,
    "score_away": 74,
    "period": 3,
    "time_remaining_sec": 135,
    "possession": "DEN"
}
print(win_prob(example))

Real-Time Streaming (WebSocket)

Subscribe to live events and request updated probabilities each tick.

import asyncio, json, websockets, time, requests, os
BASE = os.environ["SPORTS_AI_BASE_URL"]
WS = BASE.replace("https://", "wss://") + "/stream/games/2025-10-18-LAL-DEN"
HEADERS = {"Authorization": f"Bearer {os.environ['SPORTS_AI_API_KEY']}"}

def predict_tick(state):
    payload = {"model_id": "win-probability-v3", "records": [state]}
    r = requests.post(f"{BASE}/predict", json=payload, headers=HEADERS, timeout=5)
    r.raise_for_status()
    return r.json()["predictions"][0]

async def main():
    async with websockets.connect(WS, extra_headers=HEADERS) as ws:
        async for msg in ws:
            event = json.loads(msg)
            state = event["game_state"]  # provider-normalized state
            pred = predict_tick(state)
            print({"t": time.time(), "home_win_prob": pred["home_win_prob"]})

asyncio.run(main())

Player Projections

Request per-player forecasts for points or workload.

curl -X POST "$SPORTS_AI_BASE_URL/predict" \
  -H "Authorization: Bearer $SPORTS_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "player-points-v2",
    "records": [
      {"player_id": "2544", "opponent": "DEN", "minutes_proj": 33, "pace_adj": 1.03}
    ]
  }'

Response:

{"predictions": [{"player_id": "2544", "points_mean": 26.4, "p90": 34.1, "p10": 18.2}]}

Feature Engineering via API

Many providers expose feature helpers.

curl -X POST "$SPORTS_AI_BASE_URL/features/rolling" \
  -H "Authorization: Bearer $SPORTS_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "team",
    "keys": ["DEN"],
    "target_features": ["off_rating","def_rating","rebound_rate"],
    "window": 10,
    "include_playoffs": false
  }'

Response includes normalized rolling averages and z-scores you can feed to prediction endpoints.

Training a Custom Model

If the off‑the‑shelf model doesn’t fit your league or metric, train a custom one.

curl -X POST "$SPORTS_AI_BASE_URL/models" \
  -H "Authorization: Bearer $SPORTS_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "win-probability-my-league-v1",
    "task": "binary_prob",
    "dataset": {"table": "s3://my-bucket/winprob/training.parquet"},
    "target": "home_win",
    "time_column": "game_start",
    "eval_metric": "brier",
    "validation": {"method": "time_series_split", "folds": 5},
    "explainability": {"shap": true}
  }'

Poll for status, then use the returned model_id in /predict.

Evaluating Model Quality

Use objective metrics and calibration.

from sklearn.metrics import brier_score_loss, log_loss, roc_auc_score
import numpy as np

# y_true: 1 if home won, else 0; y_prob: model home_win_prob
brier = brier_score_loss(y_true, y_prob)
ll = log_loss(y_true, np.c_[1-np.array(y_prob), y_prob])
auc = roc_auc_score(y_true, y_prob)
print({"brier": brier, "log_loss": ll, "auc": auc})

For calibration, bin probabilities (e.g., 0.1 increments) and compare predicted to empirical outcomes. Poor calibration can be improved with isotonic or Platt scaling if your provider supports a /calibrate endpoint.

Explainability and Auditability

Request local feature attributions to build trust.

curl -X POST "$SPORTS_AI_BASE_URL/explain" \
  -H "Authorization: Bearer $SPORTS_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "win-probability-v3",
    "record": {"score_diff": 4, "time_remaining_sec": 135, "possession": "DEN"},
    "method": "shap"
  }'

Response highlights the drivers (e.g., score_diff, time context, possession). Log both inputs and outputs for audits.

Similar Plays via Embeddings

Find historical analogs to current game states.

curl -X POST "$SPORTS_AI_BASE_URL/embeddings/query" \
  -H "Authorization: Bearer $SPORTS_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "space": "basketball-plays-v1",
    "query": {"score_diff": 4, "time_remaining_sec": 135, "possession": "DEN"},
    "k": 5
  }'

Use nearest neighbors to enrich commentary or generate strategy insights.

Shipping a Microservice (Flask)

from flask import Flask, request, jsonify
import os, requests
app = Flask(__name__)
BASE = os.environ["SPORTS_AI_BASE_URL"]
HEADERS = {"Authorization": f"Bearer {os.environ['SPORTS_AI_API_KEY']}"}

@app.post('/win-probability')
def win_probability():
    body = request.get_json()
    r = requests.post(f"{BASE}/predict", json={"model_id":"win-probability-v3","records":[body]}, headers=HEADERS, timeout=5)
    return (r.text, r.status_code, {'Content-Type': 'application/json', 'Cache-Control': 'public, max-age=3'})

@app.post('/player-projection')
def player_projection():
    body = request.get_json()
    r = requests.post(f"{BASE}/predict", json={"model_id":"player-points-v2","records":[body]}, headers=HEADERS, timeout=5)
    return (r.text, r.status_code, {'Content-Type': 'application/json', 'Cache-Control': 'public, max-age=60'})

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)

Rate Limits, Retries, and Caching

  • Respect 429s. Back off exponentially and honor Retry-After.
  • Apply short-lived caching to live predictions (e.g., 1–5 seconds) to smooth spikes.
  • Use ETags/If-None-Match for static metadata (teams, rosters).

Example error response to handle:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "retry_after": 2.0
  }
}

Data Quality and Drift

  • Validate inputs: bounds (0–48 minutes), monotonic clocks, consistent team IDs
  • Monitor feature distributions over time; alert when KL divergence exceeds threshold
  • Recalibrate models each season and post-trade-deadline

Privacy, Ethics, and Compliance

  • Comply with league/team data use policies and vendor terms
  • Avoid sensitive attributes in modeling; audit for proxy bias
  • Provide opt-out pathways if using wearable or tracking data
  • Log minimal PII; encrypt at rest and in transit

Cost Awareness

  • Estimate cost as: requests_per_game × price_per_request × games
  • Cache, batch records, and prefer vectorized endpoints to reduce spend

Testing

  • Golden files: fixed inputs with frozen outputs for regression tests
  • Chaos tests: simulate dropped events, clock jumps, and late data
  • Backtest: time-split evaluation across seasons to ensure generalization

Deployment Checklist

  • Health endpoints and readiness probes
  • Observability: latency, error rate, throughput, tail percentiles
  • Model monitoring: calibration and drift dashboards
  • Key rotation and scoped tokens
  • Runbooks and on-call alerts

Next Steps

  • Add sport-specific features (xG for soccer, EPA for football, RAPM features for basketball)
  • Integrate embeddings to power “similar game” storytelling
  • Introduce reinforcement learning for strategy simulation in off‑ball scenarios
  • Automate seasonal retraining with CI/CD pipelines

Wrap-Up

You now have a complete blueprint: ingest data, engineer features, call AI models, stream live updates, evaluate rigorously, and serve predictions reliably. With clear interfaces and sound MLOps, your AI sports analytics API can move from a demo to a trusted tool for broadcasts, betting risk controls, front offices, or fan apps.

Tags

machine-learning sports api python javascript predictive-analytics real-time mlops

Related Posts