mlbapi 1.1.1

A Python 3 wrapper for the MLB StatsAPI at statsapi.mlb.com

mlbapi

mlbapi is a Python 3 client for the MLB StatsAPI — the data source that powers MLB.com's live game data, box scores, standings, and more.

All responses are returned as validated Pydantic models, so you get attribute access, type safety, and IDE autocompletion with no JSON parsing required.

---

Installation

pip install mlbapi

Requires Python 3.10+ and pydantic >= 2.0.

---

Quick Start

Everything goes through a Client instance.

from mlbapi import Client

client = Client()

Schedule

from mlbapi import Client

client = Client()

# Single date
schedule = client.schedule(date='2024-06-01', team_id=117)

# Date range
schedule = client.schedule(
    start_date='2024-04-01',
    end_date='2024-10-01',
    team_id=117,
)

for date in schedule.dates:
    for game in date.games:
        print(game.game_pk, game.status.detailed_state)

Box Score

from mlbapi import Client

client = Client()

schedule = client.schedule(date='2024-06-01', team_id=117)
game_pk = schedule.dates[0].games[0].game_pk

box = client.boxscore(game_pk)

# Team batting stats
print(box.teams.away.team.name)
print(box.teams.away.team_stats.batting.model_dump())

# Game info (weather, attendance, etc.)
for item in box.info:
    print(item.label, item.value)

Linescore

from mlbapi import Client

client = Client()

schedule = client.schedule(date='2024-06-01', team_id=117)
game_pk = schedule.dates[0].games[0].game_pk

line = client.linescore(game_pk)

print(
    f'{line.inning_half} of the {line.current_inning_ordinal} — '
    f'{line.offense.batter.full_name} facing {line.defense.pitcher.full_name}. '
    f'Count: {line.balls}-{line.strikes}, {line.outs} out(s).'
)

Standings

from mlbapi import Client

client = Client()

standings = client.standings(league_id=[103, 104])  # AL + NL

for record in standings.records:
    for tr in record.team_records:
        print(f'{tr.team.name:30s}  {tr.wins}-{tr.losses}  {tr.winning_percentage}')

Team Leaders

from mlbapi import Client

client = Client()

leaders = client.team_leaders(147, season='2024', leader_categories='homeRuns')

for category in leaders.team_leaders:
    print(f'{category.leader_category} ({category.season})')
    for entry in category.leaders:
        print(f'  {entry.rank}. {entry.person.full_name}  {entry.value}')

Team Affiliates

from mlbapi import Client

client = Client()

# Affiliates for one team
affiliates = client.team_affiliates(147, season='2024')
for team in affiliates.teams:
    print(team.name)

# Affiliates for multiple teams at once
affiliates = client.teams_affiliates(team_ids=[147, 111], season='2024')
for team in affiliates.teams:
    print(team.name)

Team Alumni

from mlbapi import Client

client = Client()

alumni = client.team_alumni(147, season='2000', group='alumni')
for person in alumni.people:
    print(person.full_name)

Team Stats

from mlbapi import Client

client = Client()

# Stats for a single team
stats = client.team_stats(147, stats='season', group='hitting', season='2024')
for group in stats.stats:
    for split in group.splits:
        print(split.stat)

# Aggregated stats across all teams
all_stats = client.teams_stats(stats='season', group='hitting', season='2024')

---

Configuration

Timeout

client = Client(timeout=30)

Custom Session (retries, proxy, headers)

import requests
from requests.adapters import HTTPAdapter, Retry

retry = Retry(total=3, backoff_factor=1, status_forcelist=[500, 502, 503, 504])
session = requests.Session()
session.mount('https://', HTTPAdapter(max_retries=retry))

client = Client(session=session)

Context Manager

Use the context manager when you want the client to manage its own session lifecycle:

from mlbapi import Client

with Client() as client:
    schedule = client.schedule(date='2024-06-01')
    box = client.boxscore(schedule.dates[0].games[0].game_pk)

The session is opened on __enter__ and closed on __exit__.

---

Error Handling

All exceptions inherit from mlbapi.MLBAPIException.

from mlbapi import Client, ParameterException, ObjectNotFoundException, RequestException

client = Client()

try:
    box = client.boxscore(716463)
except ParameterException as e:
    print(f'Bad parameter: {e}')
except ObjectNotFoundException as e:
    print(f'Not found: {e}')
except RequestException as e:
    print(f'Network error: {e}')

Exception	Raised when
ParameterException	An invalid kwarg is passed to an endpoint method
ObjectNotFoundException	The API returned an error message (bad ID, etc.)
RequestException	An HTTP/network error occurred
ImplementationException	An unsupported endpoint was requested

---

Hydrations

Many endpoints accept a hydrate parameter that embeds additional data inline, saving extra requests. See the hydrations guide for supported values and examples across schedule, people, teams, venues, and stats.

---

Available Methods

Method	Description
client.schedule(**kwargs)	Game schedule by date/team/sport
client.boxscore(game_pk)	Full box score for a game
client.linescore(game_pk)	Live linescore (count, bases, pitcher/batter)
client.play_by_play(game_pk)	Play-by-play data
client.live_diff(game_pk)	Live feed diff/patch (v1.1)
client.color_feed(game_pk)	Full color feed (v1.1)
client.color_diff(game_pk)	Color feed diff/patch (v1.1)
client.color_timestamps(game_pk)	Color feed timestamps (v1.1)
client.standings(**kwargs)	League standings
client.teams(**kwargs)	Team information
client.roster(team_id, roster_type)	Team roster ('active', '40Man', 'fullRoster', …)
client.coaches(team_id)	Coaching staff for a team
client.team_affiliates(team_id)	Minor-league affiliates for a team
client.team_alumni(team_id, season, group)	Alumni (former players) for a team
client.team_history(team_id)	Historical franchise records for a team
client.team_leaders(team_id)	Statistical leaders for a team
client.team_stats(team_id)	Stats for a single team
client.teams_affiliates(team_ids)	Affiliates for multiple teams
client.teams_history(team_ids)	Historical records for multiple teams
client.teams_stats(**kwargs)	Aggregated stats across all teams
client.divisions(**kwargs)	Division information
client.leagues(**kwargs)	League information
client.league_allstar_ballot(league_id)	All-star ballot for a league
client.league_allstar_writeins(league_id)	All-star write-in ballot for a league
client.conferences(**kwargs)	Conference information
client.seasons(**kwargs)	Season information
client.all_seasons(**kwargs)	All seasons
client.venues(**kwargs)	Venue information
client.draft(year)	Draft picks for a year
client.draft_prospects(**kwargs)	Draft prospects
client.draft_latest(year)	Latest draft picks
client.stats(**kwargs)	Player/team stats
client.stats_leaders(**kwargs)	Stats leaders
client.stats_streaks(**kwargs)	Stats streaks
client.homerunderby(game_pk)	Home Run Derby data
client.game_pace(**kwargs)	Pace-of-game statistics by season/team/league
client.attendance(**kwargs)	Attendance data
client.awards(**kwargs)	Awards
client.award_recipients(award_id)	Recipients for an award
client.jobs(**kwargs)	Job listings
client.umpires(**kwargs)	Umpire roster
client.transactions(**kwargs)	Transaction data
client.meta(meta_type)	Lookup table values
client.get_team_id(name)	Team ID by name (case-insensitive)
client.get_league_id(name)	League ID by name or abbreviation
client.get_division_id(name)	Division ID by name
client.get_venue_id(name)	Venue ID by name
client.last_game(team_id)	game_pk of team's most recent completed game
client.next_game(team_id)	game_pk of team's next scheduled game

---

Team IDs

Team	ID	Team	ID
Yankees	147	Dodgers	119
Red Sox	111	Giants	137
Astros	117	Cubs	112
Braves	144	Cardinals	138
Mets	121	Padres	135

Full list: client.teams()

---

Migrating from mlbgame

Coming from panzarino/mlbgame? See the migration guide for a function-by-function mapping.

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before submitting a pull request. Bug reports and feature requests can be filed as GitHub Issues.

---

Support the Project

If mlbapi saves you time, consider supporting its development:

• ⭐ Star this repo — it helps others discover the project
• 💛 Sponsor on GitHub
• ☕ Donate via PayPal

---

License

This project is licensed under the terms found in LICENSE.

---

Disclaimer

This library is not affiliated with or endorsed by Major League Baseball or MLB Advanced Media. Use of the MLB StatsAPI is subject to MLB's terms of service.