Live sports scores in Python

Terminal

export REALTIME_SPORTS_API_KEY=your_key
curl -H "Authorization: Bearer $REALTIME_SPORTS_API_KEY" \
  "https://www.realtimesportsapi.com/api/v1/sports/football/leagues/nfl/events/live"

Terminal

git clone https://github.com/ElcoDevRepos/realtime-sports-api-examples
cd realtime-sports-api-examples/python

Terminal

python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt

python/rsa_common.py

"""Shared helpers for the Python examples (uses `requests`)."""
from __future__ import annotations

import os
import sys
from pathlib import Path
from typing import Any, Dict, Optional

import requests

API_BASE = os.environ.get("RSA_API_BASE", "https://www.realtimesportsapi.com/api/v1")

# Load ../.env (KEY=value lines) if present; variables already in the environment win.
_env = Path(__file__).resolve().parent.parent / ".env"
if _env.exists():
    for line in _env.read_text().splitlines():
        line = line.strip()
        if line and not line.startswith("#") and "=" in line:
            k, v = line.split("=", 1)
            os.environ.setdefault(k.strip(), v.strip().strip("'\""))


class ApiError(Exception):
    def __init__(self, status: int, body: Optional[Dict[str, Any]], retry_after: Optional[str]):
        err = (body or {}).get("error") or {}
        self.status = status
        self.code = err.get("code")
        self.hint = err.get("hint")
        self.retry_after = retry_after
        super().__init__(f"HTTP {status} {self.code or ''}: {err.get('message', 'request failed')}")


def require_key() -> str:
    key = os.environ.get("REALTIME_SPORTS_API_KEY", "").strip()
    if not key or key == "your_api_key_here":
        sys.exit(
            "Set REALTIME_SPORTS_API_KEY first (export it, or copy .env.example to .env).\n"
            "Get a free key at https://www.realtimesportsapi.com/signup"
        )
    return key


def api_get(path: str, **query: Any) -> Dict[str, Any]:
    """GET a path under /api/v1 and return the envelope {success, data, meta}. Raises ApiError on non-2xx."""
    key = require_key()
    params = {k: v for k, v in query.items() if v is not None}
    res = requests.get(API_BASE + path, params=params, headers={"Authorization": f"Bearer {key}"}, timeout=30)
    try:
        body = res.json()
    except ValueError:
        body = None
    if not res.ok:
        raise ApiError(res.status_code, body, res.headers.get("Retry-After"))
    return body


def format_game(g: Dict[str, Any]) -> str:
    """One-line score: 'KC 14 @ BAL 10  5:23 - 2nd Quarter  [eventId]'"""
    a, h = g.get("awayTeam") or {}, g.get("homeTeam") or {}

    def side(t: Dict[str, Any]) -> str:
        name = t.get("abbreviation") or t.get("name") or "?"
        return name if t.get("score") is None else f"{name} {t['score']}"

    return f"{side(a)} @ {side(h)}  {(g.get('status') or {}).get('detail', '')}  [{g.get('id')}]"


def run(main) -> None:
    """Run main() and print API errors cleanly instead of a traceback."""
    try:
        main()
    except ApiError as e:
        print(e, file=sys.stderr)
        if e.hint:
            print(f"Hint: {e.hint}", file=sys.stderr)
        if e.status == 429:
            print(f"Monthly quota exhausted. Retry after {e.retry_after or '?'} s or upgrade.", file=sys.stderr)
        sys.exit(1)
    except requests.RequestException as e:
        sys.exit(f"Network error: {e}")

python/live_scores.py

"""Games in progress right now for one league.

Usage: python live_scores.py [sport] [league]
  python live_scores.py football nfl
  python live_scores.py soccer eng.1    # soccer is "soccer"; "football" is American football
"""
import sys

from rsa_common import api_get, format_game, run


def main() -> None:
    sport = sys.argv[1] if len(sys.argv) > 1 else "football"
    league = sys.argv[2] if len(sys.argv) > 2 else "nfl"
    body = api_get(f"/sports/{sport}/leagues/{league}/events/live")
    games = body.get("data") or []
    if not games:
        print(f"No {league} games live right now.")
    for g in games:
        print(format_game(g))
    remaining = ((body.get("meta") or {}).get("rateLimit") or {}).get("remaining")
    if remaining is not None:
        print(f"\nCalls remaining this month: {remaining}")


if __name__ == "__main__":
    run(main)

python/schedule.py

"""Season schedule. NFL and college football also take a week.

Usage: python schedule.py [sport] [league] [season] [week] [seasonType]
  python schedule.py football nfl 2026 5 2    # 2026 regular season, week 5
  python schedule.py hockey nhl 2026
"""
import sys

from rsa_common import api_get, format_game, run


def main() -> None:
    args = sys.argv[1:] + [None] * 5
    sport, league, season = args[0] or "football", args[1] or "nfl", args[2] or "2026"
    week, season_type = args[3], args[4] or "2"
    body = api_get(f"/sports/{sport}/leagues/{league}/seasons/{season}/schedule", week=week, seasonType=season_type)
    games = body.get("data") or []
    for g in games:
        print(f"{g.get('date', '')}  {format_game(g)}")
    print(f"\n{len(games)} games")


if __name__ == "__main__":
    run(main)

python/event_details.py

"""One game: details, box score and the latest plays (3 API calls).

Usage: python event_details.py <sport> <league> <eventId>
Find event ids with live_scores.py (printed in [brackets]).
"""
import sys

from rsa_common import api_get, format_game, run


def main() -> None:
    if len(sys.argv) < 4:
        sys.exit("Usage: python event_details.py <sport> <league> <eventId>   (e.g. football nfl 401772982)")
    sport, league, event_id = sys.argv[1:4]
    base = f"/sports/{sport}/leagues/{league}/events/{event_id}"
    print(format_game(api_get(base)["data"]))
    box = api_get(f"{base}/boxscore")["data"] or {}
    print("\nBox score keys:", ", ".join(box.keys()))
    plays = api_get(f"{base}/plays", limit=10)["data"] or []
    print("\nPlays:")
    for p in plays:
        print(" -", p.get("text") or " ".join(x for x in [(p.get("type") or {}).get("text") or "Play", (p.get("clock") or {}).get("displayValue")] if x))


if __name__ == "__main__":
    run(main)

Terminal

python live_scores.py hockey nhl
python schedule.py football nfl 2026 9
python event_details.py soccer eng.1 401879242
python watch.py basketball nba 30

python/watch.py

"""Poll the live endpoint and print only what changed: score, clock/period, final.

Usage: python watch.py [sport] [league] [seconds]
  python watch.py basketball nba 30

Every poll is one API call: a 3-hour game polled every 30 s is about 360 calls.
Data is typically 20-30 seconds behind live play; not for in-play betting.
"""
import sys
import time
from datetime import datetime

from rsa_common import api_get, format_game, run


def main() -> None:
    sport = sys.argv[1] if len(sys.argv) > 1 else "football"
    league = sys.argv[2] if len(sys.argv) > 2 else "nfl"
    seconds = int(sys.argv[3]) if len(sys.argv) > 3 else 30
    last: dict = {}  # event id -> last line printed
    while True:
        games = api_get(f"/sports/{sport}/leagues/{league}/events/live").get("data") or []
        for g in games:
            line = format_game(g)
            if last.get(g["id"]) != line:
                print(f"{datetime.now():%H:%M:%S}  {line}", flush=True)
                last[g["id"]] = line
        if not games and not last:
            print(f"No {league} games live right now.", flush=True)
        time.sleep(seconds)


if __name__ == "__main__":
    run(main)