Skip to main content

MLB — MLB Statcast (Baseball Savant) — Other

mlb_statcast_gamefeed​

GET /gf — Savant per-game JSON feed (pitch-by-pitch tracking).

Endpoint URL: GET https://baseballsavant.mlb.com/gf

Valid URL: https://baseballsavant.mlb.com/gf

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk query parameter.
at_bat_numberat_bat_numberYat_bat_number query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
typeStringRecord/pitch type.
yearStringSeason year.
sport_idStringSport id.
play_idStringStatcast play UUID.
inningStringInning.
half_inningStringHalf inning.
ab_numberStringAb number.
cap_indexStringCap index.
outsStringOuts.
batterInt64MLBAM id of the batter.
standStringBatter stance side (R/L).
batter_nameStringBatter name.
pitcherInt64MLBAM id of the pitcher.
p_throwsStringPitcher throwing hand (R/L).
pitcher_nameStringPitcher name.
catcherStringCatcher.
catcher_nameStringCatcher name.
team_battingStringTeam batting.
team_fieldingStringTeam fielding.
team_batting_idStringTeam batting id.
team_fielding_idStringTeam fielding id.
resultStringResult.
desStringDes.
eventsStringEvents.
strikesStringStrikes.
ballsStringBalls.
pre_strikesStringPre strikes.
pre_ballsStringPre balls.
callStringCall.
call_nameStringCall name.
pitch_typeStringPitch type code.
pitch_nameStringPitch type name.
descriptionStringDescription.
result_codeStringResult code.
pitch_callStringPitch call.
is_strike_swingingStringIs strike swinging.
balls_and_strikesStringBalls and strikes.
start_speedStringStart speed.
end_speedStringEnd speed.
sz_topStringSz top.
sz_botStringSz bot.
extensionStringRelease extension (ft).
plate_timeStringPlate time.
zoneStringZone.
spin_rateStringSpin rate (rpm).
break_xStringBreak x.
induced_break_zStringInduced break z.
break_zStringBreak z.
pxStringPx.
pzStringPz.
pfx_xStringHorizontal movement (in, pitcher perspective).
pfx_zStringInduced vertical movement (in).
is_bip_outStringIs bip out.
pitch_numberStringPitch number.
plate_xStringPlate x.
plate_zStringPlate z.
hit_speedStringHit speed.
hit_distanceStringHit distance.
xbaStringExpected batting average.
hit_angleStringHit angle.
is_barrelStringIs barrel.
hc_xStringHc x.
hc_yStringHc y.
launch_speedStringExit velocity of the batted ball (mph).
launch_angleStringLaunch angle (deg).
game_total_pitchesStringGame total pitches.
game_pkInt64MLBAM game id.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_statcast_gamefeed()

mlb_statcast_schedule​

GET /schedule — Savant schedule feed (one row per game).

Endpoint URL: GET https://baseballsavant.mlb.com/schedule

Valid URL: https://baseballsavant.mlb.com/schedule

API ParameterPythonPatternRequiredNullableDescription
datedateYdate query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
game_pkInt64MLBAM game id.
game_guidStringGame GUID.
linkStringStats API resource link.
game_typeStringGame type code (R/F/D/L/W/S/E/A).
seasonStringSeason year.
game_dateStringGame date/time (ISO 8601, UTC offset).
official_dateStringOfficial game date (YYYY-MM-DD).
game_numberInt64Game number (1, or 2 for the nightcap of a doubleheader).
public_facingBooleanPublic facing.
double_headerStringDoubleheader flag (Y/N/S).
gameday_typeStringGameday type.
tiebreakerStringTiebreaker.
calendar_event_idStringCalendar event id.
season_displayStringSeason display.
day_nightStringDay or night game.
scheduled_inningsInt64Scheduled innings (usually 9).
reverse_home_away_statusBooleanReverse home away status.
inning_break_lengthInt64Inning break length.
games_in_seriesInt64Total games in the series.
series_game_numberInt64Game number within the series.
series_descriptionStringSeries description.
record_sourceStringRecord source.
if_necessaryStringIf necessary.
if_necessary_descriptionStringIf necessary description.
status_abstract_game_stateStringStatus abstract game state.
status_coded_game_stateStringStatus coded game state.
status_detailed_stateStringStatus detailed state.
status_status_codeStringStatus status code.
status_start_time_tbdBooleanStatus start time tbd.
status_abstract_game_codeStringStatus abstract game code.
teams_away_team_spring_league_idInt64Away team team spring league id.
teams_away_team_spring_league_nameStringAway team team spring league name.
teams_away_team_spring_league_linkStringAway team team spring league link.
teams_away_team_spring_league_abbreviationStringAway team team spring league abbreviation.
teams_away_team_all_star_statusStringAway team team all star status.
teams_away_team_idInt64Away team team id.
teams_away_team_nameStringAway team team name.
teams_away_team_linkStringAway team team link.
teams_away_team_seasonInt64Away team team season.
teams_away_team_venue_idInt64Away team team venue id.
teams_away_team_venue_nameStringAway team team venue name.
teams_away_team_venue_linkStringAway team team venue link.
teams_away_team_spring_venue_idInt64Away team team spring venue id.
teams_away_team_spring_venue_linkStringAway team team spring venue link.
teams_away_team_team_codeStringAway team team team code.
teams_away_team_file_codeStringAway team team file code.
teams_away_team_abbreviationStringAway team team abbreviation.
teams_away_team_team_nameStringAway team team team name.
teams_away_team_location_nameStringAway team team location name.
teams_away_team_first_year_of_playStringAway team team first year of play.
teams_away_team_league_idInt64Away team team league id.
teams_away_team_league_nameStringAway team team league name.
teams_away_team_league_linkStringAway team team league link.
teams_away_team_division_idInt64Away team team division id.
teams_away_team_division_nameStringAway team team division name.
teams_away_team_division_linkStringAway team team division link.
teams_away_team_sport_idInt64Away team team sport id.
teams_away_team_sport_linkStringAway team team sport link.
teams_away_team_sport_nameStringAway team team sport name.
teams_away_team_short_nameStringAway team team short name.
teams_away_team_franchise_nameStringAway team team franchise name.
teams_away_team_club_nameStringAway team team club name.
teams_away_team_activeBooleanAway team team active.
teams_away_league_record_winsInt64Away team league record wins.
teams_away_league_record_lossesInt64Away team league record losses.
teams_away_league_record_tiesInt64Away team league record ties.
teams_away_league_record_pctStringAway team league record rate.
teams_away_probable_pitcher_idInt64Away team probable pitcher id.
teams_away_probable_pitcher_full_nameStringAway team probable pitcher full name.
teams_away_probable_pitcher_linkStringAway team probable pitcher link.
teams_away_probable_pitcher_first_nameStringAway team probable pitcher first name.
teams_away_probable_pitcher_last_nameStringAway team probable pitcher last name.
teams_away_probable_pitcher_primary_numberStringAway team probable pitcher primary number.
teams_away_probable_pitcher_birth_dateStringAway team probable pitcher birth date.
teams_away_probable_pitcher_current_ageInt64Away team probable pitcher current age.
teams_away_probable_pitcher_birth_cityStringAway team probable pitcher birth city.
teams_away_probable_pitcher_birth_state_provinceStringAway team probable pitcher birth state province.
teams_away_probable_pitcher_birth_countryStringAway team probable pitcher birth country.
teams_away_probable_pitcher_heightStringAway team probable pitcher height.
teams_away_probable_pitcher_weightInt64Away team probable pitcher weight.
teams_away_probable_pitcher_activeBooleanAway team probable pitcher active.
teams_away_probable_pitcher_primary_position_codeStringAway team probable pitcher primary position code.
teams_away_probable_pitcher_primary_position_nameStringAway team probable pitcher primary position name.
teams_away_probable_pitcher_primary_position_typeStringAway team probable pitcher primary position type.
teams_away_probable_pitcher_primary_position_abbreviationStringAway team probable pitcher primary position abbreviation.
teams_away_probable_pitcher_use_nameStringAway team probable pitcher use name.
teams_away_probable_pitcher_use_last_nameStringAway team probable pitcher use last name.
teams_away_probable_pitcher_middle_nameStringAway team probable pitcher middle name.
teams_away_probable_pitcher_boxscore_nameStringAway team probable pitcher boxscore name.
teams_away_probable_pitcher_genderStringAway team probable pitcher gender.
teams_away_probable_pitcher_is_playerBooleanAway team probable pitcher is player.
teams_away_probable_pitcher_is_verifiedBooleanAway team probable pitcher is verified.
teams_away_probable_pitcher_draft_yearInt64Away team probable pitcher draft year.
teams_away_probable_pitcher_mlb_debut_dateStringAway team probable pitcher mlb debut date.
teams_away_probable_pitcher_bat_side_codeStringAway team probable pitcher bat side code.
teams_away_probable_pitcher_bat_side_descriptionStringAway team probable pitcher bat side description.
teams_away_probable_pitcher_pitch_hand_codeStringAway team probable pitcher pitch hand code.
teams_away_probable_pitcher_pitch_hand_descriptionStringAway team probable pitcher pitch hand description.
teams_away_probable_pitcher_name_first_lastStringAway team probable pitcher name first last.
teams_away_probable_pitcher_name_slugStringAway team probable pitcher name slug.
teams_away_probable_pitcher_first_last_nameStringAway team probable pitcher first last name.
teams_away_probable_pitcher_last_first_nameStringAway team probable pitcher last first name.
teams_away_probable_pitcher_last_init_nameStringAway team probable pitcher last init name.
teams_away_probable_pitcher_init_last_nameStringAway team probable pitcher init last name.
teams_away_probable_pitcher_full_fml_nameStringAway team probable pitcher full fml name.
teams_away_probable_pitcher_full_lfm_nameStringAway team probable pitcher full lfm name.
teams_away_probable_pitcher_strike_zone_topFloat64Away team probable pitcher strike zone top.
teams_away_probable_pitcher_strike_zone_bottomFloat64Away team probable pitcher strike zone bottom.
teams_away_split_squadBooleanAway team split squad.
teams_away_series_numberInt64Away team series number.
teams_away_spring_league_idInt64Away team spring league id.
teams_away_spring_league_nameStringAway team spring league name.
teams_away_spring_league_linkStringAway team spring league link.
teams_away_spring_league_abbreviationStringAway team spring league abbreviation.
teams_home_team_spring_league_idInt64Home team team spring league id.
teams_home_team_spring_league_nameStringHome team team spring league name.
teams_home_team_spring_league_linkStringHome team team spring league link.
teams_home_team_spring_league_abbreviationStringHome team team spring league abbreviation.
teams_home_team_all_star_statusStringHome team team all star status.
teams_home_team_idInt64Home team team id.
teams_home_team_nameStringHome team team name.
teams_home_team_linkStringHome team team link.
teams_home_team_seasonInt64Home team team season.
teams_home_team_venue_idInt64Home team team venue id.
teams_home_team_venue_nameStringHome team team venue name.
teams_home_team_venue_linkStringHome team team venue link.
teams_home_team_spring_venue_idInt64Home team team spring venue id.
teams_home_team_spring_venue_linkStringHome team team spring venue link.
teams_home_team_team_codeStringHome team team team code.
teams_home_team_file_codeStringHome team team file code.
teams_home_team_abbreviationStringHome team team abbreviation.
teams_home_team_team_nameStringHome team team team name.
teams_home_team_location_nameStringHome team team location name.
teams_home_team_first_year_of_playStringHome team team first year of play.
teams_home_team_league_idInt64Home team team league id.
teams_home_team_league_nameStringHome team team league name.
teams_home_team_league_linkStringHome team team league link.
teams_home_team_division_idInt64Home team team division id.
teams_home_team_division_nameStringHome team team division name.
teams_home_team_division_linkStringHome team team division link.
teams_home_team_sport_idInt64Home team team sport id.
teams_home_team_sport_linkStringHome team team sport link.
teams_home_team_sport_nameStringHome team team sport name.
teams_home_team_short_nameStringHome team team short name.
teams_home_team_franchise_nameStringHome team team franchise name.
teams_home_team_club_nameStringHome team team club name.
teams_home_team_activeBooleanHome team team active.
teams_home_league_record_winsInt64Home team league record wins.
teams_home_league_record_lossesInt64Home team league record losses.
teams_home_league_record_tiesInt64Home team league record ties.
teams_home_league_record_pctStringHome team league record rate.
teams_home_probable_pitcher_idInt64Home team probable pitcher id.
teams_home_probable_pitcher_full_nameStringHome team probable pitcher full name.
teams_home_probable_pitcher_linkStringHome team probable pitcher link.
teams_home_probable_pitcher_first_nameStringHome team probable pitcher first name.
teams_home_probable_pitcher_last_nameStringHome team probable pitcher last name.
teams_home_probable_pitcher_primary_numberStringHome team probable pitcher primary number.
teams_home_probable_pitcher_birth_dateStringHome team probable pitcher birth date.
teams_home_probable_pitcher_current_ageInt64Home team probable pitcher current age.
teams_home_probable_pitcher_birth_cityStringHome team probable pitcher birth city.
teams_home_probable_pitcher_birth_state_provinceStringHome team probable pitcher birth state province.
teams_home_probable_pitcher_birth_countryStringHome team probable pitcher birth country.
teams_home_probable_pitcher_heightStringHome team probable pitcher height.
teams_home_probable_pitcher_weightInt64Home team probable pitcher weight.
teams_home_probable_pitcher_activeBooleanHome team probable pitcher active.
teams_home_probable_pitcher_primary_position_codeStringHome team probable pitcher primary position code.
teams_home_probable_pitcher_primary_position_nameStringHome team probable pitcher primary position name.
teams_home_probable_pitcher_primary_position_typeStringHome team probable pitcher primary position type.
teams_home_probable_pitcher_primary_position_abbreviationStringHome team probable pitcher primary position abbreviation.
teams_home_probable_pitcher_use_nameStringHome team probable pitcher use name.
teams_home_probable_pitcher_use_last_nameStringHome team probable pitcher use last name.
teams_home_probable_pitcher_middle_nameStringHome team probable pitcher middle name.
teams_home_probable_pitcher_boxscore_nameStringHome team probable pitcher boxscore name.
teams_home_probable_pitcher_nick_nameStringHome team probable pitcher nick name.
teams_home_probable_pitcher_genderStringHome team probable pitcher gender.
teams_home_probable_pitcher_is_playerBooleanHome team probable pitcher is player.
teams_home_probable_pitcher_is_verifiedBooleanHome team probable pitcher is verified.
teams_home_probable_pitcher_draft_yearInt64Home team probable pitcher draft year.
teams_home_probable_pitcher_mlb_debut_dateStringHome team probable pitcher mlb debut date.
teams_home_probable_pitcher_bat_side_codeStringHome team probable pitcher bat side code.
teams_home_probable_pitcher_bat_side_descriptionStringHome team probable pitcher bat side description.
teams_home_probable_pitcher_pitch_hand_codeStringHome team probable pitcher pitch hand code.
teams_home_probable_pitcher_pitch_hand_descriptionStringHome team probable pitcher pitch hand description.
teams_home_probable_pitcher_name_first_lastStringHome team probable pitcher name first last.
teams_home_probable_pitcher_name_slugStringHome team probable pitcher name slug.
teams_home_probable_pitcher_first_last_nameStringHome team probable pitcher first last name.
teams_home_probable_pitcher_last_first_nameStringHome team probable pitcher last first name.
teams_home_probable_pitcher_last_init_nameStringHome team probable pitcher last init name.
teams_home_probable_pitcher_init_last_nameStringHome team probable pitcher init last name.
teams_home_probable_pitcher_full_fml_nameStringHome team probable pitcher full fml name.
teams_home_probable_pitcher_full_lfm_nameStringHome team probable pitcher full lfm name.
teams_home_probable_pitcher_strike_zone_topFloat64Home team probable pitcher strike zone top.
teams_home_probable_pitcher_strike_zone_bottomFloat64Home team probable pitcher strike zone bottom.
teams_home_split_squadBooleanHome team split squad.
teams_home_series_numberInt64Home team series number.
teams_home_spring_league_idInt64Home team spring league id.
teams_home_spring_league_nameStringHome team spring league name.
teams_home_spring_league_linkStringHome team spring league link.
teams_home_spring_league_abbreviationStringHome team spring league abbreviation.
linescore_scheduled_inningsInt64Linescore scheduled innings.
linescore_inningsStringLinescore innings.
linescore_defense_team_idInt64Linescore defense team id.
linescore_defense_team_nameStringLinescore defense team name.
linescore_defense_team_linkStringLinescore defense team link.
linescore_offense_team_idInt64Linescore offense team id.
linescore_offense_team_nameStringLinescore offense team name.
linescore_offense_team_linkStringLinescore offense team link.
venue_idInt64MLBAM venue id.
venue_nameStringBallpark name.
venue_linkStringVenue link.
content_linkStringContent link.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_statcast_schedule()