def get_league_all_stars(league_id, write_ins=False, **kwargs):
"""This endpoint allows you to pull the all star ballots for a given league.
Args:
league_id (int): Unique League Identifier
params (dict): Contains the group, and fields parameters described
below.
params:
league_id (required)
Description: Unique Player Identifier
Parameter Type: path
Data Type: integer
league_ids
Description: Comma delimited list of League IDs.
Format: 1234, 2345
Parameter Type: query
Data Type: array[integer]
season
Description: Season of play
Parameter Type: query
Data Type: string
fields
Description: Comma delimited list of specific fields to be returned.
Format: topLevelNode, childNode, attribute
Parameter Type: query
Data Type: array[string]
Returns:
json
"""
if write_ins:
context = 'allStarWriteIns'
else:
context = 'allStarFinalVote'
return request(endpoint.LEAGUE, context, primary_key=league_id, **kwargs)
def get_current_game_stats(person_id, **kwargs):
"""This endpoint allows you to pull the current game status for a given
player.
Args:
person_id (int): Unique Player Identifier
params (dict): Contains the person_ids, season, group, and fields
parameters described below.
params:
person_id (required)
Description: Unique Player Identifier
Parameter Type: path
Data Type: integer
group *may not yet do anything
Description: Category of statistics to return. 0: hitting, 1: pitching,
2: fielding, 3: running
Format: 0, 1, 2, 3
Parameter Type: query
Data Type: array[string]
timecode
Description: Use this parameter to return a snapshot of the data at the
specified time.
Format: YYYYMMDD_HHMMSS
fields
Description: Comma delimited list of specific fields to be returned.
Format: topLevelNode, childNode, attribute
Parameter Type: query
Data Type: array[string]
Returns:
json
"""
return request(endpoint.PEOPLE, 'stats/game/current', primary_key=person_id,
valid_params=VALID_CURRENT_GAME_STATS_PARAMS, **kwargs)
def get_live_timestamps(game_pk, **kwargs):
"""
This can be used for replaying games. endpoint returns all of the timecodes
that can be used with diffs for mlbapi.game.live_diff.
params:
game_pk (required)
Description: Unique Primary Key Representing a Game
Parameter Type: path
Data Type: string
"""
return request(endpoint.GAME, 'feed/live/timestamps', primary_key=game_pk,
valid_params=VALID_LIVE_TIMESTAMPS_PARAMS, **kwargs)
def get_content(game_pk, **kwargs):
"""
Retrieve game content such as highlights.
params:
game_pk (required)
Description: Unique Primary Key Representing a Game
Parameter Type: path
Data Type: integer? #string elsewhere in documentation
highlightLimit:
Description: Number of results to return
Parameter Type: query
Data Type: integer
"""
return request(endpoint.GAME, 'content', primary_key=game_pk,
valid_params=VALID_CONTENT_PARAMS, **kwargs)
def get_win_probability(game_pk, **kwargs):
"""
params:
game_pk (required)
Description: Unique Primary Key Representing a Game
Parameter Type: path
Data Type: integer? #string elsewhere in documentation
timecode
Description: Use this parameter to return a snapshot of the data at the
specified time.
Format: YYYYMMDD_HHMMSS
Parameter Type: query
Data Type: string
fields
Description: Comma delimited list of specific fields to be returned.
Format: topLevelNode, childNode, attribute
Parameter Type: query
Data Type: array[string]
"""
return request(endpoint.GAME, 'winProbability', primary_key=game_pk,
valid_params=VALID_WIN_PROBABILITY_PARAMS, **kwargs)
def get_play_by_play(game_pk, **kwargs):
"""This endpoint allows you to pull the play by play for a game.
params:
game_pk (required)
Description: Unique Primary Key Representing a Game
Parameter Type: path
Data Type: integer? #string elsewhere in documentation
timecode
Description: Use this parameter to return a snapshot of the data at
the specified time.
Format: YYYYMMDD_HHMMSS
Parameter Type: query
Data Type: string
fields
Description: Comma delimited list of specific fields to be returned.
Format: topLevelNode, childNode, attribute
Parameter Type: query
Data Type: array[string]
"""
return request(endpoint.GAME, 'playByPlay', primary_key=game_pk,
valid_params=VALID_PLAY_BY_PLAY_PARAMS, **kwargs)
def get_color_diff(game_pk, **kwargs):
"""
?? Not Yet Implemented ??
This API can return very large payloads. It is STRONGLY recommended that
clients ask for diffs and use "Accept-Encoding: gzip" header.
startTimecode and endTimecode can be used for getting diffs.
Expected usage:
1) Request full payload by not passing startTimecode or endTimecode. This
will return the entire color feed up till the current time.
2) Find the latest timecode in this response.
3) Wait X seconds
4) Use the timecode from 2 as the startTimecode. This will give you a
diff of everything that has happened since startTimecode.
5) If no data is returned, wait X seconds and do the same request.
6) If data is returned, get a new timeStamp from the response, and use
that for the next call as startTimecode.
params:
game_pk (required)
Description: Unique Primary Key Representing a Game
Parameter Type: path
Data Type: string
startTimecode
Description: Start time code will give you everything since that time.
Format: YYYYMMDD_HHMMSS
Parameter Type: query
Data Type: string
endTimecode
Description: End time code will give you a snapshot at that specific
time.
Format: YYYYMMDD_HHMMSS
Parameter Type: query
Data Type: string
"""
return request(endpoint.GAME, 'feed/color/diffPatch', primary_key=game_pk,
valid_params=VALID_COLOR_DIFF_PARAMS, **kwargs)
def get_live_diff(game_pk, **kwargs):
"""
?? Not Yet Implemented ??
This endpoint allows comparison of game files and shows any differences or
discrepancies between the two.
Diff/Patch System: startTimecode and endTimecode can be used for getting diffs.
Expected usage:
1) Request full payload by not passing startTimecode or endTimecode. This
will return the most recent game state.
2) Find the latest timecode in this response.
3) Wait X seconds
4) Use the timecode from 2 as the startTimecode. This will give you a
diff of everything that has happened since startTimecode.
5) If no data is returned, wait X seconds and do the same request.
6) If data is returned, get a new timeStamp from the response, and use
that for the next call as startTimecode.
params:
game_pk (required)
Description: Unique Primary Key Representing a Game
Parameter Type: path
Data Type: string
startTimecode
Description: Start time code will give you everything since that time.
Format: YYYYMMDD_HHMMSS
Parameter Type: query
Data Type: string
endTimecode
Description: End time code will give you a snapshot at that specific
time.
Format: YYYYMMDD_HHMMSS
Parameter Type: query
Data Type: string
"""
return request(endpoint.GAME, 'feed/live/diffPatch', primary_key=game_pk,
valid_params=VALID_LIVE_DIFF_PARAMS, **kwargs)
def get_league(league_id, **kwargs):
"""This endpoint allows you to pull the information for a league.
Args:
league_id (int): Unique League Identifier
params (dict): Contains the league_ids, season, seasons, expand, and
fields parameters described below.
params:
league_id (required)
Description: Unique League Identifier
Parameter Type: path
Data Type: integer
league_ids
Description: Comma delimited list of League IDs.
Format: 1234, 2345
Parameter Type: query
Data Type: array[integer]
season
Description: Season of play
Parameter Type: query
Data Type: string
seasons
Description: Seasons of play
Parameter Type: query
Data Type: array[string]
expand
Description: ?
Parameter type: query
Data Type: array[string]
fields
Description: Comma delimited list of specific fields to be returned.
Format: topLevelNode, childNode, attribute
Parameter Type: query
Data Type: array[string]
Returns:
json
"""
return request(endpoint.LEAGUE, primary_key=league_id, **kwargs)
def get_person(person_id, **kwargs):
"""This endpoint allows you to pull the information for a player.
Args:
person_id (int): Unique Player Identifier
params (dict): Contains the person_ids, season, group, and fields
parameters described below.
params:
person_id (required)
Description: Unique Player Identifier
Parameter Type: path
Data Type: integer
person_ids
Description: Comma delimited list of person ID.
Format: 1234, 2345
Parameter Type: query
Data Type: array[integer]
season
Description: Season of play
Parameter Type: query
Data Type: string
group *may not yet do anything
Description: Category of statistics to return. 0: hitting, 1: pitching,
2: fielding, 3: running
Format: 0, 1, 2, 3
Parameter Type: query
Data Type: array[string]
fields
Description: Comma delimited list of specific fields to be returned.
Format: topLevelNode, childNode, attribute
Parameter Type: query
Data Type: array[string]
Returns:
json
"""
return request(endpoint.PEOPLE, primary_key=person_id,
valid_params=VALID_PERSON_PARAMS, **kwargs)
def get_live(game_pk, **kwargs):
"""
This API can return very large payloads. It is STRONGLY recommended that
clients ask for diffs and use "Accept-Encoding: gzip" header.
params:
game_pk (required)
Description: Unique Primary Key Representing a Game
Parameter Type: path
Data Type: string
timecode
Description: Use this parameter to return a snapshot of the data at the
specified time.
Format: YYYYMMDD_HHMMSS
Parameter Type: query
Data Type: string
fields
Description: Comma delimited list of specific fields to be returned.
Format: topLevelNode, childNode, attribute
Parameter Type: query
Data Type: array[string]
"""
return request(endpoint.GAME, 'feed/live', primary_key=game_pk,
valid_params=VALID_LIVE_PARAMS, **kwargs)
def get_game_stats(person_id, game_pk, **kwargs):
"""This endpoint allows you to pull the game stats for a given player and
game.
Args:
person_id (int): Unique Player Identifier
game_pk (int): Unique Primary Key representing a game.
params (dict): Contains the group, and fields parameters described
below.
params:
person_id (required)
Description: Unique Player Identifier
Parameter Type: path
Data Type: integer
game_pk (required)
Description: Unique Primary Key representing a game.
Parameter Type: path
Data Type: integer
group *may not yet do anything
Description: Category of statistics to return. 0: hitting, 1: pitching,
2: fielding, 3: running
Format: 0, 1, 2, 3
Parameter Type: query
Data Type: array[string]
fields
Description: Comma delimited list of specific fields to be returned.
Format: topLevelNode, childNode, attribute
Parameter Type: query
Data Type: array[string]
Returns:
json
"""
return request(endpoint.PEOPLE, 'stats/game', primary_key=person_id,
secondary_key=game_pk, valid_params=VALID_GAME_STATS_PARAMS,
**kwargs)
def get_schedule(**kwargs): # pylint: disable=too-many-branches
"""This endpoint allows you to pull shedules. The API parameter is camel cased. The
python equivalent is passed in as a python variable, identified in the < >.
Args:
calendar_types (list[int]): Comma delimitd list of type of events
team_id (list[int]): Unique Team Identifier. Format: 141, 147, etc.
league_id (list[int]): Unique League Identifier
sport_id (list[int]): Top level organization of a sport.
Format: SportId is 1 for MLB
game_pk (int): Unique Primary Key representing a game
game_pks (list[int]): List of unique primary keys
event_ids (list[int]): A unique identifier for non-game event
venue_ids (list[int]): Unique Venue Identifier
performer_ids (list[int]): A unique identifier for non-team event
performers
game_type (str): Type of Game. Available types in api/v1/gameTypes
game_types (list[str]): List of type of Game.
season (str): Season of play
seasons (list[str]): List of seasons of play
date (str): Date of Game. Format: MM/DD/YYYY
start_date (str): Start date for range of data. Must be used with
end date. Format: MM/DD/YYYY
end_date (str): End date for range of data. Must be used with start
date. Format: MM/DD/YYYY
timecode (str): Use this parameter to return a snapshot of the data at
the specified time. Format: YYYYMMDD_HHMMSS
use_latest_games (bool): No description provided
opponent_id (int): A unique identifier for the opposing team. Must be
used with teamId.
fields (list[str]): List of specific fields to be returned.
Format: topLevelNode, childNode, attribute
"""
if 'start_date' in kwargs.keys():
if 'end_date' not in kwargs.keys():
error = 'Query contains start_date with no end_date.'
raise mlbapi.exceptions.ParameterException(error)
elif 'end_date' in kwargs.keys():
if 'start_date' not in kwargs.keys():
error = 'Query contains end_date with no start_date.'
raise mlbapi.exceptions.ParameterException(error)
elif 'opponent_id' in kwargs.keys():
if 'team_id' not in kwargs.keys():
error = 'Query contains opponentId with no teamId.'
raise mlbapi.exceptions.ParameterException(error)
elif 'seasons' in kwargs.keys(): # Make sure seasons is a comma delimited list
if isinstance(kwargs['seasons'], list):
temp = []
for season in kwargs['seasons']:
if not isinstance(season, int):
try:
temp.append(int(season))
except ValueError as error:
raise mlbapi.exceptions.ParameterException(error)
if temp:
kwargs['seasons'] = ','.join(temp)
else:
kwargs['seasons'] = ','.join(kwargs['seasons'])
else:
error = 'seasons must be a list of years as Integers or Strings.'
raise mlbapi.exceptions.ParameterException(error)
elif 'sport_id' not in kwargs.keys():
kwargs['sport_id'] = 1
return request(endpoint.SCHEDULE, valid_params=VALID_SCHEDULE_PARAMS, **kwargs)
def get_standings(standings_type=None, **kwargs):
"""This endpoint allows you to pull standings.
params:
standingsType (required) <standings_type>
Description: Type of season. Available types in /api/v1/standingsTypes
Parameter Type: path
Data Type: Optional string
leagueId <league_id>
Description: Unique League Identifier
Parameter Type: query
Data Type: integer
season <season>
Description: Season of play.
Parameter Type: query
Data Type: string
standingsTypes <standings_types>
Description: Type of season. Available types in /api/v1/standingsTypes
Parameter Type: query
Data Type: array[string]
date <date>
Description: Date of Game.
Format: MM/DD/YYYY
Parameter Type: query
Data Type: LocalDate/string
teamId <team_id>
Description: Unique Team Identifier.
Format: 141, 147, etc
Parameter Type: query
Data Type: integer
includeMLB <include_mlb>
Description: Determines whether to include major league teams when using the
'BY_ORGANIZATION' standings type
Parameter Type: query
Data Type: boolean
expand <expand>
Description: expand
Parameter Type: query
Data Type: array[string]
fields <fields>
Description: Comma delimited list of specific fields to be returned.
Format: topLevelNode, childNode, attribute
Parameter Type: query
Data Type: array[string]
Returns json
"""
check_kwargs(kwargs.keys(), VALID_STANDINGS_PARAMS,
mlbapi.exceptions.ParameterException)
if 'league_id' in kwargs.keys(
): # Make sure seasons is a comma delimited list
if isinstance(kwargs['league_id'], list):
temp = []
for league_id in kwargs['league_id']:
if not isinstance(league_id, int):
try:
temp.append(int(league_id))
except ValueError as error:
raise mlbapi.exceptions.ParameterException(error)
if temp:
kwargs['league_id'] = ','.join(temp)
else:
error = 'league_id must be a list of leagues as Integers or Strings.'
raise mlbapi.exceptions.ParameterException(error)
kwargs['league_id'] = ','.join(
[str(lid) for lid in kwargs['league_id']])
return request(endpoint.STANDINGS, primary_key=standings_type, **kwargs)
def get_teams(**kwargs):
"""This endpoint allows you to pull teams.
params:
teamId (required) <team_id>
Description: Unique Team Identifier
Parameter Type: path
Data Type: Optional integer
season <season>
Description: Season of play
Parameter Type: query
Data Type: string
sportId <sport_id> #Not Implemented: "Object not found"
Description: Top level organization of a sport (MLB is 1)
Parameter Type: query
Data Type: integer
divisionId <division_id>
Description: Unique division ID.
Parameter Type: query
Data Type: integer
gameType <game_type>
Description: Type of Game. Available types in /api/v1/gameTypes
Parameter Type: query
Data Type: string
leagueIds <league_ids>
Description: Comma delimited list of Unique league identifiers.
Parameter Type: query
Data Type: array[integer]
sportIds <sport_ids> #Not Implemented: "Object not found"
Description: Comma delimited list of top level organizations of a sport.
Parameter Type: query
Data Type: array[integer]
activeStatus <active_status>
Description: Flag for fetching teams that are currently active (Y), inactive (N),
pending (P), or all teams (B).
Parameter Type: query
Data Type: string
Options: ['ACTIVE', 'INACTIVE', 'PENDING', 'BOTH']
leagueListId <league_list_id>
Description: Unique league list identifier
Parameter Type: query
Data Type: string
Options: ['MILB_FULL', 'MILB_SHORT', 'MILB_COMPLEX', 'MILB_ALL', 'MILB_ALL_NOMEX',
'MILB_ALL_DOMESTIC', 'MILB_NONCOMP', 'MILB_NONCOMP_NOMEX', 'MILB_DOMCOMP',
'MILB_INTCOMP', 'WIN_NOABL', 'WIN_CARIBBEAN', 'WIN_ALL', 'ABL', 'MLB',
'MLB_HIST', 'MLB_MILB', 'MLB_MILB_HIST', 'MLB_MILB_WIN', 'BASEBALL_ALL',
'MLB_SPRING']
allStarStatuses <all_star_status>
Description: allStarStatuses
Parameter Type: query
Data Type: array[string]
fields <fields>
Description: Comma delimited list of specific fields to be returned.
Format: topLevelNode, childNode, attribute
Parameter Type: query
Data Type: array[string]
Returns:
json
"""
check_kwargs(kwargs.keys(), VALID_TEAMS_PARAMS,
mlbapi.exceptions.ParameterException)
if 'league_ids' in kwargs.keys(
): # Make sure seasons is a comma delimited list
if isinstance(kwargs['league_ids'], list):
temp = []
for league_id in kwargs['league_ids']:
if not isinstance(league_id, int):
try:
temp.append(int(league_id))
except ValueError as error:
raise mlbapi.exceptions.ParameterException(error)
if temp:
kwargs['league_ids'] = ','.join(temp)
else:
error = 'seasons must be a list of years as Integers or Strings.'
raise mlbapi.exceptions.ParameterException(error)
kwargs['league_ids'] = ','.join(
[str(lid) for lid in kwargs['league_ids']])
return request(endpoint.TEAM, **kwargs)