Skip to main content

MLB — MLB Stats API — Schedule

mlb_schedule_postseason​

GET /api/v1/schedule/postseason — postseason-only schedule for a season.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/schedule/postseason

Valid URL: https://statsapi.mlb.com/api/v1/schedule/postseason?sportId=1

API ParameterPythonPatternRequiredNullableDescription
seasonseasonYSeason year (e.g. 2024).
sportIdsport_idYsportId query parameter.
hydratehydrateYhydrate 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
schedule_dateStringThe calendar date grouping postseason games in this response row, as returned by the MLB Stats API schedule endpoint.
game_pkInt64Unique game identifier.
game_guidStringGlobally unique game identifier (GUID).
linkStringAPI link to the game feed.
game_typeStringGame type code (R, P, etc.).
seasonStringSeason year.
game_dateStringGame date (YYYY-MM-DD).
official_dateStringOfficial game date (YYYY-MM-DD).
is_tieBooleanWhether the game ended in a tie.
is_featured_gameBooleanWhether the game is a featured game.
game_numberInt64Game number within a doubleheader.
public_facingBooleanWhether the game is public-facing.
double_headerStringDoubleheader indicator ('N', 'S', 'Y').
gameday_typeStringGameday data feed type.
tiebreakerStringWhether the game is a tiebreaker.
calendar_event_idStringCalendar event identifier.
season_displayStringDisplay string for the season.
day_nightStringDay or night game indicator.
descriptionStringLong-form description text.
scheduled_inningsInt64Scheduled number of innings.
reverse_home_away_statusBooleanWhether home/away teams are reversed.
inning_break_lengthInt64Length of inning breaks in seconds.
games_in_seriesInt64Number of games in the series.
series_game_numberInt64Game number within the series.
series_descriptionStringDescription of the series.
record_sourceStringSource of the schedule record.
if_necessaryStringWhether the game is played only if necessary.
if_necessary_descriptionStringDescription of the if-necessary status.
status_abstract_game_stateStringAbstract game state (e.g. 'Final').
status_coded_game_stateStringCoded game state.
status_detailed_stateStringDetailed game state.
status_status_codeStringStatus code for the game.
status_start_time_tbdBooleanWhether the start time is TBD.
status_abstract_game_codeStringAbstract game state code.
teams_away_team_idInt64Away team MLBAM ID.
teams_away_team_nameStringAway team name.
teams_away_team_linkStringAPI link to the away team.
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 winning percentage.
teams_away_scoreInt64Away team score.
teams_away_is_winnerBooleanWhether the away team won.
teams_away_split_squadBooleanWhether the away team is a split squad.
teams_away_series_numberInt64Away team's series number.
teams_home_team_idInt64Home team MLBAM ID.
teams_home_team_nameStringHome team name.
teams_home_team_linkStringAPI link to the home team.
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 winning percentage.
teams_home_scoreInt64Home team score.
teams_home_is_winnerBooleanWhether the home team won.
teams_home_split_squadBooleanWhether the home team is a split squad.
teams_home_series_numberInt64Home team's series number.
venue_idInt64MLBAM venue ID.
venue_nameStringVenue name.
venue_linkStringAPI link to the venue.
content_linkStringAPI link to the game content.

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_schedule_postseason()

mlb_schedule_tied​

View tied game schedule info.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/schedule/games/tied

Valid URL: https://statsapi.mlb.com/api/v1/schedule/games/tied?season=2016

API ParameterPythonPatternRequiredNullableDescription
gameTypesgame_typesYgameTypes query parameter.
seasonseasonYSeason year (e.g. 2024).
hydratehydrateYhydrate query parameter.
fieldsfieldsYfields 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
schedule_dateStringThe calendar date grouping tied (suspended and resumed) games in this response row, as returned by the MLB Stats API schedule endpoint.
game_pkInt64Unique game identifier.
game_guidStringGlobally unique game identifier (GUID).
linkStringAPI link to the game feed.
game_typeStringGame type code (R, P, etc.).
seasonStringSeason year.
game_dateStringGame date (YYYY-MM-DD).
official_dateStringOfficial game date (YYYY-MM-DD).
is_tieBooleanWhether the game ended in a tie.
game_numberInt64Game number within a doubleheader.
public_facingBooleanWhether the game is public-facing.
double_headerStringDoubleheader indicator ('N', 'S', 'Y').
gameday_typeStringGameday data feed type.
tiebreakerStringWhether the game is a tiebreaker.
calendar_event_idStringCalendar event identifier.
season_displayStringDisplay string for the season.
day_nightStringDay or night game indicator.
scheduled_inningsInt64Scheduled number of innings.
reverse_home_away_statusBooleanWhether home/away teams are reversed.
inning_break_lengthInt64Length of inning breaks in seconds.
games_in_seriesInt64Number of games in the series.
series_game_numberInt64Game number within the series.
series_descriptionStringDescription of the series.
record_sourceStringSource of the schedule record.
if_necessaryStringWhether the game is played only if necessary.
if_necessary_descriptionStringDescription of the if-necessary status.
status_abstract_game_stateStringAbstract game state (e.g. 'Final').
status_coded_game_stateStringCoded game state.
status_detailed_stateStringDetailed game state.
status_status_codeStringStatus code for the game.
status_start_time_tbdBooleanWhether the start time is TBD.
status_reasonStringReason for the game status (e.g. 'Rain').
status_abstract_game_codeStringAbstract game state code.
teams_away_team_idInt64Away team MLBAM ID.
teams_away_team_nameStringAway team name.
teams_away_team_linkStringAPI link to the away team.
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 winning percentage.
teams_away_scoreInt64Away team score.
teams_away_split_squadBooleanWhether the away team is a split squad.
teams_away_series_numberInt64Away team's series number.
teams_home_team_idInt64Home team MLBAM ID.
teams_home_team_nameStringHome team name.
teams_home_team_linkStringAPI link to the home team.
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 winning percentage.
teams_home_scoreInt64Home team score.
teams_home_split_squadBooleanWhether the home team is a split squad.
teams_home_series_numberInt64Home team's series number.
venue_idInt64MLBAM venue ID.
venue_nameStringVenue name.
venue_linkStringAPI link to the venue.
content_linkStringAPI link to the game content.

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_schedule_tied(season='2016')

mlb_schedule_postseason_series​

View schedule info for postseason based on series.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/schedule/postseason/series

Valid URL: https://statsapi.mlb.com/api/v1/schedule/postseason/series?season=2023

API ParameterPythonPatternRequiredNullableDescription
gameTypesgame_typesYgameTypes query parameter.
seriesNumberseries_numberYseriesNumber query parameter.
teamIdteam_idYteamId query parameter.
sportIdsport_idYsportId query parameter.
seasonseasonYSeason year (e.g. 2024).
fieldsfieldsYfields 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
total_itemsInt64Total schedule items on the date.
total_gamesInt64Total games on the date.
total_games_in_progressInt64Games currently in progress on the date.
gamesString
sort_orderInt64Display sort order for the sport.
series_idStringSeries identifier (e.g. 'W_1').
series_sort_numberInt64Sort number for the series.
series_is_defaultBooleanWhether the series is the default series.
series_game_typeStringGame type code for the series.

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_schedule_postseason_series(season='2023')

mlb_schedule_postseason_tunein​

View schedule info for the tuneIn application.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/schedule/postseason/tuneIn

Valid URL: https://statsapi.mlb.com/api/v1/schedule/postseason/tuneIn?season=2023

API ParameterPythonPatternRequiredNullableDescription
teamIdteam_idYteamId query parameter.
sportIdsport_idYsportId query parameter.
seasonseasonYSeason year (e.g. 2024).
hydratehydrateYhydrate query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_schedule); pass return_as_pandas=True for a pandas.DataFrame. 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_schedule_postseason_tunein(season='2023')