mlbstatsapi python wrapper
Project description
Python MLB Stats API
The Unofficial Python Wrapper for the MLB Stats API
Copyright Notice
This package and its authors are not affiliated with MLB or any MLB team. This API wrapper interfaces with MLB's Stats API. Use of MLB data is subject to the notice posted at http://gdx.mlb.com/components/copyright.txt.
This is an educational project - Not for commercial use.
Getting Started
Python-mlb-statsapi is a Python library that provides developers with access to the MLB Stats API which allows developers to retrieve information related to MLB teams, players, stats, and more. Python-mlb-statsapi written in python 3.10+.
To get started with the library, refer to the information provided in this README. For a more detailed explanation, check out the documentation and the Wiki section. The Wiki contains information on return objects, endpoint structure, usage examples, and more. It is a valuable resource for getting started, working with the library, and finding the information you need.
Examples | Wiki | API
Installation
python3 -m pip install python-mlb-statsapi
Usage
python3
>>> import mlbstatsapi
>>> mlb = mlbstatsapi.Mlb()
>>> mlb.get_people_id("Ty France")
[664034]
>>> stats = ['season', 'seasonAdvanced']
>>> groups = ['hitting']
>>> params = {'season': 2022}
>>> mlb.get_player_stats(664034, stats, groups, **params)
{'hitting': {'season': Stat, 'seasonadvanced': Stat }}
>>> mlb.get_team_id("Oakland Athletics")
[133]
>>> stats = ['season', 'seasonAdvanced']
>>> groups = ['pitching']
>>> params = {'season': 2022}
>>> mlb.get_team_stats(133, stats, groups, **params)
{'pitching': {'season': Stat, 'seasonadvanced': Stat }}
Documentation
People, Person, Players, Coaches
Mlb.get_people_id(self, fullname: str, sport_id: int = 1, search_key: str = 'fullname', **params)
- Return Person Id(s) from fullnameMlb.get_person(self, player_id: int, **params)
- Return Person Object from IdMlb.get_people(self, sport_id: int = 1, **params)
- Return all Players from Sport
Draft
Mlb.get_draft(self, year_id: int, **params)
- Return a draft for a given year
Awards
Mlb.get_awards(self, award_id: int, **params)
- Return rewards recipinets for a given award
Teams
Mlb.get_team_id(self, team_name: str, search_key: str = 'name', **params)
- Return Team Id(s) from nameMlb.get_team(self, team_id: int, **params)
- Return Team Object from Team IdMlb.get_teams(self, sport_id: int = 1, **params)
- Return all Teams for SportMlb.get_team_coaches(self, team_id: int, **params)
- Return coaching roster for team for current or specified seasonMlb.get_team_roster(self, team_id: int, **params)
- Return player roster for team for current or specified season
Stats
Mlb.get_player_stats(self, person_id: int, stats: list, groups: list, **params)
- Return stats by player id, stat type and groupsMlb.get_team_stats(self, team_id: int, stats: list, groups: list, **params)
- Return stats by team id, stat types and groupsMlb.get_stats(self, stats: list, groups: list, **params: dict)
- Return stats by stat type and group argsMlb.get_players_stats_for_game(self, person_id: int, game_id: int, **params)
- Return player stats for a game
Gamepace
Mlb.get_gamepace(self, season: str, sport_id=1, **params)
- Return pace of game metrics for specific sport, league or team.
Venues
Mlb.get_venue_id(self, venue_name: str, search_key: str = 'name', **params)
- Return Venue Id(s)Mlb.get_venue(self, venue_id: int, **params)
- Return Venue Object from venue IdMlb.get_venues(self, **params)
- Return all Venues
Sports
Mlb.get_sport(self, sport_id: int, **params)
- Return a Sport object from IdMlb.get_sports(self, **params)
- Return all teams for Sport IdMlb.get_sport_id(self, sport_name: str, search_key: str = 'name', **params)
- Return Sport Id from name
Schedules
Mlb.get_schedule(self, date: str, start_date: str, end_date: str, sport_id: int, team_id: int, **params)
- Return a Schedule
Divisions
Mlb.get_division(self, division_id: int, **params)
- Return a DivisonMlb.get_divisions(self, **params)
- Return all DivisionsMlb.get_division_id(self, division_name: str, search_key: str = 'name', **params)
- Return Division Id(s) from name
Leagues
Mlb.get_league(self, league_id: int, **params)
- Return a League from IdMlb.get_leagues(self, **params)
- Return all LeaguesMlb.get_league_id(self, league_name: str, search_key: str = 'name', **params)
- Return League Id(s)
Seasons
Mlb.get_season(self, season_id: str, sport_id: int = None, **params)
- Return a seasonMlb.get_seasons(self, sportid: int = None, **params)
- Return all seasons
Standings
Mlb.get_standings(self, league_id: int, season: str, **params)
- Return standings
Schedules
Mlb.get_schedule(self, date: str = None, start_date: str = None, end_date: str = None, sport_id: int = 1, team_id: int = None, **params)
- Return a Schedule from datesMlb.get_scheduled_games_by_date(self, date: str = None,start_date: str = None, end_date: str = None, sport_id: int = 1, **params)
- Return game ids from dates
Games
Mlb.get_game(self, game_id: int, **params)
- Return the Game for a specific Game IdMlb.get_game_play_by_play(self, game_id: int, **params)
- Return Play by play data for a gameMlb.get_game_line_score(self, game_id: int, **params)
- Return a Linescore for a gameMlb.get_game_box_score(self, game_id: int, **params)
- Return a Boxscore for a game
Examples
Let's show some examples of getting stat objects from the API. What is baseball with out stats right?
MLB Stats
Player Stats
Get the Id(s) of the players you want stats for and set stat types and groups.
>>> mlb = mlbstatsapi.Mlb()
>>> player_id = mlb.get_people_id("Ty France")[0]
>>> stats = ['season', 'career']
>>> groups = ['hitting', 'pitching']
>>> params = {'season': 2022}
Use player.id and stat types and groups to return a stats dictionary
>>> stat_dict = mlb.get_player_stats(player_id, stats=stats, groups=groups, **params)
>>> season_hitting_stat = stat_dict['hitting']['season']
>>> career_pitching_stat = stat_dict['pitching']['career']
Print season hitting stats
>>> for split in season_hitting_stat.splits:
... for k, v in split.stat.__dict__.items():
... print(k, v)
gamesplayed 140
groundouts 163
airouts 148
runs 65
doubles 27
triples 1
homeruns 20
strikeouts 94
baseonballs 35
...
>>> for split in career_pitching_stat.splits:
... for k, v in split.stat.__dict__.items():
... print(k, v)
gamesplayed 2
gamesstarted 0
groundouts 2
airouts 4
runs 1
doubles 0
triples 0
homeruns 1
strikeouts 0
baseonballs 0
intentionalwalks 0
hits 2
hitbypitch 0
...
Team stats
Get the Team Id(s)
python3
>>> mlb = mlbstatsapi.Mlb()
>>> team_id = mlb.get_team_id('Seattle Mariners')[0]
Set the stat types and groups.
>>> stats = ['season', 'seasonAdvanced']
>>> groups = ['hitting']
>>> params = {'season': 2022}
Use team.id and the stat types and groups to return season hitting stats
stats = mlb.get_team_stats(team_id, stats=stats, groups=groups, **params)
season_hitting = stats['hitting']['season']
advanced_hitting = stats['hitting']['seasonadvanced']
Print season and seasonadvanced stats
>>> for split in season_hitting.splits:
... for k, v in split.stat.__dict__.items():
... print(k, v)
gamesplayed 162
groundouts 1273
airouts 1523
runs 690
doubles 229
triples 19
>>>
>>> for split in advanced_hitting.splits:
... for k, v in split.stat.__dict__.items():
... print(k, v)
...
plateappearances 6117
totalbases 2094
leftonbase 1129
sacbunts 9
sacflies 45
More stats examples
Expected Stats
Get player Id's
>>> player_id = mlb.get_people_id('Ty France')[0]
Set the stat type and group
>>> stats = ['expectedStatistics']
>>> group = ['hitting']
>>> params = {'season': 2022}
Get Stats
>>> stats = mlb.get_player_stats(player_id, stats=stats, groups=group, **params)
>>> expectedstats = stats['hitting']['expectedstatistics']
>>> for split in expectedstats.splits:
... for k, v in split.stat.__dict__.items():
... print(k, v)
avg .259
slg .394
woba .317
wobacon .338
vsPlayer
Get pitcher and batter player Ids
>>> ty_france_id = mlb.get_people_id('Ty France')[0]
>>> shohei_ohtani_id = mlb.get_people_id('Shohei Ohtani')[0]
Set stat type, stat groups, and params
>>> stats = ['vsPlayer']
>>> group = ['hitting']
>>> params = {'opposingPlayerId': shohei_ohtani_id, 'season': 2022}
Get stats
>>> stats = mlb.get_player_stats(ty_france_id, stats=stats, groups=group, **params)
>>> vs_player_total = stats['hitting']['vsplayertotal']
>>> for split in vs_player_total.splits:
... for k, v in split.stat.__dict__.items():
... print(k, v)
gamesplayed 4
groundouts 3
airouts 4
runs None
doubles 1
triples 0
homeruns 0
...
>>> vs_player = stats['hitting']['vsplayer']
>>> for split in vs_player.splits:
... for k, v in split.stat.__dict__.items():
... print(k, v)
gamesplayed 2
groundouts 1
airouts 2
runs None
doubles 1
triples 0
homeruns 0
hotColdZones
Get player Id's
>>> ty_france_id = mlb.get_people_id('Ty France')[0]
>>> shohei_ohtani_id = mlb.get_people_id('Shohei Ohtani')[0]
Set the stat types and groups
>>> stats = ['hotColdZones']
>>> hitting_group = ['hitting']
>>> pitching_group = ['pitching']
>>> params = {'season': 2022}
The stat groups pitching and hitting both return hotColdZones for a pitcher and hitter. hotColdZones are not assigned to a stat group because of issues related to the REST API. So hotColdZones will be assigned to the stat key in stats return dict.
>>> hitting_hotcoldzones = mlb.get_player_stats(ty_france_id stats=stats, groups=hitting_group, **params)
>>> pitching_hotcoldzones = mlb.get_player_stats(shohei_ohtani_id, stats=stats, groups=pitching_group, **params)
hotColdZones returns a list of the HotColdZones
>>> ty_france_hotcoldzones = hitting_hotcoldzones['stats']['hotcoldzones']
>>> shohei_ohtani_hotcoldzones = pitching_hotcoldzones['stats']['hotcoldzones']
Loop through hotColdZone objects for Ty France
>>> for split in ty_france_hotcoldzones.splits:
... print(split.stat.name)
...
onBasePercentage
onBasePlusSlugging
sluggingPercentage
exitVelocity
battingAverage
Loop through hotColdZone objects for Shoei Ohtani
>>> for split in shohei_ohtani_hotcoldzones.splits:
... print(split.stat.name)
...
onBasePercentage
onBasePlusSlugging
sluggingPercentage
exitVelocity
battingAverage
Print zone information for obp
>>> for split in ty_france_hotcoldzones.splits:
... if split.stat.name == 'onBasePercentage':
... for zone in split.stat.zones:
... print('zone: ', zone.zone)
... print('value: ', zone.value)
zone: 01
value: .226
zone: 02
value: .400
zone: 03
value: .375
zone: 04
Passing params
Get Team Ids
python3
>>> mlb = mlbstatsapi.Mlb()
>>> team_id = mlb.get_team_id('Seattle Mariners')[0]
Set the stat types and groups.
>>> stats = ['season', 'seasonAdvanced']
>>> groups = ['hitting']
>>> params = {'season': 2022}
Pass season to get_team_stats()
stats = mlb.get_team_stats(team_id, stats=stats, groups=groups, **params)
season_hitting = stats['hitting']['season']
advanced_hitting = stats['hitting']['seasonadvanced']
season should be 2018
>>> for split in season_hitting.splits:
... print('Season: ', split.season)
... for k, v in split.stat.__dict__.items():
... print(k, v)
...
Season: 2018
gamesplayed 162
groundouts 1535
airouts 1425
runs 677
...
>>> for split in advanced_hitting.splits:
... print('Season: ', split.season)
... for k, v in split.stat.__dict__.items():
... print(k, v)
...
Season: 2018
plateappearances 6087
totalbases 2250
leftonbase 1084
sacbunts 29
sacflies 41
...
Gamepace examples
Get pace of game metrics for specific sport, league or team.
>>> mlb = mlbstatsapi.Mlb()
>>> season = 2021
>>> gamepace = mlb.get_gamepace(season)
Schedule Examples
Get a schedule for given date
>>> mlb = mlbstatsapi.Mlb()
>>> schedule = mlb.get_schedule_date('2022-10-13')
Get ScheduleDates from Schedule
dates = schedule.dates
Print Game status and Home and Away Teams
>>> for date in dates:
... for game in date.games:
... print(game.status)
... print(game.teams.home)
... print(game.teams.away)
Game Examples
Get a Game for a given game id
>>> mlb = mlbstatsapi.Mlb()
>>> game = mlb.get_game(662242)
Get the weather for a game for a given game id
>>> mlb = mlbstatsapi.Mlb()
>>> game = mlb.get_game(662242)
>>> weather = game.gamedata.weather
>>>
>>> print(weather.condition)
>>> print(weather.temp)
>>> print(weather.wind)
Get the current status of a game for a given game id
>>> mlb = mlbstatsapi.mlb()
>>> game = mlb.get_game(662242)
>>>
>>> linescore = game.livedata.linescore
>>> hometeaminfo = game.gamedata.teams.home
>>> awayteaminfo = game.gamedata.teams.away
>>> hometeamstatus = linescore.teams.home
>>> awayteamstatus = linescore.teams.away
>>>
>>> print("home: ", hometeaminfo.franchisename, hometeaminfo.clubname)
>>> print(" runs:", hometeamstatus.runs)
>>> print(" hits:", hometeamstatus.hits)
>>> print(" errors:", hometeamstatus.errors)
>>> print("away: ", awayteaminfo.franchisename, awayteaminfo.clubname)
>>> print(" runs:", awayteamstatus.runs)
>>> print(" hits:", awayteamstatus.hits)
>>> print(" errors:", awayteamstatus.errors)
>>> print("")
>>> print("inning:", linescore.inninghalf, linescore.currentinningordinal)
>>> print("balls:", linescore.balls)
>>> print("strikes:", linescore.strikes)
>>> print("Outs:", linescore.outs)
Get the play by play, line score, and box score objects from a game
>>> mlb = mlbstatsapi.Mlb()
>>> game = mlb.get_game(662242)
>>>
>>> play_by_play = game.livedata.plays
>>> line_score = game.livedata.linescore
>>> box_score = game.livedata.boxscore
Play by Play
Get only the play by play for a given game id
>>> mlb = mlbstatsapi.Mlb()
>>> playbyplay = mlb.get_play_by_play(662242)
Line Score
Get only the line score for a given game id
>>> mlb = mlbstatsapi.Mlb()
>>> linescore = mlb.get_line_score(662242)
Box Score
Get only the box score for a given game id
>>> mlb = mlbstatsapi.Mlb()
>>> boxscore = mlb.get_box_score(662242)
People Examples
Get all Players for a given sport id
>>> mlb = mlbstatsapi.Mlb()
>>> sport_id = mlb.get_sport_id()
>>> players = mlb.get_players(sport_id=sport_id)
>>> for player in players:
... print(player.id)
Get a player id
>>> player_id = mlb.get_people_id("Ty France")
>>> print(player_id[0])
>>> [664034]
Team Examples
Get a Team
>>> mlb = mlbstatsapi.Mlb()
>>> team_ids = mlb.get_team_id("Seattle Mariners")
>>> team_id = team_ids[0]
>>> team = mlb.get_team(team_id.id)
>>> print(team.id)
>>> print(team.name)
Get a Player Roster
>>> mlb = mlbstatsapi.Mlb()
>>> team_id = 133
>>> players = mlb.get_team_roster(team_id)
>>> for player in players:
print(player.jerseynumber)
Get a Coach Roster
>>> mlb = mlbstatsapi.Mlb()
>>> team_id = 133
>>> coaches = mlb.get_team_coaches(team_id)
>>> for coach in coaches:
print(coach.title)
Draft Examples
Get a draft for a year
>>> mlb = mlbstatsapi.Mlb()
>>> draft_year = '2019'
>>> draft = mlb.get_draft(draft_year)
Get Players from Draft
>>> draftpicks = draft[0].picks
>>> for draftpick in draftpicks:
... print(draftpick.id)
... print(draftpick.pickround)
Award Examples
Get awards for a given award id
>>> mlb = mlbstatsapi.Mlb()
>>> retiredjersy = self.mlb.get_awards(award_id='RETIREDUNI_108')
>>> for recipient in retiredjersy.awards:
... print (recipient.player.nameFirstLast, recipient.name, recipient.date)
Venue Examples
Get a Venue
>>> mlb = mlbstatsapi.Mlb()
>>> vevue_ids = mlb.get_venue_id('PNC Park')
>>> venue_id = venue_ids[0]
>>> venue = mlb.get_team(venue.id)
>>> print(venue.id)
>>> print(venue.name)
Sport Examples
Get a Sport
>>> mlb = mlbstatsapi.Mlb()
>>> sport_ids = mlb.get_sport_id('Major League Baseball')
>>> sport_id = sport_ids[0]
>>> sport = mlb.get_sport(sport_id)
Division Examples
Get a division
>>> mlb = mlbstatsapi.Mlb()
>>> division = mlb.get_division(200)
>>> print(division.name)
League Examples
Get a league
>>> mlb = mlbstatsapi.Mlb()
>>> league = mlb.get_league(103)
>>> print(league.name)
Season Examples
Get a Season
>>> mlb = mlbstatsapi.Mlb()
>>> season = mlb.get_season(2018)
>>> print(season.seasonid)
Standings Examples
Get a Standings
>>> mlb = mlbstatsapi.Mlb()
>>> standings = mlb.get_standings(103, 2018)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file python_mlb_statsapi-0.5.25.tar.gz
.
File metadata
- Download URL: python_mlb_statsapi-0.5.25.tar.gz
- Upload date:
- Size: 65.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.7
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 75406a74584d9388720d051b183b8419b1bbda27ea4a68870656d6fc4c0b2a87 |
|
MD5 | 41e09f364c3d94f82da45d0dfcaa9d6c |
|
BLAKE2b-256 | 72e1d59d6886a8a070656ee30361a058935fee09eedfce2db395b1f41eef7754 |
File details
Details for the file python_mlb_statsapi-0.5.25-py3-none-any.whl
.
File metadata
- Download URL: python_mlb_statsapi-0.5.25-py3-none-any.whl
- Upload date:
- Size: 90.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.7
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8abf4ab224210529a96007b49a5a2768f5b4c92dbebcc94b02dfc0241ee567d5 |
|
MD5 | 5f246382d0fd97984a68af1d3ae221fb |
|
BLAKE2b-256 | 098017f4eba106acc3f2c890ae22343b559ea6cd5ef240a8ede66e8cc9e3fe30 |