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.
pip install mlbapiRequires Python 3.10+ and pydantic >= 2.0.
Everything goes through a Client instance.
from mlbapi import Client
client = Client()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)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)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).'
)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}')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}')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)from mlbapi import Client
client = Client()
alumni = client.team_alumni(147, season='2000', group='alumni')
for person in alumni.people:
print(person.full_name)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')client = Client(timeout=30)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)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__.
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 |
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.
| 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 | 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()
Coming from panzarino/mlbgame? See the migration guide for a function-by-function mapping.
Contributions are welcome. Please read CONTRIBUTING.md before submitting a pull request. Bug reports and feature requests can be filed as GitHub Issues.
If mlbapi saves you time, consider supporting its development:
- ⭐ Star this repo — it helps others discover the project
- 💛 Sponsor on GitHub
- ☕ Donate via PayPal
This project is licensed under the terms found in LICENSE.
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.