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)