Sports Odds API for Python Models

import os
import time
from datetime import datetime, timezone

import pandas as pd
import requests

BASE_URL = os.getenv("ODDS_API_BASE_URL", "https://api.odds-api.net/v1").rstrip("/")
HEADERS = {"X-API-Key": os.environ["ODDS_API_KEY"]}
MAX_AGE_SECONDS = 120


def get_json(path, **params):
    response = requests.get(
        f"{BASE_URL}{path}",
        headers=HEADERS,
        params=params,
        timeout=20,
    )
    response.raise_for_status()
    return response.json()


now_s = int(time.time())
events = get_json(
    "/events",
    sport="american football",
    league="NFL",
    start_from=now_s,
    start_to=now_s + 7 * 24 * 60 * 60,
    limit=25,
)
event = next(
    item for item in events["items"]
    if item.get("home_team") and item.get("away_team")
)

snapshot = get_json(
    f"/events/{event['event_id']}/odds/snapshot",
    bookmakers="pinnacle,draftkings,fanduel",
    market_keys="moneyline,handicap,total",
    periods="full time",
    price_fields="odds,fair",
    include_unavailable="true",
    limit=2000,
)

# Snapshot and per-bookmaker timing fields are in the public contract.
snapshot_as_of = snapshot.get("as_of_ts_ms")
snapshot_capture = snapshot.get("snapshot_capture_ts_ms", snapshot_as_of)
bookmaker_as_of = snapshot.get("bookmaker_as_of_ts_ms") or {}
oldest_bookmaker_as_of = snapshot.get("oldest_bookmaker_as_of_ts_ms")

rows = []
for item in snapshot.get("items", []):
    rows.append({
        "event_id": snapshot["event_id"],
        "home_team": event["home_team"],
        "away_team": event["away_team"],
        "bookmaker": item.get("bookmaker"),
        "market_key": item.get("market_key"),
        "bet_type": item.get("bet_type"),
        "metric": item.get("metric"),
        "period": item.get("period"),
        "line": item.get("line"),
        "side": item.get("side"),
        "selection_key": item.get("selection_key"),
        "odds": item.get("odds"),
        "fair_odds": item.get("fair_odds"),
        "is_available": item.get("is_available", True),
        "as_of_ts_ms": snapshot_as_of,
        "snapshot_capture_ts_ms": snapshot_capture,
        "bookmaker_as_of_ts_ms": bookmaker_as_of.get(item.get("bookmaker")),
        "oldest_bookmaker_as_of_ts_ms": oldest_bookmaker_as_of,
        "target_refresh_interval_seconds": snapshot.get("target_refresh_interval_seconds"),
        "ttl_seconds": snapshot.get("ttl_seconds"),
        "resume": snapshot.get("resume"),
        "next_cursor": snapshot.get("next_cursor"),
    })

model_rows = pd.DataFrame(rows)
if model_rows.empty:
    raise RuntimeError("No odds rows returned for the selected event and filters")

now_ms = int(datetime.now(timezone.utc).timestamp() * 1000)
source_time = pd.to_numeric(model_rows["bookmaker_as_of_ts_ms"], errors="coerce")
snapshot_time = pd.to_numeric(model_rows["as_of_ts_ms"], errors="coerce")
model_rows["freshness_basis_ts_ms"] = source_time.fillna(snapshot_time)
model_rows["row_age_seconds"] = (now_ms - model_rows["freshness_basis_ts_ms"]) / 1000

usable = model_rows[
    model_rows["is_available"].eq(True)
    & model_rows["odds"].notna()
    & model_rows["selection_key"].notna()
    & model_rows["row_age_seconds"].le(MAX_AGE_SECONDS)
].copy()

comparison_key = [
    "event_id", "market_key", "bet_type", "metric",
    "period", "line", "side", "selection_key",
]
best_prices = (
    usable.sort_values("odds", ascending=False)
    .groupby(comparison_key, dropna=False, as_index=False)
    .first()
)

print(best_prices[
    comparison_key + ["bookmaker", "odds", "fair_odds", "row_age_seconds"]
].to_string(index=False))
print("resume:", snapshot["resume"])

import pandas as pd
import requests

payload = requests.get(
    "https://api.odds-api.net/v1/coverage",
    timeout=30,
).json()
rows = pd.DataFrame(payload["markets"])
as_of = pd.Timestamp(payload["as_of"])
rows["last_seen_at"] = pd.to_datetime(rows["last_seen_at"], utc=True)
rows["last_seen_age_hours"] = (as_of - rows["last_seen_at"]).dt.total_seconds() / 3600
rows["within_1h"] = rows["last_seen_age_hours"].le(1)
rows["within_24h"] = rows["last_seen_age_hours"].le(24)

shape_fields = ["bet_type", "metric", "period"]
rows["market_shape"] = rows[shape_fields].fillna("").astype(str).agg("|".join, axis=1)

recent = rows[rows["within_24h"]]
league_readiness = (
    recent.groupby("league", dropna=False)
    .agg(
        bookmakers_24h=("bookmaker", "nunique"),
        market_shapes_24h=("market_shape", "nunique"),
        latest_observation=("last_seen_at", "max"),
    )
    .sort_values("bookmakers_24h", ascending=False)
)

print({
    "coverage_snapshot": payload["as_of"],
    "one_hour_observation_rate": round(rows["within_1h"].mean() * 100, 1),
    "twenty_four_hour_observation_rate": round(rows["within_24h"].mean() * 100, 1),
})
print(league_readiness.head(20).to_string())