⚾ Baseball with sportsdataverse-py
Welcome to the ballpark! 🏟️ In just a few lines of Python you're about to pull official MLB data — schedules, standings, rosters, box scores, play-by-play — straight from the league's own MLB Stats API, plus pitch-level Statcast tracking from Baseball Savant. Every premium call hands you back a tidy polars DataFrame (or raw JSON when you want it), ready to model. 🚀
If you've used the R package baseballr, or Python's pybaseball, the data shapes will feel right at home. Let's play ball! ⚾
🧰 The toolbox
We lead with the premium sources — the MLB Stats API (mlb_*,
backed by statsapi.mlb.com) and the comprehensive Statcast surface
(mlb_statcast_*, from Baseball
Savant). ESPN (espn_mlb_*) is a handy secondary path. Click any name for the
full reference:
| Function | What it gives you | Source |
|---|---|---|
mlb_schedule · parse_mlb_api_schedule | Games for a date / range — one row per game (with game_pk) | 🟢 MLB Stats API |
mlb_teams · parse_mlb_api_teams | Every club — one row per team | 🟢 MLB Stats API |
mlb_standings · parse_mlb_api_standings | Division standings — wins, losses, run diff | 🟢 MLB Stats API |
mlb_team_roster | A team's roster — one row per player | 🟢 MLB Stats API |
mlb_person | A player's bio (one tidy row) | 🟢 MLB Stats API |
mlb_person_stats · parse_mlb_api_person_stats | A player's season stat splits | 🟢 MLB Stats API |
mlb_boxscore | Full game box score | 🟢 MLB Stats API |
mlb_play_by_play | Plate-appearance-level play-by-play | 🟢 MLB Stats API |
mlb_stats_leaders | League leaders for any stat (HR, AVG, ERA, …) | 🟢 MLB Stats API |
mlb_win_probability | Per-play win probability + WPA for a game | 🟢 MLB Stats API |
mlb_awards · mlb_award_recipients | Award catalog + season winners (MVP, Cy Young, …) | 🟢 MLB Stats API |
mlb_draft | Amateur draft board — one row per pick | 🟢 MLB Stats API |
mlb_statcast_search | Every pitch matching a filter — ~110 cols/pitch; auto date-chunks past the 25k cap; friendly filters (batters_lookup, pitch_type, at_bat_result, …) | 🔵 Statcast |
mlb_statcast_search_minors · mlb_statcast_search_wbc | Same pitch search for MiLB and the World Baseball Classic | 🔵 Statcast |
mlb_statcast_leaderboard_* (37 of them) — e.g. …_sprint_speed, …_expected_stats, …_bat_tracking, …_outs_above_average | Every Savant leaderboard: expected stats, sprint speed, bat tracking, pitch arsenals/movement/tempo, OAA, arm strength, catcher framing/blocking/throwing, baserunning, park factors, … | 🔵 Statcast |
mlb_statcast_gamefeed | Savant single-game feed — one tidy row per pitch | 🔵 Statcast |
mlb_statcast_player | A player's Savant page metrics | 🔵 Statcast |
espn_mlb_teams · espn_mlb_schedule | ESPN teams / schedule (wide frames) | ⚪ ESPN |
most_recent_mlb_season | Current season helper | ⚪ helper |
🔌 Setup
pip install sportsdataverse
No API key needed for any of the premium MLB endpoints — the MLB Stats API and Baseball Savant are both public. 🎉
import polars as pl
import sportsdataverse.mlb as mlb
pl.Config.set_tbl_rows(12)
print("most recent MLB season:", mlb.most_recent_mlb_season())
most recent MLB season: 2026
The MLB Stats API and Savant are public and reliable, but they're still
live network calls — a date with no games, an offseason day, or a blip can
make a call come back empty. So we use a tiny safe() helper: you get the
frame when the feed is up, and a friendly one-liner when it isn't (never a
scary traceback). 🛟
We also pick a stable completed-season date for our examples so the page renders the same in June as in October.
def safe(label, thunk):
"""Run a live call defensively: return its result, or print a one-liner."""
try:
out = thunk()
print(f"✅ {label}")
return out
except Exception as e: # noqa: BLE001 -- demo resilience
print(f"⏭️ {label}: unavailable right now ({type(e).__name__})")
return None
# A known completed regular-season slate — stable for the docs build.
SAMPLE_SEASON = 2024
SAMPLE_DATE = "2024-07-01" # YYYY-MM-DD for the Stats API
JUDGE_ID = 592450 # Aaron Judge, NYY — our running example player
YANKEES_ID = 147 # New York Yankees team_id
📅 The schedule (MLB Stats API)
mlb_schedule returns the
raw JSON dict; its partner
parse_mlb_api_schedule
flattens it to one row per game. The most important column is game_pk —
that's the id you feed to the box score and play-by-play endpoints. Pass a
single date=, or a start_date/end_date range, team_id, or season.
schedule = safe(
"schedule",
lambda: mlb.parse_mlb_api_schedule(mlb.mlb_schedule(date=SAMPLE_DATE)),
)
cols = ["game_pk", "status_detailed_state",
"teams_away_team_name", "teams_away_score",
"teams_home_team_name", "teams_home_score"]
(schedule.select([c for c in cols if c in schedule.columns]).head()
if schedule is not None else "schedule unavailable right now")
✅ schedule
shape: (3, 6)
┌─────────┬─────────────────┬─────────────────┬─────────────────┬─────────────────┬────────────────┐
│ game_pk ┆ status_detailed ┆ teams_away_team ┆ teams_away_scor ┆ teams_home_team ┆ teams_home_sco │
│ --- ┆ _state ┆ _name ┆ e ┆ _name ┆ re │
│ i64 ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ ┆ str ┆ str ┆ i64 ┆ str ┆ i64 │
╞═════════╪═════════════════╪═════════════════╪═════════════════╪═════════════════╪════════════════╡
│ 744914 ┆ Final ┆ Houston Astros ┆ 3 ┆ Toronto Blue ┆ 1 │
│ ┆ ┆ ┆ ┆ Jays ┆ │
│ 744840 ┆ Final ┆ New York Mets ┆ 9 ┆ Washington ┆ 7 │
│ ┆ ┆ ┆ ┆ Nationals ┆ │
│ 746535 ┆ Final ┆ Milwaukee ┆ 7 ┆ Colorado ┆ 8 │
│ ┆ ┆ Brewers ┆ ┆ Rockies ┆ │
└─────────┴─────────────────┴─────────────────┴─────────────────┴─────────────────┴────────────────┘
🏆 Standings (MLB Stats API)
mlb_standings covers
both leagues by default (league_id="103,104").
parse_mlb_api_standings
returns one row per team with wins/losses, division rank, and winning
percentage.
standings = safe(
"standings",
lambda: mlb.parse_mlb_api_standings(mlb.mlb_standings(season=SAMPLE_SEASON)),
)
keep = ["team_name", "standings_division_name", "wins", "losses",
"winning_percentage", "division_rank"]
(standings.select([c for c in keep if c in standings.columns])
.sort("wins", descending=True).head(10)
if standings is not None else "standings unavailable right now")
✅ standings
shape: (10, 6)
┌───────────┬─────────────────────────┬──────┬────────┬────────────────────┬───────────────┐
│ team_name ┆ standings_division_name ┆ wins ┆ losses ┆ winning_percentage ┆ division_rank │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ str ┆ i64 ┆ i64 ┆ str ┆ str │
╞═══════════╪═════════════════════════╪══════╪════════╪════════════════════╪═══════════════╡
│ Dodgers ┆ null ┆ 98 ┆ 64 ┆ .605 ┆ 1 │
│ Phillies ┆ null ┆ 95 ┆ 67 ┆ .586 ┆ 1 │
│ Yankees ┆ null ┆ 94 ┆ 68 ┆ .580 ┆ 1 │
│ Brewers ┆ null ┆ 93 ┆ 69 ┆ .574 ┆ 1 │
│ Padres ┆ null ┆ 93 ┆ 69 ┆ .574 ┆ 2 │
│ Guardians ┆ null ┆ 92 ┆ 69 ┆ .571 ┆ 1 │
│ Orioles ┆ null ┆ 91 ┆ 71 ┆ .562 ┆ 2 │
│ Braves ┆ null ┆ 89 ┆ 73 ┆ .549 ┆ 2 │
│ Mets ┆ null ┆ 89 ┆ 73 ┆ .549 ┆ 3 │
│ D-backs ┆ null ┆ 89 ┆ 73 ┆ .549 ┆ 3 │
└───────────┴─────────────────────────┴──────┴────────┴────────────────────┴───────────────┘
🧢 Teams & rosters (MLB Stats API)
mlb_teams +
parse_mlb_api_teams lists every
club — grab a team_id here.
mlb_team_roster then
returns a tidy frame directly (one row per player).
teams = safe(
"teams",
lambda: mlb.parse_mlb_api_teams(mlb.mlb_teams(season=SAMPLE_SEASON)),
)
(teams.select(["id", "name", "abbreviation", "location_name", "team_name"]).head()
if teams is not None else "teams unavailable right now")
✅ teams
shape: (5, 5)
┌─────┬──────────────────────┬──────────────┬───────────────┬───────────┐
│ id ┆ name ┆ abbreviation ┆ location_name ┆ team_name │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str ┆ str ┆ str │
╞═════╪══════════════════════╪══════════════╪═══════════════╪═══════════╡
│ 133 ┆ Oakland Athletics ┆ OAK ┆ Oakland ┆ Athletics │
│ 134 ┆ Pittsburgh Pirates ┆ PIT ┆ Pittsburgh ┆ Pirates │
│ 135 ┆ San Diego Padres ┆ SD ┆ San Diego ┆ Padres │
│ 136 ┆ Seattle Mariners ┆ SEA ┆ Seattle ┆ Mariners │
│ 137 ┆ San Francisco Giants ┆ SF ┆ San Francisco ┆ Giants │
└─────┴──────────────────────┴──────────────┴───────────────┴───────────┘
roster = safe(
"Yankees roster",
lambda: mlb.mlb_team_roster(team_id=YANKEES_ID, season=SAMPLE_SEASON),
)
rcols = ["jersey_number", "person_id", "person_full_name",
"position_abbreviation", "status_description"]
(roster.select([c for c in rcols if c in roster.columns]).head()
if roster is not None else "roster unavailable right now")
✅ Yankees roster
shape: (5, 5)
┌───────────────┬───────────┬──────────────────┬───────────────────────┬───────────────────────┐
│ jersey_number ┆ person_id ┆ person_full_name ┆ position_abbreviation ┆ status_description │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ str ┆ str ┆ str │
╞═══════════════╪═══════════╪══════════════════╪═══════════════════════╪═══════════════════════╡
│ 74 ┆ 677076 ┆ Clayton Andrews ┆ P ┆ Minor League Contract │
│ 85 ┆ 690925 ┆ Clayton Beeter ┆ P ┆ Forty Man │
│ 19 ┆ 542932 ┆ Jon Berti ┆ 3B ┆ Forty Man │
│ 53 ┆ 641360 ┆ Phil Bickford ┆ P ┆ Minor League Contract │
│ 57 ┆ 595897 ┆ Nick Burdi ┆ P ┆ Minor League Contract │
└───────────────┴───────────┴──────────────────┴───────────────────────┴───────────────────────┘
🧍 Player bio & season stats (MLB Stats API)
mlb_person returns a one-row
bio frame. mlb_person_stats
returns the raw stat-split dict;
parse_mlb_api_person_stats
flattens it. Our running example is Aaron Judge (person_id=592450).
bio = safe("Judge bio", lambda: mlb.mlb_person(person_id=JUDGE_ID))
bcols = ["id", "full_name", "primary_number", "birth_date",
"height", "weight", "mlb_debut_date"]
(bio.select([c for c in bcols if c in bio.columns])
if bio is not None else "bio unavailable right now")
✅ Judge bio
shape: (1, 7)
┌────────┬─────────────┬────────────────┬────────────┬────────┬────────┬────────────────┐
│ id ┆ full_name ┆ primary_number ┆ birth_date ┆ height ┆ weight ┆ mlb_debut_date │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str ┆ str ┆ str ┆ i64 ┆ str │
╞════════╪═════════════╪════════════════╪════════════╪════════╪════════╪════════════════╡
│ 592450 ┆ Aaron Judge ┆ 99 ┆ 1992-04-26 ┆ 6' 7" ┆ 282 ┆ 2016-08-13 │
└────────┴─────────────┴────────────────┴────────────┴────────┴────────┴────────────────┘
hitting = safe(
"Judge 2024 hitting",
lambda: mlb.parse_mlb_api_person_stats(
mlb.mlb_person_stats(person_id=JUDGE_ID, stats="season",
group="hitting", season=SAMPLE_SEASON)
),
)
scols = ["season", "stat_games_played", "stat_home_runs", "stat_rbi",
"stat_avg", "stat_obp", "stat_slg", "stat_ops"]
(hitting.select([c for c in scols if c in hitting.columns])
if hitting is not None else "stats unavailable right now")
✅ Judge 2024 hitting
shape: (1, 8)
┌────────┬─────────────────┬────────────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
│ season ┆ stat_games_play ┆ stat_home_runs ┆ stat_rbi ┆ stat_avg ┆ stat_obp ┆ stat_slg ┆ stat_ops │
│ --- ┆ ed ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ --- ┆ i64 ┆ i64 ┆ str ┆ str ┆ str ┆ str │
│ ┆ i64 ┆ ┆ ┆ ┆ ┆ ┆ │
╞════════╪═════════════════╪════════════════╪══════════╪══════════╪══════════╪══════════╪══════════╡
│ 2024 ┆ 158 ┆ 58 ┆ 144 ┆ .322 ┆ .458 ┆ .701 ┆ 1.159 │
└────────┴─────────────────┴────────────────┴──────────┴──────────┴──────────┴──────────┴──────────┘
🎯 Pitch-level Statcast (Baseball Savant)
Now the fun part — every single pitch.
mlb_statcast_search pulls each
pitch matching your filter, with 100+ columns (velocity, spin, launch angle,
expected stats). Keep windows small (one player, one game, or a 1–2 day
slice) — a full season is millions of pitches. Here's every pitch Aaron Judge
saw over a two-day window.
pitches = safe(
"Judge pitches (2-day)",
lambda: mlb.mlb_statcast_search(start_dt="2024-07-01", end_dt="2024-07-02",
batters_lookup=JUDGE_ID),
)
if pitches is not None and pitches.height:
print("shape:", pitches.shape)
out = pitches.select(["game_date", "player_name", "pitch_type", "release_speed",
"launch_speed", "launch_angle", "events", "description"]).head()
else:
out = "no pitches in that window right now"
out
✅ Judge pitches (2-day)
shape: (11, 119)
shape: (5, 8)
┌────────────┬────────────┬────────────┬───────────┬───────────┬───────────┬───────────┬───────────┐
│ game_date ┆ player_nam ┆ pitch_type ┆ release_s ┆ launch_sp ┆ launch_an ┆ events ┆ descripti │
│ --- ┆ e ┆ --- ┆ peed ┆ eed ┆ gle ┆ --- ┆ on │
│ str ┆ --- ┆ str ┆ --- ┆ --- ┆ --- ┆ str ┆ --- │
│ ┆ str ┆ ┆ f64 ┆ f64 ┆ f64 ┆ ┆ str │
╞════════════╪════════════╪════════════╪═══════════╪═══════════╪═══════════╪═══════════╪═══════════╡
│ 2024-07-02 ┆ Judge, ┆ FC ┆ 97.1 ┆ 91.0 ┆ 19.0 ┆ single ┆ hit_into_ │
│ ┆ Aaron ┆ ┆ ┆ ┆ ┆ ┆ play │
│ 2024-07-02 ┆ Judge, ┆ FC ┆ 97.2 ┆ null ┆ null ┆ null ┆ swinging_ │
│ ┆ Aaron ┆ ┆ ┆ ┆ ┆ ┆ strike │
│ 2024-07-02 ┆ Judge, ┆ SL ┆ 87.5 ┆ 94.3 ┆ 42.0 ┆ field_out ┆ hit_into_ │
│ ┆ Aaron ┆ ┆ ┆ ┆ ┆ ┆ play │
│ 2024-07-02 ┆ Judge, ┆ FC ┆ 96.3 ┆ null ┆ null ┆ null ┆ ball │
│ ┆ Aaron ┆ ┆ ┆ ┆ ┆ ┆ │
│ 2024-07-02 ┆ Judge, ┆ SL ┆ 90.1 ┆ null ┆ null ┆ null ┆ foul │
│ ┆ Aaron ┆ ┆ ┆ ┆ ┆ ┆ │
└────────────┴────────────┴────────────┴───────────┴───────────┴───────────┴───────────┴───────────┘
🍳 Cookbook: common baseball tasks
A handful of recipes you'll reach for constantly — every one leads with a premium source.
Recipe 1 — A team's schedule + where they sit in the standings 📋
Pull one club's slate with mlb_schedule(team_id=...), then find their row
in the standings. Two premium calls, one tidy snapshot.
yanks_sched = safe(
"Yankees July schedule",
lambda: mlb.parse_mlb_api_schedule(
mlb.mlb_schedule(team_id=YANKEES_ID,
start_date="2024-07-01", end_date="2024-07-07")
),
)
sched_cols = ["game_pk", "official_date", "teams_away_team_name",
"teams_home_team_name", "teams_away_score", "teams_home_score"]
if yanks_sched is not None and yanks_sched.height:
games = yanks_sched.select([c for c in sched_cols if c in yanks_sched.columns])
else:
games = "schedule unavailable right now"
if standings is not None and "team_name" in standings.columns:
rank = (standings.filter(pl.col("team_name").str.contains("Yankees"))
.select([c for c in ["team_name", "wins", "losses", "division_rank"]
if c in standings.columns]))
else:
rank = "standings unavailable"
print(rank)
games
✅ Yankees July schedule
shape: (1, 4)
┌───────────┬──────┬────────┬───────────────┐
│ team_name ┆ wins ┆ losses ┆ division_rank │
│ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 ┆ str │
╞═══════════╪══════╪════════╪═══════════════╡
│ Yankees ┆ 94 ┆ 68 ┆ 1 │
└───────────┴──────┴────────┴───────────────┘
shape: (6, 6)
┌─────────┬───────────────┬──────────────────┬─────────────────┬─────────────────┬─────────────────┐
│ game_pk ┆ official_date ┆ teams_away_team_ ┆ teams_home_team ┆ teams_away_scor ┆ teams_home_scor │
│ --- ┆ --- ┆ name ┆ _name ┆ e ┆ e │
│ i64 ┆ str ┆ --- ┆ --- ┆ --- ┆ --- │
│ ┆ ┆ str ┆ str ┆ i64 ┆ i64 │
╞═════════╪═══════════════╪══════════════════╪═════════════════╪═════════════════╪═════════════════╡
│ 745730 ┆ 2024-07-02 ┆ Cincinnati Reds ┆ New York ┆ 5 ┆ 4 │
│ ┆ ┆ ┆ Yankees ┆ ┆ │
│ 745728 ┆ 2024-07-03 ┆ Cincinnati Reds ┆ New York ┆ 3 ┆ 2 │
│ ┆ ┆ ┆ Yankees ┆ ┆ │
│ 745726 ┆ 2024-07-04 ┆ Cincinnati Reds ┆ New York ┆ 8 ┆ 4 │
│ ┆ ┆ ┆ Yankees ┆ ┆ │
│ 745725 ┆ 2024-07-05 ┆ Boston Red Sox ┆ New York ┆ 5 ┆ 3 │
│ ┆ ┆ ┆ Yankees ┆ ┆ │
│ 745724 ┆ 2024-07-06 ┆ Boston Red Sox ┆ New York ┆ 4 ┆ 14 │
│ ┆ ┆ ┆ Yankees ┆ ┆ │
│ 745723 ┆ 2024-07-07 ┆ Boston Red Sox ┆ New York ┆ 3 ┆ 0 │
│ ┆ ┆ ┆ Yankees ┆ ┆ │
└─────────┴───────────────┴──────────────────┴─────────────────┴─────────────────┴─────────────────┘
Recipe 2 — A Statcast leaderboard 🏃
The mlb_statcast_leaderboard_* family wraps Savant's pre-aggregated season
leaderboards — fast, because the heavy lifting happens server-side. Here's the
2024 sprint speed leaderboard, fastest first.
sprint = safe(
"sprint speed leaderboard",
lambda: mlb.mlb_statcast_leaderboard_sprint_speed(year=SAMPLE_SEASON, min_opp=10),
)
spcols = ["last_name, first_name", "team", "position", "competitive_runs", "sprint_speed"]
(sprint.select([c for c in spcols if c in sprint.columns])
.sort("sprint_speed", descending=True).head(10)
if sprint is not None and sprint.height else "leaderboard unavailable right now")
✅ sprint speed leaderboard
shape: (10, 5)
┌───────────────────────┬──────┬──────────┬──────────────────┬──────────────┐
│ last_name, first_name ┆ team ┆ position ┆ competitive_runs ┆ sprint_speed │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ str ┆ str ┆ i64 ┆ f64 │
╞═══════════════════════╪══════╪══════════╪══════════════════╪══════════════╡
│ Witt Jr., Bobby ┆ KC ┆ SS ┆ 298 ┆ 30.5 │
│ Rojas, Johan ┆ PHI ┆ CF ┆ 176 ┆ 30.1 │
│ De La Cruz, Elly ┆ CIN ┆ SS ┆ 249 ┆ 30.0 │
│ Fitzgerald, Tyler ┆ SF ┆ SS ┆ 99 ┆ 30.0 │
│ Clase, Jonatan ┆ TOR ┆ LF ┆ 20 ┆ 30.0 │
│ Crow-Armstrong, Pete ┆ CHC ┆ CF ┆ 149 ┆ 30.0 │
│ Scott II, Victor ┆ STL ┆ CF ┆ 62 ┆ 30.0 │
│ Mateo, Jorge ┆ BAL ┆ 2B ┆ 77 ┆ 29.9 │
│ Siri, Jose ┆ TB ┆ CF ┆ 116 ┆ 29.9 │
│ Hampson, Garrett ┆ KC ┆ CF ┆ 89 ┆ 29.8 │
└───────────────────────┴──────┴──────────┴──────────────────┴──────────────┘
Recipe 3 — Box score for one game 📊
Take a game_pk from any schedule and pull the full box score with
mlb_boxscore. Asking for
return_parsed=False gives the raw dict, which carries per-team batting and
pitching lines under teams.home / teams.away.
def team_line(game_pk):
box = mlb.mlb_boxscore(game_pk=game_pk, return_parsed=False)
rows = []
for side in ("away", "home"):
t = box["teams"][side]
bat = t["teamStats"]["batting"]
rows.append({"side": side, "team": t["team"]["name"],
"runs": bat["runs"], "hits": bat["hits"],
"home_runs": bat["homeRuns"], "rbi": bat["rbi"], "avg": bat["avg"]})
return pl.DataFrame(rows)
# Use a game_pk from the schedule we pulled, or fall back to a known game.
gid = int(schedule["game_pk"][0]) if (schedule is not None and schedule.height) else 744914
box_df = safe(f"boxscore {gid}", lambda: team_line(gid))
out = box_df if box_df is not None else "boxscore unavailable right now"
out
✅ boxscore 744914
shape: (2, 7)
┌──────┬───────────────────┬──────┬──────┬───────────┬─────┬──────┐
│ side ┆ team ┆ runs ┆ hits ┆ home_runs ┆ rbi ┆ avg │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ str ┆ i64 ┆ i64 ┆ i64 ┆ i64 ┆ str │
╞══════╪═══════════════════╪══════╪══════╪═══════════╪═════╪══════╡
│ away ┆ Houston Astros ┆ 3 ┆ 4 ┆ 2 ┆ 3 ┆ .264 │
│ home ┆ Toronto Blue Jays ┆ 1 ┆ 4 ┆ 1 ┆ 1 ┆ .234 │
└──────┴───────────────────┴──────┴──────┴───────────┴─────┴──────┘
Recipe 4 — Plate-appearance play-by-play + outcome mix ⚾
mlb_play_by_play
returns a dict with an allPlays list — one entry per plate appearance.
Flatten it with pl.json_normalize (dot-notation columns), then tally the
plate-appearance outcomes.
def pbp_frame(game_pk):
raw = mlb.mlb_play_by_play(game_pk=game_pk, return_parsed=False)
return pl.json_normalize(raw["allPlays"], separator=".", max_level=2)
plays = safe(f"play-by-play {gid}", lambda: pbp_frame(gid))
if plays is not None and plays.height:
pcols = ["about.inning", "about.halfInning", "matchup.batter.fullName",
"matchup.pitcher.fullName", "result.event"]
out = plays.select([c for c in pcols if c in plays.columns]).head()
else:
out = "play-by-play unavailable right now"
out
✅ play-by-play 744914
shape: (5, 5)
┌──────────────┬──────────────────┬────────────────────────┬────────────────────────┬──────────────┐
│ about.inning ┆ about.halfInning ┆ matchup.batter.fullNam ┆ matchup.pitcher.fullNa ┆ result.event │
│ --- ┆ --- ┆ e ┆ me ┆ --- │
│ i64 ┆ str ┆ --- ┆ --- ┆ str │
│ ┆ ┆ str ┆ str ┆ │
╞══════════════╪══════════════════╪════════════════════════╪════════════════════════╪══════════════╡
│ 1 ┆ top ┆ Alex Bregman ┆ Yariel Rodríguez ┆ Flyout │
│ 1 ┆ top ┆ Jake Meyers ┆ Yariel Rodríguez ┆ Strikeout │
│ 1 ┆ top ┆ Yordan Alvarez ┆ Yariel Rodríguez ┆ Groundout │
│ 1 ┆ bottom ┆ Bo Bichette ┆ Hunter Brown ┆ Groundout │
│ 1 ┆ bottom ┆ Spencer Horwitz ┆ Hunter Brown ┆ Lineout │
└──────────────┴──────────────────┴────────────────────────┴────────────────────────┴──────────────┘
# Outcome mix for the game — the shape of every plate appearance.
if plays is not None and plays.height and "result.event" in plays.columns:
out = (plays.group_by("result.event")
.agg(pl.len().alias("count"))
.sort("count", descending=True).head(10))
else:
out = "no play-by-play to summarize right now"
out
shape: (10, 2)
┌──────────────────┬───────┐
│ result.event ┆ count │
│ --- ┆ --- │
│ str ┆ u32 │
╞══════════════════╪═══════╡
│ Strikeout ┆ 16 │
│ Groundout ┆ 14 │
│ Pop Out ┆ 10 │
│ Flyout ┆ 7 │
│ Walk ┆ 6 │
│ Lineout ┆ 4 │
│ Single ┆ 3 │
│ Home Run ┆ 3 │
│ Double ┆ 2 │
│ Grounded Into DP ┆ 1 │
└──────────────────┴───────┘
Recipe 5 — League leaders for any stat 🥇
mlb_stats_leaders
gives you the league leaderboard for any category — homeRuns, avg,
era, strikeouts, you name it. The leaders come back nested under each
category, so we flatten the top-N into a tidy frame. Here's the 2024 home-run
race.
def hr_leaders(season, category="homeRuns", group="hitting", n=10):
raw = mlb.mlb_stats_leaders(leader_categories=category, season=season,
stat_group=group, limit=n)
leaders = raw["leagueLeaders"][0]["leaders"]
rows = [{"rank": l["rank"], "player": l["person"]["fullName"],
"team": l.get("team", {}).get("name"), "value": l["value"]}
for l in leaders]
return pl.DataFrame(rows)
leaders = safe("2024 HR leaders",
lambda: hr_leaders(SAMPLE_SEASON, "homeRuns", "hitting", 10))
leaders if leaders is not None else "leaders unavailable right now"
✅ 2024 HR leaders
shape: (10, 4)
┌──────┬───────────────────┬───────────────────────┬───────┐
│ rank ┆ player ┆ team ┆ value │
│ --- ┆ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str ┆ str │
╞══════╪═══════════════════╪═══════════════════════╪═══════╡
│ 1 ┆ Aaron Judge ┆ New York Yankees ┆ 58 │
│ 2 ┆ Shohei Ohtani ┆ Los Angeles Dodgers ┆ 54 │
│ 3 ┆ Anthony Santander ┆ Baltimore Orioles ┆ 44 │
│ 4 ┆ Juan Soto ┆ New York Yankees ┆ 41 │
│ 5 ┆ Marcell Ozuna ┆ Atlanta Braves ┆ 39 │
│ 5 ┆ José Ramírez ┆ Cleveland Guardians ┆ 39 │
│ 5 ┆ Brent Rooker ┆ Oakland Athletics ┆ 39 │
│ 8 ┆ Kyle Schwarber ┆ Philadelphia Phillies ┆ 38 │
│ 9 ┆ Gunnar Henderson ┆ Baltimore Orioles ┆ 37 │
│ 10 ┆ Ketel Marte ┆ Arizona Diamondbacks ┆ 36 │
└──────┴───────────────────┴───────────────────────┴───────┘
Recipe 6 — Who's beating their expected stats? 🎲
Statcast's expected stats ask what should have happened given each ball's
exit velocity and launch angle.
mlb_statcast_leaderboard_expected_stats
hands you ba/est_ba, slg/est_slg, woba/est_woba side by side —
sort by the diff to find the luckiest (and unluckiest) hitters.
xstats = safe(
"expected stats",
lambda: mlb.mlb_statcast_leaderboard_expected_stats(
year=SAMPLE_SEASON, type="batter", min="q"),
)
if xstats is not None and xstats.height and "est_woba_minus_woba_diff" in xstats.columns:
cols = ["last_name, first_name", "pa", "woba", "est_woba",
"est_woba_minus_woba_diff"]
# Most negative diff = outperforming their expected wOBA the most.
out = (xstats.select([c for c in cols if c in xstats.columns])
.sort("est_woba_minus_woba_diff").head(10))
else:
out = "expected-stats leaderboard unavailable right now"
out
✅ expected stats
shape: (10, 5)
┌───────────────────────┬─────┬───────┬──────────┬──────────────────────────┐
│ last_name, first_name ┆ pa ┆ woba ┆ est_woba ┆ est_woba_minus_woba_diff │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ f64 ┆ f64 ┆ f64 │
╞═══════════════════════╪═════╪═══════╪══════════╪══════════════════════════╡
│ Drury, Brandon ┆ 360 ┆ 0.217 ┆ 0.264 ┆ -0.047 │
│ Soto, Juan ┆ 713 ┆ 0.421 ┆ 0.463 ┆ -0.042 │
│ Bailey, Patrick ┆ 448 ┆ 0.281 ┆ 0.322 ┆ -0.041 │
│ Sosa, Lenyn ┆ 369 ┆ 0.28 ┆ 0.321 ┆ -0.041 │
│ Morel, Christopher ┆ 611 ┆ 0.28 ┆ 0.316 ┆ -0.036 │
│ Garcia, Maikel ┆ 626 ┆ 0.27 ┆ 0.305 ┆ -0.035 │
│ Martinez, J.D. ┆ 495 ┆ 0.318 ┆ 0.353 ┆ -0.035 │
│ Harris II, Michael ┆ 470 ┆ 0.312 ┆ 0.346 ┆ -0.034 │
│ Margot, Manuel ┆ 343 ┆ 0.276 ┆ 0.31 ┆ -0.034 │
│ Kirk, Alejandro ┆ 386 ┆ 0.297 ┆ 0.329 ┆ -0.032 │
└───────────────────────┴─────┴───────┴──────────┴──────────────────────────┘
Recipe 7 — The fastest bats in baseball 💨
Bat tracking is one of Statcast's newest toys.
mlb_statcast_leaderboard_bat_tracking
returns average bat speed, swing length, and "hard-swing rate" per hitter —
sort by avg_bat_speed to see who's swinging the hardest.
bats = safe(
"bat tracking",
lambda: mlb.mlb_statcast_leaderboard_bat_tracking(year=SAMPLE_SEASON, type="batter"),
)
if bats is not None and bats.height and "avg_bat_speed" in bats.columns:
cols = ["name", "swings_competitive", "avg_bat_speed",
"hard_swing_rate", "swing_length"]
out = (bats.select([c for c in cols if c in bats.columns])
.sort("avg_bat_speed", descending=True).head(10))
else:
out = "bat-tracking leaderboard unavailable right now"
out
✅ bat tracking
shape: (10, 5)
┌───────────────────┬────────────────────┬───────────────┬─────────────────┬──────────────┐
│ name ┆ swings_competitive ┆ avg_bat_speed ┆ hard_swing_rate ┆ swing_length │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ f64 ┆ f64 ┆ f64 │
╞═══════════════════╪════════════════════╪═══════════════╪═════════════════╪══════════════╡
│ Caminero, Junior ┆ 433 ┆ 79.917064 ┆ 0.896074 ┆ 8.5657 │
│ Walker, Jordan ┆ 506 ┆ 79.072949 ┆ 0.859684 ┆ 8.319791 │
│ Cruz, Oneil ┆ 447 ┆ 78.461902 ┆ 0.780761 ┆ 7.622225 │
│ Kurtz, Nick ┆ 471 ┆ 78.17323 ┆ 0.808917 ┆ 7.771097 │
│ Adell, Jo ┆ 594 ┆ 77.347233 ┆ 0.703704 ┆ 7.74126 │
│ Smith, Cam ┆ 470 ┆ 77.064652 ┆ 0.723404 ┆ 7.690357 │
│ Schwarber, Kyle ┆ 514 ┆ 77.027339 ┆ 0.754864 ┆ 7.471818 │
│ Bauers, Jake ┆ 353 ┆ 77.014821 ┆ 0.753541 ┆ 7.692569 │
│ Caglianone, Jac ┆ 431 ┆ 76.845271 ┆ 0.712297 ┆ 7.914317 │
│ Mitchell, Garrett ┆ 333 ┆ 76.823575 ┆ 0.744745 ┆ 7.198839 │
└───────────────────┴────────────────────┴───────────────┴─────────────────┴──────────────┘
Recipe 8 — The best gloves: Outs Above Average 🧤
Offense is easy to measure; defense is hard. Statcast's
mlb_statcast_leaderboard_outs_above_average
credits fielders for the plays they make relative to expectation. Sort by
outs_above_average to find the season's best defenders.
oaa = safe(
"outs above average",
lambda: mlb.mlb_statcast_leaderboard_outs_above_average(year=SAMPLE_SEASON),
)
if oaa is not None and oaa.height and "outs_above_average" in oaa.columns:
cols = ["last_name, first_name", "display_team_name",
"primary_pos_formatted", "outs_above_average",
"fielding_runs_prevented"]
out = (oaa.select([c for c in cols if c in oaa.columns])
.sort("outs_above_average", descending=True).head(10))
else:
out = "OAA leaderboard unavailable right now"
out
✅ outs above average
shape: (10, 5)
┌───────────────────┬───────────────────┬───────────────────┬───────────────────┬──────────────────┐
│ last_name, ┆ display_team_name ┆ primary_pos_forma ┆ outs_above_averag ┆ fielding_runs_pr │
│ first_name ┆ --- ┆ tted ┆ e ┆ evented │
│ --- ┆ str ┆ --- ┆ --- ┆ --- │
│ str ┆ ┆ str ┆ i64 ┆ i64 │
╞═══════════════════╪═══════════════════╪═══════════════════╪═══════════════════╪══════════════════╡
│ Giménez, Andrés ┆ Guardians ┆ 2B ┆ 20 ┆ 15 │
│ Young, Jacob ┆ Nationals ┆ CF ┆ 20 ┆ 18 │
│ Semien, Marcus ┆ Rangers ┆ 2B ┆ 19 ┆ 14 │
│ Swanson, Dansby ┆ Cubs ┆ SS ┆ 17 ┆ 13 │
│ Siani, Michael ┆ Cardinals ┆ CF ┆ 16 ┆ 14 │
│ Siri, Jose ┆ Rays ┆ CF ┆ 16 ┆ 14 │
│ Witt Jr., Bobby ┆ Royals ┆ SS ┆ 16 ┆ 12 │
│ Lindor, Francisco ┆ Mets ┆ SS ┆ 15 ┆ 11 │
│ Santana, Carlos ┆ Twins ┆ 1B ┆ 15 ┆ 11 │
│ Tovar, Ezequiel ┆ Rockies ┆ SS ┆ 15 ┆ 11 │
└───────────────────┴───────────────────┴───────────────────┴───────────────────┴──────────────────┘
Recipe 9 — Find the X: the hardest-hit homers 🚀
mlb_statcast_search isn't just for one player — point its filters at an outcome.
Pass at_bat_result="home_run" over a short window to pull every homer,
then sort by launch_speed to find the ones that were absolutely crushed.
(Keep the window small — a couple of days at a time.)
homers = safe(
"home runs (2-day)",
lambda: mlb.mlb_statcast_search(start_dt="2024-07-01", end_dt="2024-07-02",
at_bat_result="home_run"),
)
if homers is not None and homers.height and "launch_speed" in homers.columns:
print("homers in window:", homers.height)
cols = ["game_date", "player_name", "launch_speed",
"launch_angle", "hit_distance_sc"]
out = (homers.select([c for c in cols if c in homers.columns])
.sort("launch_speed", descending=True).head(10))
else:
out = "no homers in that window right now"
out
✅ home runs (2-day)
homers in window: 51
shape: (10, 5)
┌────────────┬────────────────────┬──────────────┬──────────────┬─────────────────┐
│ game_date ┆ player_name ┆ launch_speed ┆ launch_angle ┆ hit_distance_sc │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ str ┆ f64 ┆ i64 ┆ i64 │
╞════════════╪════════════════════╪══════════════╪══════════════╪═════════════════╡
│ 2024-07-02 ┆ De La Cruz, Elly ┆ 114.1 ┆ 21 ┆ 425 │
│ 2024-07-02 ┆ Judge, Aaron ┆ 112.5 ┆ 25 ┆ 381 │
│ 2024-07-02 ┆ Sánchez, Jesús ┆ 112.5 ┆ 24 ┆ 448 │
│ 2024-07-02 ┆ Ohtani, Shohei ┆ 112.0 ┆ 37 ┆ 433 │
│ 2024-07-02 ┆ Soler, Jorge ┆ 109.0 ┆ 21 ┆ 394 │
│ 2024-07-02 ┆ Rooker, Brent ┆ 108.7 ┆ 34 ┆ 405 │
│ 2024-07-02 ┆ Turner, Trea ┆ 108.5 ┆ 20 ┆ 422 │
│ 2024-07-02 ┆ Schneemann, Daniel ┆ 108.3 ┆ 28 ┆ 408 │
│ 2024-07-02 ┆ Riley, Austin ┆ 108.3 ┆ 36 ┆ 407 │
│ 2024-07-02 ┆ Witt Jr., Bobby ┆ 108.0 ┆ 24 ┆ 399 │
└────────────┴────────────────────┴──────────────┴──────────────┴─────────────────┘
Recipe 13 — Every pitch of a single game (Savant gamefeed) 🎮
mlb_statcast_gamefeed
pulls Baseball Savant's rich single-game feed and tidies it to one row per
pitch — pitch type, velocity, plate location, and the batted-ball result —
across both teams. Feed it any game_pk from a schedule.
gf = safe(
f"gamefeed {gid}",
lambda: mlb.mlb_statcast_gamefeed(game_pk=gid),
)
if gf is not None and gf.height:
print("pitches tracked:", gf.height)
gcols = ["inning", "half_inning", "batter_name", "pitcher_name",
"pitch_type", "start_speed", "launch_speed", "events"]
out = gf.select([c for c in gcols if c in gf.columns]).head()
else:
out = "gamefeed unavailable right now"
out
✅ gamefeed 744914
pitches tracked: 244
shape: (5, 8)
┌────────┬────────────┬────────────┬────────────┬────────────┬────────────┬────────────┬───────────┐
│ inning ┆ half_innin ┆ batter_nam ┆ pitcher_na ┆ pitch_type ┆ start_spee ┆ launch_spe ┆ events │
│ --- ┆ g ┆ e ┆ me ┆ --- ┆ d ┆ ed ┆ --- │
│ i64 ┆ --- ┆ --- ┆ --- ┆ str ┆ --- ┆ --- ┆ str │
│ ┆ str ┆ str ┆ str ┆ ┆ f64 ┆ str ┆ │
╞════════╪════════════╪════════════╪════════════╪════════════╪════════════╪════════════╪═══════════╡
│ 1 ┆ top ┆ Alex ┆ Yariel ┆ FF ┆ 95.9 ┆ null ┆ Flyout │
│ ┆ ┆ Bregman ┆ Rodríguez ┆ ┆ ┆ ┆ │
│ 1 ┆ top ┆ Alex ┆ Yariel ┆ FF ┆ 94.1 ┆ null ┆ Flyout │
│ ┆ ┆ Bregman ┆ Rodríguez ┆ ┆ ┆ ┆ │
│ 1 ┆ top ┆ Alex ┆ Yariel ┆ SL ┆ 85.8 ┆ 92.9 ┆ Flyout │
│ ┆ ┆ Bregman ┆ Rodríguez ┆ ┆ ┆ ┆ │
│ 1 ┆ top ┆ Jake ┆ Yariel ┆ FF ┆ 94.1 ┆ null ┆ Strikeout │
│ ┆ ┆ Meyers ┆ Rodríguez ┆ ┆ ┆ ┆ │
│ 1 ┆ top ┆ Jake ┆ Yariel ┆ FF ┆ 95.4 ┆ null ┆ Strikeout │
│ ┆ ┆ Meyers ┆ Rodríguez ┆ ┆ ┆ ┆ │
└────────┴────────────┴────────────┴────────────┴────────────┴────────────┴────────────┴───────────┘
Recipe 10 — The biggest swings of a game (WPA) 📈
mlb_win_probability
returns every play with the live win-probability before and after, plus
Win Probability Added (homeTeamWinProbabilityAdded). Sort by its absolute
value to surface the most pivotal moments of the game.
def wpa_swings(game_pk, n=8):
plays = mlb.mlb_win_probability(game_pk=game_pk, return_parsed=False)
df = pl.json_normalize(plays, separator=".", max_level=2)
keep = ["about.inning", "about.halfInning", "result.event",
"result.description", "homeTeamWinProbabilityAdded"]
df = df.select([c for c in keep if c in df.columns])
if "homeTeamWinProbabilityAdded" in df.columns:
df = (df.with_columns(
pl.col("homeTeamWinProbabilityAdded").abs().alias("wpa_abs"))
.sort("wpa_abs", descending=True).drop("wpa_abs").head(n))
return df
# Reuse the game_pk we pulled earlier (falls back to a known game).
wpa = safe(f"WPA swings {gid}", lambda: wpa_swings(gid))
wpa if wpa is not None else "win-probability unavailable right now"
✅ WPA swings 744914
shape: (8, 5)
┌──────────────┬──────────────────┬──────────────────┬──────────────────────┬──────────────────────┐
│ about.inning ┆ about.halfInning ┆ result.event ┆ result.description ┆ homeTeamWinProbabili │
│ --- ┆ --- ┆ --- ┆ --- ┆ tyAdded │
│ i64 ┆ str ┆ str ┆ str ┆ --- │
│ ┆ ┆ ┆ ┆ f64 │
╞══════════════╪══════════════════╪══════════════════╪══════════════════════╪══════════════════════╡
│ 8 ┆ bottom ┆ Double ┆ Spencer Horwitz ┆ 23.7 │
│ ┆ ┆ ┆ doubles (3) on… ┆ │
│ 8 ┆ bottom ┆ Groundout ┆ Daulton Varsho ┆ -20.4 │
│ ┆ ┆ ┆ grounds out sha… ┆ │
│ 8 ┆ bottom ┆ Lineout ┆ George Springer ┆ -19.3 │
│ ┆ ┆ ┆ lines out to t… ┆ │
│ 5 ┆ top ┆ Home Run ┆ Jeremy Peña homers ┆ -14.8 │
│ ┆ ┆ ┆ (6) on a fl… ┆ │
│ 9 ┆ top ┆ Home Run ┆ Yordan Alvarez ┆ -12.6 │
│ ┆ ┆ ┆ homers (17) on … ┆ │
│ 8 ┆ bottom ┆ Walk ┆ Addison Barger ┆ 9.8 │
│ ┆ ┆ ┆ walks. ┆ │
│ 8 ┆ bottom ┆ Strikeout ┆ Bo Bichette strikes ┆ -9.0 │
│ ┆ ┆ ┆ out swingi… ┆ │
│ 7 ┆ top ┆ Grounded Into DP ┆ Yainer Diaz grounds ┆ 8.1 │
│ ┆ ┆ ┆ into a dou… ┆ │
└──────────────┴──────────────────┴──────────────────┴──────────────────────┴──────────────────────┘
Recipe 11 — Season award winners (MVP, Cy Young) 🏅
mlb_awards is the catalog of
every award id; mlb_award_recipients
names the season's winner for one id. We grab the four marquee awards — AL/NL
MVP and AL/NL Cy Young — and stack them into one tidy board.
def award_board(season, award_ids):
frames = []
for label, aid in award_ids.items():
df = mlb.mlb_award_recipients(award_id=aid, season=season)
if df is not None and df.height:
name_col = ("player_name_first_last" if "player_name_first_last"
in df.columns else "name")
frames.append(df.select([
pl.lit(label).alias("award"),
pl.col("season"),
pl.col(name_col).alias("winner"),
]))
return pl.concat(frames, how="vertical") if frames else pl.DataFrame()
AWARDS = {"AL MVP": "ALMVP", "NL MVP": "NLMVP",
"AL Cy Young": "ALCY", "NL Cy Young": "NLCY"}
board = safe("2024 award winners", lambda: award_board(SAMPLE_SEASON, AWARDS))
board if (board is not None and board.height) else "awards unavailable right now"
✅ 2024 award winners
shape: (4, 3)
┌─────────────┬────────┬───────────────┐
│ award ┆ season ┆ winner │
│ --- ┆ --- ┆ --- │
│ str ┆ str ┆ str │
╞═════════════╪════════╪═══════════════╡
│ AL MVP ┆ 2024 ┆ Aaron Judge │
│ NL MVP ┆ 2024 ┆ Shohei Ohtani │
│ AL Cy Young ┆ 2024 ┆ Tarik Skubal │
│ NL Cy Young ┆ 2024 ┆ Chris Sale │
└─────────────┴────────┴───────────────┘
Recipe 12 — The first-round draft board 🎓
mlb_draft returns the amateur
draft, organized into rounds of picks. Pass round_=1 and flatten the picks
into one row per selection — who went where, and from which school.
def draft_board(year, round_=1):
raw = mlb.mlb_draft(year=year, round_=round_, return_parsed=False)
picks = raw["drafts"]["rounds"][0]["picks"]
rows = [{
"pick": p.get("pickNumber"),
"player": p.get("person", {}).get("fullName"),
"team": p.get("team", {}).get("name"),
"school": p.get("school", {}).get("name"),
} for p in picks]
return pl.DataFrame(rows)
draft = safe("2024 first round", lambda: draft_board(2024, round_=1))
draft.head(12) if (draft is not None and draft.height) else "draft unavailable right now"
✅ 2024 first round
shape: (12, 4)
┌──────┬───────────────────┬──────────────────────┬─────────────────────┐
│ pick ┆ player ┆ team ┆ school │
│ --- ┆ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str ┆ str │
╞══════╪═══════════════════╪══════════════════════╪═════════════════════╡
│ 1 ┆ Travis Bazzana ┆ Cleveland Guardians ┆ Oregon State │
│ 2 ┆ Chase Burns ┆ Cincinnati Reds ┆ Wake Forest │
│ 3 ┆ Charlie Condon ┆ Colorado Rockies ┆ Georgia │
│ 4 ┆ Nick Kurtz ┆ Athletics ┆ Wake Forest │
│ 5 ┆ Hagen Smith ┆ Chicago White Sox ┆ Arkansas │
│ 6 ┆ Jac Caglianone ┆ Kansas City Royals ┆ Florida │
│ 7 ┆ JJ Wetherholt ┆ St. Louis Cardinals ┆ West Virginia │
│ 8 ┆ Christian Moore ┆ Los Angeles Angels ┆ Tennessee │
│ 9 ┆ Konnor Griffin ┆ Pittsburgh Pirates ┆ Jackson Prep School │
│ 10 ┆ Seaver King ┆ Washington Nationals ┆ Wake Forest │
│ 11 ┆ Bryce Rainer ┆ Detroit Tigers ┆ Harvard-Westlake HS │
│ 12 ┆ Braden Montgomery ┆ Boston Red Sox ┆ Texas A&M │
└──────┴───────────────────┴──────────────────────┴─────────────────────┘
📅 A whole season's schedule via ESPN
Want every game in a season without looping over dates? The bulk
load_mlb_* release-parquet loaders are still being wired up (they raise a
friendly NotImplementedError for now), and they point you to the working
path: espn_mlb_schedule
with dates=<season year> pulls the full slate as one wide frame. Scores come
back as strings — cast before doing arithmetic.
season_sched = safe(
"ESPN 2024 season schedule",
lambda: mlb.espn_mlb_schedule(dates=2024),
)
if season_sched is not None and season_sched.height:
print("games:", season_sched.height)
scols = ["game_id", "away_display_name", "away_score",
"home_display_name", "home_score", "status_type_completed"]
out = season_sched.select([c for c in scols if c in season_sched.columns]).head()
else:
out = "ESPN schedule unavailable right now"
out
✅ ESPN 2024 season schedule
games: 500
shape: (5, 6)
┌───────────┬────────────────────┬────────────┬───────────────────┬────────────┬───────────────────┐
│ game_id ┆ away_display_name ┆ away_score ┆ home_display_name ┆ home_score ┆ status_type_compl │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ eted │
│ str ┆ str ┆ str ┆ str ┆ str ┆ --- │
│ ┆ ┆ ┆ ┆ ┆ bool │
╞═══════════╪════════════════════╪════════════╪═══════════════════╪════════════╪═══════════════════╡
│ 401576167 ┆ Los Angeles ┆ 14 ┆ San Diego Padres ┆ 1 ┆ true │
│ ┆ Dodgers ┆ ┆ ┆ ┆ │
│ 401576169 ┆ Kansas City Royals ┆ 4 ┆ Texas Rangers ┆ 5 ┆ true │
│ 401576643 ┆ Chicago White Sox ┆ 1 ┆ Chicago Cubs ┆ 8 ┆ true │
│ 401576170 ┆ San Diego Padres ┆ 1 ┆ Los Angeles ┆ 4 ┆ true │
│ ┆ ┆ ┆ Dodgers ┆ ┆ │
│ 401576168 ┆ Arizona ┆ 0 ┆ Colorado Rockies ┆ 3 ┆ true │
│ ┆ Diamondbacks ┆ ┆ ┆ ┆ │
└───────────┴────────────────────┴────────────┴───────────────────┴────────────┴───────────────────┘
⚪ Secondary path: ESPN teams (espn_mlb_*)
espn_mlb_teams returns one
wide polars frame — handy as a cross-check, or when you want ESPN's display
names and ids alongside the MLB Stats API ones.
espn_teams = safe("ESPN teams", lambda: mlb.espn_mlb_teams())
ecols = ["team_id", "team_location", "team_name", "team_abbreviation", "team_display_name"]
(espn_teams.select([c for c in ecols if c in espn_teams.columns]).head()
if espn_teams is not None else "ESPN teams unavailable right now")
✅ ESPN teams
shape: (5, 5)
┌─────────┬───────────────┬──────────────┬───────────────────┬──────────────────────┐
│ team_id ┆ team_location ┆ team_name ┆ team_abbreviation ┆ team_display_name │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ str ┆ str ┆ str ┆ str │
╞═════════╪═══════════════╪══════════════╪═══════════════════╪══════════════════════╡
│ 29 ┆ Arizona ┆ Diamondbacks ┆ ARI ┆ Arizona Diamondbacks │
│ 11 ┆ Athletics ┆ Athletics ┆ ATH ┆ Athletics │
│ 15 ┆ Atlanta ┆ Braves ┆ ATL ┆ Atlanta Braves │
│ 1 ┆ Baltimore ┆ Orioles ┆ BAL ┆ Baltimore Orioles │
│ 2 ┆ Boston ┆ Red Sox ┆ BOS ┆ Boston Red Sox │
└─────────┴───────────────┴──────────────┴───────────────────┴──────────────────────┘
🎉 Where to next
- Everything returns polars by default — pass
return_as_pandas=Truefor a pandas frame, orreturn_parsed=Falseon themlb_*wrappers for raw JSON. - Full reference: the MLB pages in the sidebar — MLB Stats API + Statcast helpers, the full MLB Stats API surface, and the ESPN core / site / web endpoints.
- R user? The same data lives in baseballr.
- Compare conventions with the other league intros (
04_nba_intro.ipynb,07_nhl_intro.ipynb) or the cross-sport01_quickstart.ipynb.
Now go find the next 60-homer season. ⚾🔥