mlbapi

mlbapi is a Python library that provides Pythonic bindings for MLB Advanced Media's StatsAPI — the same data source that powers MLB.com's live game data, box scores, standings, and more.

Unlike raw API calls, mlbapi returns structured Python objects so you can work with MLB data naturally in your code.

---

Features

• Schedule lookups by team and date range
• Box score data including batting and pitching stats
• Live linescore data (inning, batter, pitcher, count)
• Structured Python objects from every endpoint — no manual JSON parsing
• Lightweight: only requires requests

---

Installation

pip install mlbapi

---

Quick Start

Get a team's schedule for a date range

import mlbapi

# Houston Astros schedule for the 2024 season
schedule = mlbapi.schedule(start_date='04/01/2024', end_date='10/01/2024', team_id=117)

Get a team's schedule for a single date

import mlbapi

schedule = mlbapi.schedule(date='04/01/2024', team_id=117)

Get box score data for a game

import mlbapi

schedule = mlbapi.schedule(date='04/01/2024', team_id=117)
game_pk = schedule.dates[0].games[0].game_pk
boxscore = mlbapi.boxscore(game_pk)

# Print all game info (weather, attendance, venue, etc.)
for info in boxscore.info:
    print(info.info)

# Print batting stats for both teams
print(boxscore.teams.away.team_stats.batting.__dict__)
print(boxscore.teams.home.team_stats.batting.__dict__)

Get live linescore data

import mlbapi

schedule = mlbapi.schedule(date='04/01/2024', team_id=117)
game_pk = schedule.dates[0].games[0].game_pk
line = mlbapi.linescore(game_pk)

output = '{} of the {}, {} facing {}. {} ball(s), {} strike(s), {} out(s)'
print(output.format(
    line.inning_half,
    line.current_inning_ordinal,
    line.offense.batter.full_name,
    line.defense.pitcher.full_name,
    line.balls,
    line.strikes,
    line.outs
))
# Top of the 9th, Scott Van Slyke facing Framber Valdez. 0 ball(s), 3 strike(s), 3 out(s)

---

Team IDs

Common MLB team IDs for reference:

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

A full list is available via mlbapi.teams().

---

Documentation

Full documentation and endpoint reference coming soon. In the meantime, feel free to open an issue with questions.

---

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.