get_schedule
Get list of games for a given date/range and/or team/opponent.
get_player_stats
Returns a list of current season or career stat data for a given player.
get_standings
Returns a dict of standings data for a given league/division and season.
get_team_leaders
Returns a python list of stat leader data for a given team
lookup_player
Get data about players based on first, last, or full name.
get_boxscore
Get a formatted boxscore for a given game.
get_team_roster
Get the roster for a given team.
get_game_pace
Returns data about pace of game for a given season (back to 1999).
get_meta
Get available values from StatsAPI for use in other queries,
or look up descriptions for values found in API results.
For example, to get a list of leader categories to use when calling team_leaders():
statsapi.meta('leagueLeaderTypes')
get_available_endpoints
Get MLB StatsAPI endpoints directly
get_notes
Get additional notes on an endpoint
get_game_scoring_play_data
Returns a dictionary of scoring plays for a given game containing 3 keys:
* home - home team data
* away - away team data
* plays - sorted list of scoring play data
get_last_game
Get the gamePk (game_id) for the given team's most recent completed game.
get_league_leader_data
Returns a list of stat leaders overall or for a given league (103=AL, 104=NL).
get_linescore
Get formatted linescore data for a specific MLB game.
get_next_game
Get the game ID for a team's next scheduled game.
get_game_highlight_data
Returns a list of highlight data for a given game.
get_statcast_data
Pulls statcast play-level data from Baseball Savant for a given date range.
INPUTS:
start_dt: YYYY-MM-DD : the first date for which you want statcast data
end_dt: YYYY-MM-DD : the last date for which you want statcast data
team: optional (defaults to None) :
city abbreviation of the team you want data for (e.g. SEA or BOS)
verbose: bool (defaults to True) :
whether to print updates on query progress
parallel: bool (defaults to True) :
whether to parallelize HTTP requests in large queries
start_row: optional (defaults to None) :
starting row index for truncating large results (0-based, inclusive)
end_row: optional (defaults to None) :
ending row index for truncating large results (0-based, exclusive)
Use start_row and end_row to limit response size when dealing with large datasets.
If no arguments are provided, this will return yesterday's statcast data.
If one date is provided, it will return that date's statcast data.
get_statcast_batter_data
Pulls statcast pitch-level data from Baseball Savant for a given batter.
ARGUMENTS
start_dt : YYYY-MM-DD :
the first date for which you want a player's statcast data
end_dt : YYYY-MM-DD : the final date for which you want data
player_id : INT :
the player's MLBAM ID.
Find this by via the get_playerid_lookup tool,
finding the correct player, and selecting their key_mlbam.
start_row: optional (defaults to None) :
starting row index for truncating large results (0-based, inclusive)
end_row: optional (defaults to None) :
ending row index for truncating large results (0-based, exclusive)
Use start_row and end_row to limit response size when dealing with large datasets.
get_statcast_pitcher_data
Pulls statcast pitch-level data from Baseball Savant for a given pitcher.
ARGUMENTS
start_dt : YYYY-MM-DD :
the first date for which you want a player's statcast data
end_dt : YYYY-MM-DD : the final date for which you want data
player_id : INT :
the player's MLBAM ID.
Find this by calling pthe get_playerid_lookup tool,
finding the correct player, and selecting their key_mlbam.
start_row: optional (defaults to None) :
starting row index for truncating large results (0-based, inclusive)
end_row: optional (defaults to None) :
ending row index for truncating large results (0-based, exclusive)
Use start_row and end_row to limit response size when dealing with large datasets.
get_statcast_batter_exitvelo_barrels
Retrieves batted ball data for all batters in a given year.
ARGUMENTS
year: The year for which you wish to retrieve batted ball data. Format: YYYY.
minBBE:
The minimum number of batted ball events for each player.
If a player falls below this threshold, they will be excluded from the results.
If no value is specified, only qualified batters will be returned.
start_row: optional (defaults to None) :
starting row index for truncating large results (0-based, inclusive)
end_row: optional (defaults to None) :
ending row index for truncating large results (0-based, exclusive)
Use start_row and end_row to limit response size when dealing with large datasets.
get_statcast_pitcher_exitvelo_barrels
Retrieves batted ball against data for all qualified pitchers in a given year.
ARGUMENTS
year: The year for which you wish to retrieve batted ball against data. Format: YYYY.
minBBE:
The minimum number of batted ball against events for each pitcher.
If a player falls below this threshold, they will be excluded from the results.
If no value is specified, only qualified pitchers will be returned.
start_row: optional (defaults to None) :
starting row index for truncating large results (0-based, inclusive)
end_row: optional (defaults to None) :
ending row index for truncating large results (0-based, exclusive)
Use start_row and end_row to limit response size when dealing with large datasets.
get_statcast_batter_expected_stats
Retrieves expected stats based on quality of batted ball contact in a given year.
ARGUMENTS
year: The year for which you wish to retrieve expected stats data. Format: YYYY.
minPA: The minimum number of plate appearances for each player.
If a player falls below this threshold, they will be excluded from the results.
If no value is specified, only qualified batters will be returned.
start_row: optional (defaults to None) :
starting row index for truncating large results (0-based, inclusive)
end_row: optional (defaults to None) :
ending row index for truncating large results (0-based, exclusive)
Use start_row and end_row to limit response size when dealing with large datasets.
get_statcast_pitcher_expected_stats
Retrieves expected stats based on quality of batted ball contact against in a given year.
ARGUMENTS
year: The year for which you wish to retrieve expected stats data. Format: YYYY.
minPA: The minimum number of plate appearances against for each pitcher.
If a player falls below this
threshold, they will be excluded from the results.
If no value is specified, only qualified pitchers
will be returned.
start_row: optional (defaults to None) :
starting row index for truncating large results (0-based, inclusive)
end_row: optional (defaults to None) :
ending row index for truncating large results (0-based, exclusive)
Use start_row and end_row to limit response size when dealing with large datasets.
get_statcast_batter_percentile_ranks
Retrieves percentile ranks for batters in a given year.
ARGUMENTS
year: The year for which you wish to retrieve percentile data. Format: YYYY.
start_row: optional (defaults to None) :
starting row index for truncating large results (0-based, inclusive)
end_row: optional (defaults to None) :
ending row index for truncating large results (0-based, exclusive)
Use start_row and end_row to limit response size when dealing with large datasets.
get_statcast_pitcher_percentile_ranks
Retrieves percentile ranks for each player in a given year,
including batters with 2.1 PA per team game and 1.25
for pitchers. It includes percentiles on expected stats,
batted ball data, and spin rates, among others.
ARGUMENTS
year: The year for which you wish to retrieve percentile data. Format: YYYY.
start_row: optional (defaults to None) :
starting row index for truncating large results (0-based, inclusive)
end_row: optional (defaults to None) :
ending row index for truncating large results (0-based, exclusive)
Use start_row and end_row to limit response size when dealing with large datasets.
get_statcast_batter_pitch_arsenal
Retrieves outcome data for batters split by the pitch type in a given year.
ARGUMENTS
year: The year for which you wish to retrieve pitch arsenal data. Format: YYYY.
minPA: The minimum number of plate appearances for each player.
If a player falls below this threshold,
they will be excluded from the results.
If no value is specified, the default number of plate appearances is 25.
start_row: optional (defaults to None) :
starting row index for truncating large results (0-based, inclusive)
end_row: optional (defaults to None) :
ending row index for truncating large results (0-based, exclusive)
Use start_row and end_row to limit response size when dealing with large datasets.
get_statcast_pitcher_pitch_arsenal
Retrieves high level stats on each pitcher's arsenal in a given year.
ARGUMENTS
year: The year for which you wish to retrieve expected stats data. Format: YYYY.
minP: The minimum number of pitches thrown.
If a player falls below this threshold, they will be excluded
from the results. If no value is specified, only qualified pitchers will be returned.
arsenal_type:
The type of stat to retrieve for the pitchers' arsenals.
Options include ["average_speed", "n_", "average_spin"],
where "n_" corresponds to the percentage share for each pitch.
If no value is specified, it will default to average speed.
start_row: optional (defaults to None) :
starting row index for truncating large results (0-based, inclusive)
end_row: optional (defaults to None) :
ending row index for truncating large results (0-based, exclusive)
Use start_row and end_row to limit response size when dealing with large datasets.
get_statcast_single_game
Pulls statcast play-level data from Baseball Savant for a single game,
identified by its MLB game ID (game_pk in statcast data)
INPUTS:
game_pk : 6-digit integer MLB game ID to retrieve
start_row: optional (defaults to None) :
starting row index for truncating large results (0-based, inclusive)
end_row: optional (defaults to None) :
ending row index for truncating large results (0-based, exclusive)
Use start_row and end_row to limit response size when dealing with large datasets.
create_strike_zone_plot
Produces a pitches overlaid on a strike zone using StatCast data
Args:
data: (pandas.DataFrame)
StatCast pandas.DataFrame of StatCast pitcher data
title: (str), default = ''
Optional: Title of plot
colorby: (str), default = 'pitch_type'
Optional: Which category to color the mark with.
'pitch_type', 'pitcher', 'description' or a column within data
legend_title: (str), default = based on colorby
Optional: Title for the legend
annotation: (str), default = 'pitch_type'
Optional: What to annotate in the marker.
'pitch_type', 'release_speed', 'effective_speed',
'launch_speed', or something else in the data
create_spraychart_plot
Produces a spraychart using statcast data overlayed on specified stadium
Args:
data: (pandas.DataFrame)
StatCast pandas.DataFrame of StatCast batter data
team_stadium: (str)
Team whose stadium the hits will be overlaid on
title: (str), default = ''
Optional: Title of plot
size: (int), default = 100
Optional: Size of hit circles on plot
colorby: (str), default = 'events'
Optional: Which category to color the mark with.
'events','player', or a column within data
legend_title: (str), default = based on colorby
Optional: Title for the legend
width: (int), default = 500
Optional: Width of plot (not counting the legend)
height: (int), default = 500
Optional: Height of plot
create_bb_profile_plot
Plots a given StatCast parameter split by bb_type
Args:
df: (pandas.DataFrame)
pandas.DataFrame of StatCast batter data
(retrieved through statcast, statcast_batter, etc)
parameter: (str), default = 'launch_angle'
Optional: Parameter to plot
create_teams_plot
Plots a scatter plot with each MLB team
Args:
data: (pandas.DataFrame)
pandas.DataFrame of Fangraphs team data
(retrieved through team_batting or team_pitching)
x_axis: (str)
Stat name to be plotted as the x_axis of the chart
y_axis: (str)
Stat name to be plotted as the y_axis of the chart
title: (str), default = None
Optional: Title of the plot
get_pitching_stats_bref
Get all pitching stats for a set season. If no argument is supplied, gives stats for
current season to date.
get_pitching_stats_range
Get all pitching stats for a set time range. This can be the past week, the
month of August, anything. Just supply the start and end date in YYYY-MM-DD
format.
get_pitching_stats
Get season-level pitching data from FanGraphs.
Args:
start_season: First season to retrieve data from
end_season: Final season to retrieve data from.
If None, returns only start_season.
league: Either "all", "nl", "al", or "mnl"
qual: Minimum number of plate appearances to be included
ind: 1 for individual season level, 0 for aggregate data
Returns:
Dictionary containing pitching stats from FanGraphs
get_playerid_lookup
Lookup playerIDs (MLB AM, bbref, retrosheet, FG) for a given player
Args:
last (str, required): Player's last name.
first (str, optional): Player's first name. Defaults to None.
fuzzy (bool, optional): In case of typos, returns players with names close to input.
Defaults to False.
Returns:
pd.DataFrame: DataFrame of playerIDs, name, years played
reverse_lookup_player
Retrieve a table of player information given a list of player ids
:param player_ids: list of player ids
:type player_ids: list
:param key_type: name of the key type being looked up
(one of "mlbam", "retro", "bbref", or "fangraphs")
:type key_type: str
:rtype: :class:`pandas.core.frame.DataFrame`
get_schedule_and_record
Retrieve a team's game-level results for a given season,
including win/loss/tie result, score, attendance,
and winning/losing/saving pitcher. If the season is incomplete,
it will provide scheduling information for
future games.
ARGUMENTS
season: Integer. The season for which you want a team's record data.
team: String.
The abbreviation of the team for which you are requesting data (e.g. "PHI", "BOS", "LAD").
get_player_splits
Returns a dataframe of all split stats for a given player.
If player_info is True, this will also return a dictionary that includes player position,
handedness, height, weight, position, and team
get_pybaseball_standings
Returns a pandas DataFrame of the standings for a given MLB season, or the most recent standings
if the date is not specified.
ARGUMENTS
season (int): the year of the season
get_team_batting
Get season-level Batting Statistics for Specific Team (from Baseball-Reference)
ARGUMENTS:
team : str : The Team Abbreviation (i.e. 'NYY' for Yankees) of the Team you want data for
start_season : int : first season you want data for
(or the only season if you do not specify an end_season)
end_season : int : final season you want data for
get_team_fielding
Get season-level Fielding Statistics for Specific Team (from Baseball-Reference)
ARGUMENTS:
team : str : The Team Abbreviation (i.e., 'NYY' for Yankees) of the
Team you want data for
start_season : int : first season you want data for
(or the only season if you do not specify an end_season)
end_season : int : final season you want data for
get_team_pitching
Get season-level Pitching Statistics for Specific Team (from Baseball-Reference)
ARGUMENTS:
team : str : The Team Abbreviation (i.e. 'NYY' for Yankees) of the Team you want data for
start_season : int : first season you want data for
(or the only season if you do not specify an end_season)
end_season : int : final season you want data for
get_top_prospects
Retrieves the top prospects by team or leaguewide.
It can return top prospect pitchers, batters, or both.
ARGUMENTS
team: The team name for which you wish to retrieve top prospects. If not specified,
the function will return leaguewide top prospects.
playerType: Either "pitchers" or "batters".
If not specified, the function will return top prospects for both
pitchers and batters.