yfpy.query.YahooFantasySportsQuery

class YahooFantasySportsQuery(auth_dir, league_id, game_id=None, game_code='nfl', offline=False, all_output_as_json_str=False, consumer_key=None, consumer_secret=None, browser_callback=True)[source]

Bases: object

Yahoo Fantasy Sports REST API query CLASS to retrieve all types of fantasy sports data.

Instantiate a YahooQueryObject for running queries against the Yahoo fantasy REST API.

Parameters

auth_dir (Path | str) – Location of both private.json (containing Yahoo dev app consumer_key and consumer_secret) and token.json (generated by OAuth2 three-legged handshake).
league_id (str) – League ID of selected Yahoo Fantasy league.
game_id (int, optional) – Game ID of selected Yahoo fantasy game corresponding to a specific year, and defaulting to the current year.
game_code (str, optional) – Game code of selected Yahoo Fantasy game corresponding to a specific year, and defaulting to “nfl” (fantasy football), “nhl” (fantasy hockey), “mlb” (fantasy baseball), or “nba” (fantasy basketball)
offline (bool, optional) – Boolean to run in offline mode (Only works if all needed Yahoo Fantasy data has been previously saved locally using the Data module in data.py).
all_output_as_json_str (bool, optional) – Option to automatically convert all query output to JSON strings.
consumer_key (str, optional) – User defined consumer key to use instead of values stored in the private.json file (must be defined alongside a user defined consumer secret).
consumer_secret (str, optional) – User defined consumer secret to use instead of values stored in the private.json file (must be defined alongside a user defined consumer key).
browser_callback (bool, optional) – Enable or disable (enabled by default) whether the yahoo-oauth library automatically opens a browser window to authenticate (if disabled, it will output the callback URL).

_auth_dir

Location of both private.json (containing Yahoo dev app consumer_key and consumer_secret) and token.json (generated by OAuth2 three-legged handshake).

Type: Path

_yahoo_consumer_key

User defined consumer key to use instead of values stored in the private.json file (must be defined alongside a user defined consumer secret).

Type: str

_yahoo_consumer_secret

User defined consumer secret to use instead of values stored in the private.json file (must be defined alongside a user defined consumer key).

Type: str

_yahoo_access_token

Refreshable access token generated by the yahoo-oauth library to avoid having to reauthenticate on every access to the Yahoo Fantasy Sports API.

Type: str

_browser_callback

Enable or disable (enabled by default) whether the yahoo-oauth library automatically opens a browser window to authenticate (if disabled, it will output the callback URL).

Type: bool

fantasy_content_data_field

The initial JSON field in which all Yahoo Fantasy Sports API responses store the data output of the submitted query.

Type: str

league_id

League ID of selected Yahoo Fantasy league.

Type: str

game_id

Game ID of selected Yahoo fantasy game corresponding to a specific year, and defaulting to

Type: int

the current year.

game_code

Game code of selected Yahoo Fantasy game corresponding to a specific year, and defaulting to “nfl” (fantasy football), “nhl” (fantasy hockey), “mlb” (fantasy baseball), or “nba” (fantasy basketball)

Type: str

offline

Boolean to run in offline mode (Only works if all needed Yahoo Fantasy data has been previously saved locally using the Data module in data.py).

Type: bool

all_output_as_json_str

Option to automatically convert all query output to JSON strings.

Type: bool

league_key

The Yahoo Fantasy Sports league key formatted as <game_id>.l.<league_id>.

Type: str

executed_queries

List of completed queries and their responses.

Type: list[dict[str, Any]]

Methods

`get_all_yahoo_fantasy_game_keys`	Retrieve all Yahoo Fantasy Sports game keys by ID (from year of inception to present), sorted by season/year.
`get_current_game_info`	Retrieve game info for current fantasy season.
`get_current_game_metadata`	Retrieve game metadata for current fantasy season.
`get_current_user`	Retrieve metadata for current logged-in user.
`get_game_info_by_game_id`	Retrieve game info for specific game by ID.
`get_game_key_by_season`	Retrieve specific game key by season.
`get_game_metadata_by_game_id`	Retrieve game metadata for specific game by ID.
`get_game_position_types_by_game_id`	Retrieve all valid position types for specific game by ID sorted alphabetically by type.
`get_game_roster_positions_by_game_id`	Retrieve all valid roster positions for specific game by ID sorted alphabetically by position.
`get_game_stat_categories_by_game_id`	Retrieve all valid stat categories of a specific game by ID.
`get_game_weeks_by_game_id`	Retrieve all valid weeks of a specific game by ID.
`get_league_draft_results`	Retrieve draft results for chosen league.
`get_league_info`	Retrieve info for chosen league.
`get_league_key`	Retrieve league key for selected league.
`get_league_matchups_by_week`	Retrieve matchups for chosen league by week.
`get_league_metadata`	Retrieve metadata for chosen league.
`get_league_players`	Retrieve valid players for chosen league.
`get_league_scoreboard_by_week`	Retrieve scoreboard for chosen league by week.
`get_league_settings`	Retrieve settings (rules) for chosen league.
`get_league_standings`	Retrieve standings for chosen league.
`get_league_teams`	Retrieve teams for chosen league.
`get_league_transactions`	Retrieve transactions for chosen league.
`get_player_draft_analysis`	Retrieve draft analysis of specific player by player_key for chosen league.
`get_player_ownership`	Retrieve ownership of specific player by player_key for chosen league.
`get_player_percent_owned_by_week`	Retrieve percent-owned of specific player by player_key and by week for chosen league.
`get_player_stats_by_date`	Retrieve player stats by player_key and by date for chosen league.
`get_player_stats_by_week`	Retrieve stats of specific player by player_key and by week for chosen league.
`get_player_stats_for_season`	Retrieve stats of specific player by player_key for the entire season for chosen league.
`get_response`	Retrieve Yahoo Fantasy Sports data from the REST API.
`get_team_draft_results`	Retrieve draft results of specific team by team_id for chosen league.
`get_team_info`	Retrieve info of specific team by team_id for chosen league.
`get_team_matchups`	Retrieve matchups of specific team by team_id for chosen league.
`get_team_metadata`	Retrieve metadata of specific team by team_id for chosen league.
`get_team_roster_by_week`	Retrieve roster of specific team by team_id and by week for chosen league.
`get_team_roster_player_info_by_date`	Retrieve roster with ALL player info of specific team by team_id and by date for chosen league.
`get_team_roster_player_info_by_week`	Retrieve roster with ALL player info of specific team by team_id and by week for chosen league.
`get_team_roster_player_stats`	Retrieve roster with ALL player info for the season of specific team by team_id and for chosen league.
`get_team_roster_player_stats_by_week`	Retrieve roster with player stats of specific team by team_id and by week for chosen league.
`get_team_standings`	Retrieve standings of specific team by team_id for chosen league.
`get_team_stats`	Retrieve stats of specific team by team_id for chosen league.
`get_team_stats_by_week`	Retrieve stats of specific team by team_id and by week for chosen league.
`get_user_games`	Retrieve game history for current logged-in user sorted by season/year.
`get_user_leagues_by_game_key`	Retrieve league history for current logged-in user for specific game by game IDs/keys sorted by season/year.
`get_user_teams`	Retrieve teams for all leagues for current logged-in user for current game sorted by season/year.
`query`	Base query class to retrieve requested data from the Yahoo fantasy sports REST API.

Attributes

YFO

alias of TypeVar('YFO', bound=yfpy.models.YahooFantasyObject)

get_all_yahoo_fantasy_game_keys()[source]

Retrieve all Yahoo Fantasy Sports game keys by ID (from year of inception to present), sorted by season/year.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_all_yahoo_fantasy_game_keys()
[
  {
    "game": {
      "code": "nfl",
      "game_id": "50",
      "game_key": "50",
      "is_game_over": 1,
      "is_offseason": 1,
      "is_registration_over": 1,
      "name": "Football",
      "season": "1999",
      "type": "full",
      "url": "https://football.fantasysports.yahoo.com/archive/nfl/1999"
    }
  },
  ...
]

Returns: List of dictionaries containing the single key “game” and value of each YFPY Game instance.
Return type: list[dict[str, Game]]

get_current_game_info()[source]

Retrieve game info for current fantasy season.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_current_game_info()
{
  "code": "nfl",
  "game_id": "390",
  "game_key": "390",
  "game_weeks": [
    {
      "game_week": {
        "display_name": "1",
        "end": "2019-09-09",
        "start": "2019-09-05",
        "week": "1"
      }
    },
    ...
  ],
  "is_game_over": 0,
  "is_live_draft_lobby_active": 1,
  "is_offseason": 0,
  "is_registration_over": 0,
  "name": "Football",
  "position_types": [
    {
      "position_type": {
        "type": "O",
        "display_name": "Offense"
      }
    },
    ...
  ],
  "roster_positions": [
    {
      "roster_position": {
        "position": "QB",
        "position_type": "O"
      }
    },
    ...
  ],
  "season": "2019",
  "stat_categories": {
    "stats": [
      {
        "stat": {
          "display_name": "GP",
          "name": "Games Played",
          "sort_order": "1",
          "stat_id": 0
        }
      },
      ...
  },
  "type": "full",
  "url": "https://football.fantasysports.yahoo.com/f1"
}

Returns: YFPY Game instance.
Return type: Game

get_current_game_metadata()[source]

Retrieve game metadata for current fantasy season.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_current_game_metadata()
{
  "code": "nfl",
  "game_id": "390",
  "game_key": "390",
  "is_game_over": 0,
  "is_live_draft_lobby_active": 1,
  "is_offseason": 0,
  "is_registration_over": 0,
  "name": "Football",
  "season": "2019",
  "type": "full",
  "url": "https://football.fantasysports.yahoo.com/f1"
}

Returns: YFPY Game instance.
Return type: Game

get_current_user()[source]

Retrieve metadata for current logged-in user.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_current_user()
{
  "guid": "USER_GUID_STRING"
}

Returns: YFPY User instance.
Return type: User

get_game_info_by_game_id(game_id)[source]

Retrieve game info for specific game by ID.

Parameters: game_id (int) – Game ID of selected Yahoo Fantasy game corresponding to a specific year.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_game_info_by_game_id(390)
{
  "code": "nfl",
  "game_id": "390",
  "game_key": "390",
  "game_weeks": [
    {
      "game_week": {
        "display_name": "1",
        "end": "2019-09-09",
        "start": "2019-09-05",
        "week": "1"
      }
    },
    ...
  ],
  "is_game_over": 0,
  "is_live_draft_lobby_active": 1,
  "is_offseason": 0,
  "is_registration_over": 0,
  "name": "Football",
  "position_types": [
    {
      "position_type": {
        "type": "O",
        "display_name": "Offense"
      }
    },
    ...
  ],
  "roster_positions": [
    {
      "roster_position": {
        "position": "QB",
        "position_type": "O"
      }
    },
    ...
  ],
  "season": "2019",
  "stat_categories": {
    "stats": [
      {
        "stat": {
          "display_name": "GP",
          "name": "Games Played",
          "sort_order": "1",
          "stat_id": 0
        }
      },
      ...
  },
  "type": "full",
  "url": "https://football.fantasysports.yahoo.com/f1"
}

Returns: YFPY Game instance.
Return type: Game

get_game_key_by_season(season)[source]

Retrieve specific game key by season.

Parameters: season (int) – User defined season/year for which to retrieve the Yahoo Fantasy Sports game.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_game_key_by_season(2021)
338

Returns: The game key for a Yahoo Fantasy Sports game specified by season.
Return type: str

get_game_metadata_by_game_id(game_id)[source]

Retrieve game metadata for specific game by ID.

Parameters: game_id (int) – Game ID of selected Yahoo Fantasy game corresponding to a specific year.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_game_metadata_by_game_id(331)
{
  "code": "nfl",
  "game_id": "331",
  "game_key": "331",
  "is_game_over": 1,
  "is_offseason": 1,
  "is_registration_over": 1,
  "name": "Football",
  "season": "2014",
  "type": "full",
  "url": "https://football.fantasysports.yahoo.com/archive/nfl/2014"
}

Returns: YFPY Game instance.
Return type: Game

get_game_position_types_by_game_id(game_id)[source]

Retrieve all valid position types for specific game by ID sorted alphabetically by type.

Parameters: game_id (int) – Game ID of selected Yahoo Fantasy game corresponding to a specific year.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_game_position_types_by_game_id(331)
[
  {
    "position_type": {
      "type": "O",
      "display_name": "Offense"
    }
  },
  {
    "position_type": {
      "type": "K",
      "display_name": "Kickers"
    }
  },
  {
    "position_type": {
      "type": "DT",
      "display_name": "Defense/Special Teams"
    }
  },
  {
    "position_type": {
      "type": "DP",
      "display_name": "Defensive Players"
    }
  }
]

Returns: List of dictionaries containing the single key “position_type” and value of each YFPY PositionType instance.
Return type: list[dict[str, PositionType]]

get_game_roster_positions_by_game_id(game_id)[source]

Retrieve all valid roster positions for specific game by ID sorted alphabetically by position.

Parameters: game_id (int) – Game ID of selected Yahoo Fantasy game corresponding to a specific year.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_game_roster_positions_by_game_id(331)
[
  {
    "roster_position": {
      "position": "BN"
    }
  },
  ...,
  {
    "roster_position": {
      "position": "WR",
      "position_type": "O"
    }
  }
]

Returns: List of dictionaries containing the single key “roster_position” and value of each YFPY RosterPosition instance.
Return type: list[dict[str, RosterPosition]]

get_game_stat_categories_by_game_id(game_id)[source]

Retrieve all valid stat categories of a specific game by ID.

Parameters: game_id (int) – Game ID of selected Yahoo Fantasy game corresponding to a specific year.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_game_stat_categories_by_game_id(331)
{
  "stats": [
    {
      "stat": {
        "display_name": "GP",
        "name": "Games Played",
        "sort_order": "1",
        "stat_id": 0
      }
    },
    ...,
    {
      "stat": {
        "display_name": "Rush 1st Downs",
        "name": "Rushing 1st Downs",
        "sort_order": "1",
        "stat_id": 81
      }
    }
  ]
}

Returns: YFPY StatCategories instance.
Return type: StatCategories

get_game_weeks_by_game_id(game_id)[source]

Retrieve all valid weeks of a specific game by ID.

Parameters: game_id (int) – Game ID of selected Yahoo Fantasy game corresponding to a specific year.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_game_weeks_by_game_id(331)
[
  {
    "game_week": {
      "display_name": "1",
      "end": "2014-09-08",
      "start": "2014-09-04",
      "week": "1"
    }
  },
  ...,
  {
    "game_week": {
      "display_name": "17",
      "end": "2014-12-28",
      "start": "2014-12-23",
      "week": "17"
    }
  }
]

Returns: List of dictionaries containing the single key “game_week” and value of each YFPY GameWeek instance.
Return type: list[dict[str, GameWeek]]

get_league_draft_results()[source]

Retrieve draft results for chosen league.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_league_draft_results()
[
  {
    "draft_result": {
      "pick": 1,
      "round": 1,
      "team_key": "331.l.729259.t.4",
      "player_key": "331.p.9317"
    }
  },
  ...
]

Returns: List of dictionaries containing the single key “draft_result” and value of each YFPY DraftResult instance.
Return type: list[dict[str, DraftResult]]

get_league_info()[source]

Retrieve info for chosen league.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_league_info()
{
  "allow_add_to_dl_extra_pos": 0,
  "current_week": "16",
  "draft_status": "postdraft",
  "edit_key": "16",
  "end_date": "2014-12-22",
  "end_week": "16",
  "game_code": "nfl",
  "iris_group_chat_id": null,
  "is_cash_league": "0",
  "is_finished": 1,
  "is_pro_league": "1",
  "league_id": "729259",
  "league_key": "331.l.729259",
  "league_type": "public",
  "league_update_timestamp": "1420099793",
  "logo_url": "https://s.yimg.com/cv/api/default/20180206/default-league-logo@2x.png",
  "name": "Yahoo Public 729259",
  "num_teams": 10,
  "renew": null,
  "renewed": null,
  "scoreboard": {
    "week": "16",
    "matchups": [
      ...
    ]
  },
  "scoring_type": "head",
  "season": "2014",
  "settings": {
    ...
  },
  "standings": {
    "teams": [
        ...,
        ...
    ],
    ...
  },
  "start_date": "2014-09-04",
  "start_week": "1",
  "url": "https://football.fantasysports.yahoo.com/archive/nfl/2014/729259",
  "weekly_deadline": null
}

Returns: YFPY League instance.
Return type: League

get_league_key(season=None)[source]

Retrieve league key for selected league.

Parameters: season (int) – User defined season/year for which to retrieve the Yahoo Fantasy Sports league key.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_league_key(2021)
331.l.729259

Returns: League key string for selected league.
Return type: str

get_league_matchups_by_week(chosen_week)[source]

Retrieve matchups for chosen league by week.

Parameters: chosen_week (int) – Selected week for which to retrieve data.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_league_matchups_by_week(1)
[
    "matchup": {
        "is_consolation": "0",
        "is_matchup_recap_available": 1,
        "is_playoffs": "0",
        "is_tied": 0,
        "matchup_grades": [
          {
            "matchup_grade": {
              "grade": "B",
              "team_key": "331.l.729259.t.1"
            }
          },
          {
            "matchup_grade": {
              "grade": "B",
              "team_key": "331.l.729259.t.2"
            }
          }
        ],
        "matchup_recap_title": "Wax On Wax Off Gets Victory Against Hellacious Hill 12",
        "matchup_recap_url":
            "https://football.fantasysports.yahoo.com/archive/nfl/2014/729259/recap?
            week=1&mid1=1&mid2=2",
        "status": "postevent",
        "teams": [
          {
            "team": {
                <team data>
            }
          },
          {
            "team": {
                <team data>
            }
          }
        ],
        "week": "1",
        "week_end": "2014-09-08",
        "week_start": "2014-09-04",
        "winner_team_key": "331.l.729259.t.2"
      }
    },
    ...
]

Returns: List of dictionaries containing the single key “matchup” and value of each YFPY Matchup instance.
Return type: list[dict[str, Matchup]]

get_league_metadata()[source]

Retrieve metadata for chosen league.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_league_metadata()
{
  "allow_add_to_dl_extra_pos": 0,
  "current_week": "16",
  "draft_status": "postdraft",
  "edit_key": "16",
  "end_date": "2014-12-22",
  "end_week": "16",
  "game_code": "nfl",
  "iris_group_chat_id": null,
  "is_cash_league": "0",
  "is_finished": 1,
  "is_pro_league": "1",
  "league_id": "729259",
  "league_key": "331.l.729259",
  "league_type": "public",
  "league_update_timestamp": "1420099793",
  "logo_url": "https://s.yimg.com/cv/api/default/20180206/default-league-logo@2x.png",
  "name": "Yahoo Public 729259",
  "num_teams": 10,
  "renew": null,
  "renewed": null,
  "scoring_type": "head",
  "season": "2014",
  "start_date": "2014-09-04",
  "start_week": "1",
  "url": "https://football.fantasysports.yahoo.com/archive/nfl/2014/729259",
  "weekly_deadline": null
}

Returns: YFPY League instance.
Return type: League

get_league_players(player_count_limit=None, player_count_start=0, is_retry=False)[source]

Retrieve valid players for chosen league.

Parameters

player_count_limit (int) – Maximum number of players to retreive.
player_count_start (int) – Index from which to retrieve all subsequent players.
is_retry (bool) – Boolean to indicate whether the method is being retried during error handling.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_league_players(50, 25)
[
  {
    "player": {
      "bye_weeks": {
        "week": "10"
      },
      "display_position": "K",
      "editorial_player_key": "nfl.p.3727",
      "editorial_team_abbr": "Ind",
      "editorial_team_full_name": "Indianapolis Colts",
      "editorial_team_key": "nfl.t.11",
      "eligible_positions": {
        "position": "K"
      },
      "has_player_notes": 1,
      "headshot": {
        "size": "small",
        "url":
            "https://s.yimg.com/iu/api/res/1.2/OpHvpCHjl_PQvkeQUgsjsA--~C
            /YXBwaWQ9eXNwb3J0cztjaD0yMzM2O2NyPTE7Y3c9MTc5MDtkeD04NTc7ZHk9MDtmaT11bGNyb3A7aD02MDtxPTEwMDt
            3PTQ2/https://s.yimg.com/xe/i/us/sp/v/nfl_cutout/players_l/08152019/3727.png"
      },
      "is_undroppable": "0",
      "name": {
        "ascii_first": "Adam",
        "ascii_last": "Vinatieri",
        "first": "Adam",
        "full": "Adam Vinatieri",
        "last": "Vinatieri"
      },
      "player_id": "3727",
      "player_key": "331.p.3727",
      "player_notes_last_timestamp": 1568758320,
      "position_type": "K",
      "primary_position": "K",
      "uniform_number": "4"
    }
  },
  ...
]

Returns: List of dictionaries containing the single key “player” and value of each YFPY Player instance.
Return type: list[dict[str, Player]]

get_league_scoreboard_by_week(chosen_week)[source]

Retrieve scoreboard for chosen league by week.

Parameters: chosen_week (int) – Selected week for which to retrieve data.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_league_scoreboard_by_week(1)
{
  "week": "1",
  "matchups": [
    {
      "matchup": {
        "is_consolation": "0",
        "is_matchup_recap_available": 1,
        "is_playoffs": "0",
        "is_tied": 0,
        "matchup_grades": [
          {
            "matchup_grade": {
              "grade": "B",
              "team_key": "331.l.729259.t.1"
            }
          },
          {
            "matchup_grade": {
              "grade": "B",
              "team_key": "331.l.729259.t.2"
            }
          }
        ],
        "matchup_recap_title": "Wax On Wax Off Gets Victory Against Hellacious Hill 12",
        "matchup_recap_url":
            "https://football.fantasysports.yahoo.com/archive/nfl/2014/729259/recap?
            week=1&mid1=1&mid2=2",
        "status": "postevent",
        "teams": [
          {
            "team": {
                <team data>
            }
          },
          {
            "team": {
                <team data>
            }
          }
        ],
        "week": "1",
        "week_end": "2014-09-08",
        "week_start": "2014-09-04",
        "winner_team_key": "331.l.729259.t.2"
      }
    },
    ...
  ]
}

Returns: YFPY Scoreboard instance.
Return type: Scoreboard

get_league_settings()[source]

Retrieve settings (rules) for chosen league.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_league_settings()
{
  "cant_cut_list": "yahoo",
  "draft_time": "1408410000",
  "draft_type": "live",
  "has_multiweek_championship": 0,
  "has_playoff_consolation_games": true,
  "is_auction_draft": "0",
  "max_teams": "10",
  "num_playoff_consolation_teams": 4,
  "num_playoff_teams": "4",
  "pickem_enabled": "1",
  "player_pool": "ALL",
  "playoff_start_week": "15",
  "post_draft_players": "W",
  "roster_positions": [
    {
      "roster_position": {
        "count": 1,
        "position": "QB",
        "position_type": "O"
      }
    },
    ...
  ],
  "scoring_type": "head",
  "stat_categories": {
    "stats": [
      {
        "stat": {
          "display_name": "Pass Yds",
          "enabled": "1",
          "name": "Passing Yards",
          "position_type": "O",
          "sort_order": "1",
          "stat_id": 4,
          "stat_position_types": {
            "stat_position_type": {
              "position_type": "O"
            }
          }
        }
      },
      ...
    ]
  },
  "stat_modifiers": {
    "stats": [
      {
        "stat": {
          "stat_id": 4,
          "value": "0.04"
        }
      },
      ...
    ]
  },
  "trade_end_date": "2014-11-14",
  "trade_ratify_type": "yahoo",
  "trade_reject_time": "2",
  "uses_faab": "0",
  "uses_fractional_points": "1",
  "uses_lock_eliminated_teams": 1,
  "uses_negative_points": "1",
  "uses_playoff": "1",
  "uses_playoff_reseeding": 0,
  "waiver_rule": "gametime",
  "waiver_time": "2",
  "waiver_type": "R"
}

Returns: YFPY Settings instance.
Return type: Settings

get_league_standings()[source]

Retrieve standings for chosen league.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_league_standings()
{
  "teams": [
    {
      "team": {
        "clinched_playoffs": 1,
        "draft_grade": "C+",
        "draft_position": 7,
        "draft_recap_url":
            "https://football.fantasysports.yahoo.com/archive/nfl/2014/729259/8/draftrecap",
        "has_draft_grade": 1,
        "league_scoring_type": "head",
        "managers": {
          "manager": {
            "guid": "PMTCFWSK5U5LI4SKWREUR56B5A",
            "manager_id": "8",
            "nickname": "--hidden--"
          }
        },
        "name": "clam dam",
        "number_of_moves": "27",
        "number_of_trades": 0,
        "roster_adds": {
          "coverage_type": "week",
          "coverage_value": "17",
          "value": "0"
        },
        "team_id": "8",
        "team_key": "331.l.729259.t.8",
        "team_logos": {
          "team_logo": {
            "size": "large",
            "url": "https://s.yimg.com/cv/apiv2/default/nfl/nfl_1.png"
          }
        },
        "team_points": {
          "coverage_type": "season",
          "season": "2014",
          "total": "1507.06"
        },
        "team_standings": {
          "outcome_totals": {
            "losses": 2,
            "percentage": 0.857,
            "ties": 0,
            "wins": 12
          },
          "playoff_seed": "1",
          "points_against": 1263.78,
          "points_for": 1507.06,
          "rank": 1,
          "streak": {
            "type": "win",
            "value": "2"
          }
        },
        "url": "https://football.fantasysports.yahoo.com/archive/nfl/2014/729259/8",
        "waiver_priority": 10
      }
    },
    ...
  ]
}

Returns: YFPY Standings instance.
Return type: Standings

get_league_teams()[source]

Retrieve teams for chosen league.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_league_teams()
[
  {
    "team": {
      "clinched_playoffs": 1,
      "draft_grade": "B",
      "draft_position": 4,
      "draft_recap_url":
        "https://football.fantasysports.yahoo.com/archive/nfl/2014/729259/1/draftrecap",
      "has_draft_grade": 1,
      "league_scoring_type": "head",
      "managers": {
        "manager": {
          "guid": "BMACD7S5UXV7JIQX4PGGUVQJAU",
          "manager_id": "1",
          "nickname": "--hidden--"
        }
      },
      "name": "Hellacious Hill 12",
      "number_of_moves": "71",
      "number_of_trades": 0,
      "roster_adds": {
        "coverage_type": "week",
        "coverage_value": "17",
        "value": "0"
      },
      "team_id": "1",
      "team_key": "331.l.729259.t.1",
      "team_logos": {
        "team_logo": {
          "size": "large",
          "url": "https://ct.yimg.com/cy/1441/24935131299_a8242dab70_192sq.jpg?ct=fantasy"
        }
      },
      "url": "https://football.fantasysports.yahoo.com/archive/nfl/2014/729259/1",
      "waiver_priority": 9
    }
  },
  ...
]

Returns: List of dictionaries containing the single key “team” and value of each YFPY Team instance.
Return type: list[dict[str, Team]]

get_league_transactions()[source]

Retrieve transactions for chosen league.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_league_transactions()
[
  {
    "transaction": {
      "players": [
        {
          "player": {
            "display_position": "RB",
            "editorial_team_abbr": "NO",
            "name": {
              "ascii_first": "Kerwynn",
              "ascii_last": "Williams",
              "first": "Kerwynn",
              "full": "Kerwynn Williams",
              "last": "Williams"
            },
            "player_id": "26853",
            "player_key": "331.p.26853",
            "position_type": "O",
            "transaction_data": {
              "destination_team_key": "331.l.729259.t.1",
              "destination_team_name": "Hellacious Hill 12",
              "destination_type": "team",
              "source_type": "freeagents",
              "type": "add"
            }
          }
        }
      ],
      "status": "successful",
      "timestamp": "1419188151",
      "transaction_id": "282",
      "transaction_key": "331.l.729259.tr.282",
      "type": "add/drop"
    }
  },
  ...
]

Returns: List of dictionaries containing the single key “transaction” and value of each YFPY Transaction instance.
Return type: list[dict[str, Transaction]]

get_player_draft_analysis(player_key)[source]

Retrieve draft analysis of specific player by player_key for chosen league.

Parameters: player_key (str) – The player key of chosen player (example: 331.p.7200 - <game_id>.p.<player_id>).

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_player_draft_analysis("331.p.7200")
{
  "bye_weeks": {
    "week": "9"
  },
  "display_position": "QB",
  "draft_analysis": {
    "average_pick": "19.9",
    "average_round": "2.8",
    "average_cost": "38.5",
    "percent_drafted": "1.00"
  },
  "editorial_player_key": "nfl.p.7200",
  "editorial_team_abbr": "GB",
  "editorial_team_full_name": "Green Bay Packers",
  "editorial_team_key": "nfl.t.9",
  "eligible_positions": {
    "position": "QB"
  },
  "has_player_notes": 1,
  "headshot": {
    "size": "small",
    "url": "https://s.yimg.com/iu/api/res/1.2/Xdm96BfVJw4WV_W7GA7xLw--~C
        /YXBwaWQ9eXNwb3J0cztjaD0yMzM2O2NyPTE7Y3c9MTc5MDtkeD04NTc7ZHk9MDtmaT11bGNyb3A7aD02MDtxPTEwMDt3PTQ
        2/https://s.yimg.com/xe/i/us/sp/v/nfl_cutout/players_l/08202019/7200.2.png"
  },
  "is_undroppable": "0",
  "name": {
    "ascii_first": "Aaron",
    "ascii_last": "Rodgers",
    "first": "Aaron",
    "full": "Aaron Rodgers",
    "last": "Rodgers"
  },
  "player_id": "7200",
  "player_key": "331.p.7200",
  "player_notes_last_timestamp": 1568581740,
  "position_type": "O",
  "primary_position": "QB",
  "uniform_number": "12"
}

Returns: YFPY Player instance containing the “draft_analysis” key (returns a YFPY DraftAnalysis instnace).
Return type: Player

get_player_ownership(player_key)[source]

Retrieve ownership of specific player by player_key for chosen league.

Parameters: player_key (str) – The player key of chosen player (example: 331.p.7200 - <game_id>.p.<player_id>).

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_player_ownership("331.p.7200")
{
  "bye_weeks": {
    "week": "9"
  },
  "display_position": "QB",
  "editorial_player_key": "nfl.p.7200",
  "editorial_team_abbr": "GB",
  "editorial_team_full_name": "Green Bay Packers",
  "editorial_team_key": "nfl.t.9",
  "eligible_positions": {
    "position": "QB"
  },
  "has_player_notes": 1,
  "headshot": {
    "size": "small",
    "url": "https://s.yimg.com/iu/api/res/1.2/Xdm96BfVJw4WV_W7GA7xLw--~C
        /YXBwaWQ9eXNwb3J0cztjaD0yMzM2O2NyPTE7Y3c9MTc5MDtkeD04NTc7ZHk9MDtmaT11bGNyb3A7aD02MDtxPTEwMDt3PTQ
        2/https://s.yimg.com/xe/i/us/sp/v/nfl_cutout/players_l/08202019/7200.2.png"
  },
  "is_undroppable": "0",
  "name": {
    "ascii_first": "Aaron",
    "ascii_last": "Rodgers",
    "first": "Aaron",
    "full": "Aaron Rodgers",
    "last": "Rodgers"
  },
  "ownership": {
    "ownership_type": "team",
    "owner_team_key": "331.l.729259.t.4",
    "owner_team_name": "hold my D",
    "teams": {
      "team": {
        "clinched_playoffs": 1,
        "draft_grade": "B-",
        "draft_position": 1,
        "draft_recap_url":
            "https://football.fantasysports.yahoo.com/archive/nfl/2014/729259/4/draftrecap",
        "has_draft_grade": 1,
        "league_scoring_type": "head",
        "managers": {
          "manager": {
            "guid": "5KLNXUYW5RP22UMRKUXHBCIITI",
            "manager_id": "4",
            "nickname": "--hidden--"
          }
        },
        "name": "hold my D",
        "number_of_moves": "27",
        "number_of_trades": "1",
        "roster_adds": {
          "coverage_type": "week",
          "coverage_value": "17",
          "value": "0"
        },
        "team_id": "4",
        "team_key": "331.l.729259.t.4",
        "team_logos": {
          "team_logo": {
            "size": "large",
            "url": "https://ct.yimg.com/cy/1589/24677593583_68859308dd_192sq.jpg?ct=fantasy"
          }
        },
        "url": "https://football.fantasysports.yahoo.com/archive/nfl/2014/729259/4",
        "waiver_priority": 7
      }
    }
  },
  "player_id": "7200",
  "player_key": "331.p.7200",
  "player_notes_last_timestamp": 1568581740,
  "position_type": "O",
  "primary_position": "QB",
  "uniform_number": "12"
}

Returns: YFPY Player instance containing the “ownership” key (returns a YFPY Ownership instance).
Return type: Player

get_player_percent_owned_by_week(player_key, chosen_week='current')[source]

Retrieve percent-owned of specific player by player_key and by week for chosen league.

Parameters

player_key (str) – The player key of chosen player (example: 331.p.7200 - <game_id>.p.<player_id>).
chosen_week (int) – Selected week for which to retrieve data.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_player_percent_owned_by_week("331.p.7200", 1)
{
  "bye_weeks": {
    "week": "9"
  },
  "display_position": "QB",
  "editorial_player_key": "nfl.p.7200",
  "editorial_team_abbr": "GB",
  "editorial_team_full_name": "Green Bay Packers",
  "editorial_team_key": "nfl.t.9",
  "eligible_positions": {
    "position": "QB"
  },
  "has_player_notes": 1,
  "headshot": {
    "size": "small",
    "url": "https://s.yimg.com/iu/api/res/1.2/Xdm96BfVJw4WV_W7GA7xLw--~C
    /YXBwaWQ9eXNwb3J0cztjaD0yMzM2O2NyPTE7Y3c9MTc5MDtkeD04NTc7ZHk9MDtmaT11bGNyb3A7aD02MDtxPTEwMDt3PTQ2/
    https://s.yimg.com/xe/i/us/sp/v/nfl_cutout/players_l/08202019/7200.2.png"
  },
  "is_undroppable": "0",
  "name": {
    "ascii_first": "Aaron",
    "ascii_last": "Rodgers",
    "first": "Aaron",
    "full": "Aaron Rodgers",
    "last": "Rodgers"
  },
  "percent_owned": {
    "coverage_type": "week",
    "week": "1",
    "value": 100,
    "delta": "0"
  },
  "player_id": "7200",
  "player_key": "331.p.7200",
  "player_notes_last_timestamp": 1568581740,
  "position_type": "O",
  "primary_position": "QB",
  "uniform_number": "12"
}

Returns: YFPY Player instance containing the “percent_owned” key (returns a YFPY PercentOwned instance).
Return type: Player

get_player_stats_by_date(player_key, chosen_date=None)[source]

Retrieve player stats by player_key and by date for chosen league.

Note

This applies to MLB, NBA, and NHL leagues, but does NOT apply to NFL leagues. This query will FAIL if you pass it an INVALID date string!

Parameters

player_key (str) – The player key of chosen player (example: 331.p.7200 - <game_id>.p.<player_id>).
chosen_date (str) – Selected date for which to retrieve data. REQUIRED FORMAT: YYYY-MM-DD (Ex. 2011-05-01)

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_player_stats_by_date("nhl.p.4588", "2011-05-01")
{
  "display_position": "G",
  "editorial_player_key": "nhl.p.4588",
  "editorial_team_abbr": "Was",
  "editorial_team_full_name": "Washington Capitals",
  "editorial_team_key": "nhl.t.23",
  "eligible_positions": {
    "position": "G"
  },
  "has_player_notes": 1,
  "headshot": {
    "size": "small",
    "url": "https://s.yimg.com/iu/api/res/1.2/CzntDh_d59voTqU6fhQy3g--~C/YXBwaWQ9eXNwb3J0cztjaD0yMzM2O2
    NyPTE7Y3c9MTc5MDtkeD04NTc7ZHk9MDtmaT11bGNyb3A7aD02MDtxPTEwMDt3PTQ2/https://s.yimg.com/
    xe/i/us/sp/v/nhl_cutout/players_l/10182019/4588.png"
  },
  "is_undroppable": "0",
  "name": {
    "ascii_first": "Braden",
    "ascii_last": "Holtby",
    "first": "Braden",
    "full": "Braden Holtby",
    "last": "Holtby"
  },
  "player_id": "4588",
  "player_key": "303.p.4588",
  "player_notes_last_timestamp": 1574133600,
  "player_stats": {
    "coverage_type": "date",
    "stats": [
      {
        "stat": {
          "stat_id": "19",
          "value": "1"
        }
      },
      {
        "stat": {
          "stat_id": "22",
          "value": "1"
        }
      },
      {
        "stat": {
          "stat_id": "23",
          "value": "1.00"
        }
      },
      {
        "stat": {
          "stat_id": "25",
          "value": "29"
        }
      },
      {
        "stat": {
          "stat_id": "24",
          "value": "30"
        }
      },
      {
        "stat": {
          "stat_id": "26",
          "value": ".967"
        }
      },
      {
        "stat": {
          "stat_id": "27",
          "value": "0"
        }
      }
    ]
  },
  "position_type": "G",
  "primary_position": "G",
  "uniform_number": "70"
}

Returns: YFPY Player instnace containing the “player_stats” key (returns a YFPY PlayerStats instance).
Return type: Player

get_player_stats_by_week(player_key, chosen_week='current')[source]

Retrieve stats of specific player by player_key and by week for chosen league.

Parameters

player_key (str) – The player key of chosen player (example: 331.p.7200 - <game_id>.p.<player_id>).
chosen_week (int) – Selected week for which to retrieve data.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_player_stats_by_week("331.p.7200", 1)
{
  "bye_weeks": {
    "week": "9"
  },
  "display_position": "QB",
  "editorial_player_key": "nfl.p.7200",
  "editorial_team_abbr": "GB",
  "editorial_team_full_name": "Green Bay Packers",
  "editorial_team_key": "nfl.t.9",
  "eligible_positions": {
    "position": "QB"
  },
  "has_player_notes": 1,
  "headshot": {
    "size": "small",
    "url": "https://s.yimg.com/iu/api/res/1.2/Xdm96BfVJw4WV_W7GA7xLw--~C
        /YXBwaWQ9eXNwb3J0cztjaD0yMzM2O2NyPTE7Y3c9MTc5MDtkeD04NTc7ZHk9MDtmaT11bGNyb3A7aD02MDtxPTEwMDt3PTQ
        2/https://s.yimg.com/xe/i/us/sp/v/nfl_cutout/players_l/08202019/7200.2.png"
  },
  "is_undroppable": "0",
  "name": {
    "ascii_first": "Aaron",
    "ascii_last": "Rodgers",
    "first": "Aaron",
    "full": "Aaron Rodgers",
    "last": "Rodgers"
  },
  "player_id": "7200",
  "player_key": "331.p.7200",
  "player_notes_last_timestamp": 1568581740,
  "player_points": {
    "coverage_type": "week",
    "week": "1",
    "total": 10.56
  },
  "player_stats": {
    "coverage_type": "week",
    "week": "1",
    "stats": [
      {
        "stat": {
          "stat_id": "4",
          "value": "189"
        }
      },
      ...
    ]
  },
  "position_type": "O",
  "primary_position": "QB",
  "uniform_number": "12"
}

Returns: YFPY Player instance containing the “player_stats” key (returns a YFPY PlayerStats instance).
Return type: Player

get_player_stats_for_season(player_key)[source]

Retrieve stats of specific player by player_key for the entire season for chosen league.

Parameters: player_key (str) – The player key of chosen player (example: 331.p.7200 - <game_id>.p.<player_id>).

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_player_stats_for_season("331.p.7200")
{
  "bye_weeks": {
    "week": "9"
  },
  "display_position": "QB",
  "editorial_player_key": "nfl.p.7200",
  "editorial_team_abbr": "GB",
  "editorial_team_full_name": "Green Bay Packers",
  "editorial_team_key": "nfl.t.9",
  "eligible_positions": {
    "position": "QB"
  },
  "has_player_notes": 1,
  "headshot": {
    "size": "small",
    "url": "https://s.yimg.com/iu/api/res/1.2/Xdm96BfVJw4WV_W7GA7xLw--~C
        /YXBwaWQ9eXNwb3J0cztjaD0yMzM2O2NyPTE7Y3c9MTc5MDtkeD04NTc7ZHk9MDtmaT11bGNyb3A7aD02MDtxPTEwMDt3PTQ
        2/https://s.yimg.com/xe/i/us/sp/v/nfl_cutout/players_l/08202019/7200.2.png"
  },
  "is_undroppable": "0",
  "name": {
    "ascii_first": "Aaron",
    "ascii_last": "Rodgers",
    "first": "Aaron",
    "full": "Aaron Rodgers",
    "last": "Rodgers"
  },
  "player_id": "7200",
  "player_key": "331.p.7200",
  "player_notes_last_timestamp": 1568581740,
  "player_points": {
    "coverage_type": "season",
    "total": 359.14
  },
  "player_stats": {
    "coverage_type": "season",
    "stats": [
      {
        "stat": {
          "stat_id": "4",
          "value": "4381"
        }
      },
      ...
    ]
  },
  "position_type": "O",
  "primary_position": "QB",
  "uniform_number": "12"
}

Returns: YFPY Player instance.
Return type: Player

get_response(url, retries=3, backoff=0)[source]

Retrieve Yahoo Fantasy Sports data from the REST API.

Parameters

url (str) – REST API request URL string.
retries (int, optional) – Number of times to retry a query if it fails (defaults to 3).
backoff (int, optional) – Multiplier that incrementally increases the wait time before retrying a failed query request.

Returns

API response from Yahoo Fantasy Sports API request.

Return type

Response

get_team_draft_results(team_id)[source]

Retrieve draft results of specific team by team_id for chosen league.

Parameters: team_id (str | int) – Selected team ID for which to retrieva data (can be integers 1 through n where n is the number of teams in the league).

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_team_draft_results(1)
[
  {
    "draft_result": {
      "pick": 4,
      "round": 1,
      "team_key": "331.l.729259.t.1",
      "player_key": "331.p.8256"
    }
  },
  ...
]

Returns: List of dictionaries with key = “draft_result” and value = YFPY DraftResult instance.
Return type: list[dict[str, DraftResult]]

get_team_info(team_id)[source]

Retrieve info of specific team by team_id for chosen league.

Parameters: team_id (str | int) – Selected team ID for which to retrieva data (can be integers 1 through n where n is the number of teams in the league).

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_team_info(1)
{
  "clinched_playoffs": 1,
  "draft_grade": "B",
  "draft_position": 4,
  "draft_recap_url": "https://football.fantasysports.yahoo.com/archive/nfl/2014/729259/1/draftrecap",
  "draft_results": [
    ...
  ],
  "has_draft_grade": 1,
  "league_scoring_type": "head",
  "managers": {
    "manager": {
      "guid": "BMACD7S5UXV7JIQX4PGGUVQJAU",
      "manager_id": "1",
      "nickname": "--hidden--"
    }
  },
  "matchups": [
    ...
  ],
  "name": "Hellacious Hill 12",
  "number_of_moves": "71",
  "number_of_trades": 0,
  "roster": {
    ...
  },
  "roster_adds": {
    "coverage_type": "week",
    "coverage_value": "17",
    "value": "0"
  },
  "team_id": "1",
  "team_key": "331.l.729259.t.1",
  "team_logos": {
    "team_logo": {
      "size": "large",
      "url": "https://ct.yimg.com/cy/1441/24935131299_a8242dab70_192sq.jpg?ct=fantasy"
    }
  },
  "team_points": {
    "coverage_type": "season",
    "season": "2014",
    "total": "1409.24"
  },
  "team_standings": {
    "outcome_totals": {
      "losses": 5,
      "percentage": 0.643,
      "ties": 0,
      "wins": 9
    },
    "playoff_seed": "2",
    "points_against": 1266.6599999999999,
    "points_for": 1409.24,
    "rank": 2,
    "streak": {
      "type": "win",
      "value": "1"
    }
  },
  "url": "https://football.fantasysports.yahoo.com/archive/nfl/2014/729259/1",
  "waiver_priority": 9
}

Returns: YFPY Team instance.
Return type: Team

get_team_matchups(team_id)[source]

Retrieve matchups of specific team by team_id for chosen league.

Parameters: team_id (str | int) – Selected team ID for which to retrieva data (can be integers 1 through n where n is the number of teams in the league).

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_team_matchups(1)
[
    {
        "matchup": {
            <matchup data> (see get_league_matchups_by_week docstring for matchup data example)
        }
    }
]

Returns: List of dictionaries with key = “matchup” and value = YFPY Matchup instance.
Return type: list[dict[str, Matchup]]

get_team_metadata(team_id)[source]

Retrieve metadata of specific team by team_id for chosen league.

Parameters: team_id (str | int) – Selected team ID for which to retrieva data (can be integers 1 through n where n is the number of teams in the league).

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_team_metadata(1)
{
  "team_key": "331.l.729259.t.1",
  "team_id": "1",
  "name": "Hellacious Hill 12",
  "url": "https://football.fantasysports.yahoo.com/archive/nfl/2014/729259/1",
  "team_logos": {
    "team_logo": {
      "size": "large",
      "url": "https://ct.yimg.com/cy/1441/24935131299_a8242dab70_192sq.jpg?ct=fantasy"
    }
  },
  "waiver_priority": 9,
  "number_of_moves": "71",
  "number_of_trades": 0,
  "roster_adds": {
    "coverage_type": "week",
    "coverage_value": "17",
    "value": "0"
  },
  "clinched_playoffs": 1,
  "league_scoring_type": "head",
  "draft_position": 4,
  "has_draft_grade": 1,
  "draft_grade": "B",
  "draft_recap_url": "https://football.fantasysports.yahoo.com/archive/nfl/2014/729259/1/draftrecap",
  "managers": {
    "manager": {
      "guid": "BMACD7S5UXV7JIQX4PGGUVQJAU",
      "manager_id": "1",
      "nickname": "--hidden--"
    }
  }
}

Returns: YFPY Team instance.
Return type: Team

get_team_roster_by_week(team_id, chosen_week='current')[source]

Retrieve roster of specific team by team_id and by week for chosen league.

Parameters

team_id (str | int) – Selected team ID for which to retrieva data (can be integers 1 through n where n is the number of teams in the league).
chosen_week (int) – Selected week for which to retrieve data.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_team_roster_by_week(1, 1)
{
  "coverage_type": "week",
  "week": "1",
  "is_editable": 0,
  "players": [
    {
      "player": {
        "bye_weeks": {
          "week": "10"
        },
        "display_position": "QB",
        "editorial_player_key": "nfl.p.5228",
        "editorial_team_abbr": "NE",
        "editorial_team_full_name": "New England Patriots",
        "editorial_team_key": "nfl.t.17",
        "eligible_positions": {
          "position": "QB"
        },
        "has_player_notes": 1,
        "headshot": {
          "size": "small",
          "url": "https://s.yimg.com/iu/api/res/1.2/_U9UJlrYMsJ22DpA..S3zg--~C
            /YXBwaWQ9eXNwb3J0cztjaD0yMzM2O2NyPTE7Y3c9MTc5MDtkeD04NTc7ZHk9MDtmaT11bGNyb3A7aD02MDtxPTEwMDt
            3PTQ2/https://s.yimg.com/xe/i/us/sp/v/nfl_cutout/players_l/08212019/5228.png"
        },
        "is_undroppable": "0",
        "name": {
          "ascii_first": "Tom",
          "ascii_last": "Brady",
          "first": "Tom",
          "full": "Tom Brady",
          "last": "Brady"
        },
        "player_id": "5228",
        "player_key": "331.p.5228",
        "player_notes_last_timestamp": 1568837880,
        "position_type": "O",
        "primary_position": "QB",
        "selected_position": {
          "coverage_type": "week",
          "is_flex": 0,
          "position": "QB",
          "week": "1"
        },
        "uniform_number": "12"
      }
    },
    ...
  ]
}

Returns: YFPY Roster instance.
Return type: Roster

get_team_roster_player_info_by_date(team_id, chosen_date=None)[source]

Retrieve roster with ALL player info of specific team by team_id and by date for chosen league.

Note

This applies to MLB, NBA, and NHL leagues, but does NOT apply to NFL leagues. This query will FAIL if you pass it an INVALID date string!

Parameters

team_id (str | int) – Selected team ID for which to retrieva data (can be integers 1 through n where n is the number of teams in the league).
chosen_date (str) – Selected date for which to retrieve data. REQUIRED FORMAT: YYYY-MM-DD (Ex. 2011-05-01)

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_team_roster_player_info_by_date(1, "2011-05-01")
[
  {
    "player": {
      "display_position": "C",
      "draft_analysis": {
        "average_pick": 33.2,
        "average_round": 3.5,
        "average_cost": 39.2,
        "percent_drafted": 1.0
      },
      "editorial_player_key": "nhl.p.3981",
      "editorial_team_abbr": "Chi",
      "editorial_team_full_name": "Chicago Blackhawks",
      "editorial_team_key": "nhl.t.4",
      "eligible_positions": [
        "C",
        "F"
      ],
      "has_player_notes": 1,
      "headshot": {
        "size": "small",
        "url": "https://s.yimg.com/iu/api/res/1.2/tz.KOMoEiBDch6AJAGaUtg--~C/
        YXBwaWQ9eXNwb3J0cztjaD0yMzM2O2NyPTE7Y3c9MTc5MDtkeD04NTc7ZHk9MDtmaT11bGNyb3A7aD02MDtxPTEwMDt3PTQ2/https://s.yimg.com/xe/i/us/sp/v/nhl_cutout/players_l/11032021/3981.png"
      },
      "is_editable": 0,
      "is_undroppable": 0,
      "name": {
        "ascii_first": "Jonathan",
        "ascii_last": "Toews",
        "first": "Jonathan",
        "full": "Jonathan Toews",
        "last": "Toews"
      },
      "ownership": {
        "ownership_type": "team",
        "owner_team_key": "303.l.69624.t.2",
        "owner_team_name": "The Bateleurs"
      },
      "percent_owned": {
        "coverage_type": "week",
        "week": 25,
        "value": 98,
        "delta": -1.0
      },
      "player_id": 3981,
      "player_key": "303.p.3981",
      "player_notes_last_timestamp": 1651606838,
      "player_stats": {
        "coverage_type": "date",
        "stats": [
          {
            "stat": {
              "stat_id": 1,
              "value": 1.0
            }
          },
          ...
        ]
      },
      "position_type": "P",
      "primary_position": "C",
      "selected_position": {
        "coverage_type": "date",
        "is_flex": 0,
        "position": "C"
      },
      "uniform_number": 19
    }
  },
  ...
]

Returns: List of dictionaries containing the single key “player” and value of each YFPY Player instance containing the keys “draft_analysis”, “ownership”, “percent_owned”, and “player_stats”, which each return instances of their respective YFPY objects.
Return type: list[dict[str, Player]]

get_team_roster_player_info_by_week(team_id, chosen_week='current')[source]

Retrieve roster with ALL player info of specific team by team_id and by week for chosen league.

Parameters

team_id (str | int) – Selected team ID for which to retrieva data (can be integers 1 through n where n is the number of teams in the league).
chosen_week (int) – Selected week for which to retrieve data.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_team_roster_player_info_by_week(1, 1)
[
  {
    "player": {
      "bye_weeks": {
        "week": "10"
      },
      "display_position": "QB",
      "draft_analysis": {
        "average_pick": "65.9",
        "average_round": "7.6",
        "average_cost": "5.0",
        "percent_drafted": "1.00"
      },
      "editorial_player_key": "nfl.p.5228",
      "editorial_team_abbr": "NE",
      "editorial_team_full_name": "New England Patriots",
      "editorial_team_key": "nfl.t.17",
      "eligible_positions": {
        "position": "QB"
      },
      "has_player_notes": 1,
      "headshot": {
        "size": "small",
        "url": "https://s.yimg.com/iu/api/res/1.2/_U9UJlrYMsJ22DpA..S3zg--~C
            /YXBwaWQ9eXNwb3J0cztjaD0yMzM2O2NyPTE7Y3c9MTc5MDtkeD04NTc7ZHk9MDtmaT11bGNyb3A7aD02MDtxPTEwMDt3PTQ2/https://s.yimg.com/xe/i/us/sp/v/nfl_cutout/players_l/08212019/5228.png"
      },
      "is_undroppable": "0",
      "name": {
        "ascii_first": "Tom",
        "ascii_last": "Brady",
        "first": "Tom",
        "full": "Tom Brady",
        "last": "Brady"
      },
      "ownership": {
        "ownership_type": "team",
        "owner_team_key": "331.l.729259.t.1",
        "owner_team_name": "Hellacious Hill 12"
      },
      "percent_owned": {
        "coverage_type": "week",
        "week": "17",
        "value": 99,
        "delta": "0"
      },
      "player_id": "5228",
      "player_key": "331.p.5228",
      "player_notes_last_timestamp": 1568837880,
      "player_points": {
        "coverage_type": "week",
        "week": "1",
        "total": 10.26
      },
      "player_stats": {
        "coverage_type": "week",
        "week": "1",
        "stats": [
          {
            "stat": {
              "stat_id": "4",
              "value": "249"
            }
          },
          ...
        ]
      },
      "position_type": "O",
      "primary_position": "QB",
      "selected_position": {
        "coverage_type": "week",
        "is_flex": 0,
        "position": "QB",
        "week": "1"
      },
      "uniform_number": "12"
    }
  },
  ...
]

Returns: List of dictionaries containing the single key “player” and value of each YFPY Player instance containing the keys “draft_analysis”, “ownership”, “percent_owned”, and “player_stats”, which each return instances of their respective YFPY objects.
Return type: list[dict[str, Player]]

get_team_roster_player_stats(team_id)[source]

Retrieve roster with ALL player info for the season of specific team by team_id and for chosen league.

Parameters: team_id (str | int) – Selected team ID for which to retrieva data (can be integers 1 through n where n is the number of teams in the league).

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_team_roster_player_stats(1)
[
  {
    "player": {
      "bye_weeks": {
        "week": "10"
      },
      "display_position": "QB",
      "draft_analysis": {
        "average_pick": "65.9",
        "average_round": "7.6",
        "average_cost": "5.0",
        "percent_drafted": "1.00"
      },
      "editorial_player_key": "nfl.p.5228",
      "editorial_team_abbr": "NE",
      "editorial_team_full_name": "New England Patriots",
      "editorial_team_key": "nfl.t.17",
      "eligible_positions": {
        "position": "QB"
      },
      "has_player_notes": 1,
      "headshot": {
        "size": "small",
        "url": "https://s.yimg.com/iu/api/res/1.2/_U9UJlrYMsJ22DpA..S3zg--~C
            /YXBwaWQ9eXNwb3J0cztjaD0yMzM2O2NyPTE7Y3c9MTc5MDtkeD04NTc7ZHk9MDtmaT11bGNyb3A7aD02MDtxPTEwMDt3PTQ2/https://s.yimg.com/xe/i/us/sp/v/nfl_cutout/players_l/08212019/5228.png"
      },
      "is_undroppable": "0",
      "name": {
        "ascii_first": "Tom",
        "ascii_last": "Brady",
        "first": "Tom",
        "full": "Tom Brady",
        "last": "Brady"
      },
      "player_id": "5228",
      "player_key": "331.p.5228",
      "player_notes_last_timestamp": 1568837880,
      "player_points": {
        "coverage_type": "season",
        "total": 287.06
      },
      "player_stats": {
        "coverage_type": "season",
        "stats": [
          {
            "stat": {
              "stat_id": "4",
              "value": "4109"
            }
          },
          ...
        ]
      },
      "position_type": "O",
      "primary_position": "QB",
      "selected_position": {
        "coverage_type": "week",
        "is_flex": 0,
        "position": "QB",
        "week": "16"
      },
      "uniform_number": "12"
    }
  },
  ...
]

Returns: List of dictionaries with key = “player” and value = YFPY Player instance containing the keys “draft_analysis”, “ownership”, “percent_owned”, and “player_stats”, which each return instances of their respective YFPY objects.
Return type: list[dict[str, Player]]

get_team_roster_player_stats_by_week(team_id, chosen_week='current')[source]

Retrieve roster with player stats of specific team by team_id and by week for chosen league.

Parameters

team_id (str | int) – Selected team ID for which to retrieva data (can be integers 1 through n where n is the number of teams in the league).
chosen_week (int) – Selected week for which to retrieve data.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_team_roster_player_stats_by_week(1, 1)
[
  {
    "player": {
      "bye_weeks": {
        "week": "10"
      },
      "display_position": "QB",
      "editorial_player_key": "nfl.p.5228",
      "editorial_team_abbr": "NE",
      "editorial_team_full_name": "New England Patriots",
      "editorial_team_key": "nfl.t.17",
      "eligible_positions": {
        "position": "QB"
      },
      "has_player_notes": 1,
      "headshot": {
        "size": "small",
        "url": "https://s.yimg.com/iu/api/res/1.2/_U9UJlrYMsJ22DpA..S3zg--~C
            /YXBwaWQ9eXNwb3J0cztjaD0yMzM2O2NyPTE7Y3c9MTc5MDtkeD04NTc7ZHk9MDtmaT11bGNyb3A7aD02MDtxPTEwMDt
            3PTQ2/https://s.yimg.com/xe/i/us/sp/v/nfl_cutout/players_l/08212019/5228.png"
      },
      "is_undroppable": "0",
      "name": {
        "ascii_first": "Tom",
        "ascii_last": "Brady",
        "first": "Tom",
        "full": "Tom Brady",
        "last": "Brady"
      },
      "player_id": "5228",
      "player_key": "331.p.5228",
      "player_notes_last_timestamp": 1568837880,
      "player_points": {
        "coverage_type": "week",
        "week": "1",
        "total": 10.26
      },
      "player_stats": {
        "coverage_type": "week",
        "week": "1",
        "stats": [
          {
            "stat": {
              "stat_id": "4",
              "value": "249"
            }
          },
          ...
        ]
      },
      "position_type": "O",
      "primary_position": "QB",
      "selected_position": {
        "coverage_type": "week",
        "is_flex": 0,
        "position": "QB",
        "week": "1"
      },
      "uniform_number": "12"
    }
  },
  ...
]

Returns: List of dictionaries with key = “player” and value = YFPY Player instance containing the “player_stats” key (returns a YFPY PlayerStats instance).
Return type: list[dict[str, Player]]

get_team_standings(team_id)[source]

Retrieve standings of specific team by team_id for chosen league.

Parameters: team_id (str | int) – Selected team ID for which to retrieva data (can be integers 1 through n where n is the number of teams in the league).

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_team_standings(1)
{
  "rank": 2,
  "playoff_seed": "2",
  "outcome_totals": {
    "losses": 5,
    "percentage": 0.643,
    "ties": 0,
    "wins": 9
  },
  "streak": {
    "type": "win",
    "value": "1"
  },
  "points_for": "1409.24",
  "points_against": 1266.6599999999999
}

Returns: YFPY TeamStandings instance.
Return type: TeamStandings

get_team_stats(team_id)[source]

Retrieve stats of specific team by team_id for chosen league.

Parameters: team_id (str | int) – Selected team ID for which to retrieva data (can be integers 1 through n where n is the number of teams in the league).

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_team_stats(1)
{
  "coverage_type": "season",
  "season": "2014",
  "total": "1409.24"
}

Returns: YFPY TeamPoints instance.
Return type: TeamPoints

get_team_stats_by_week(team_id, chosen_week='current')[source]

Retrieve stats of specific team by team_id and by week for chosen league.

Parameters

team_id (str | int) – Selected team ID for which to retrieva data (can be integers 1 through n where n is the number of teams in the league).
chosen_week (int) – Selected week for which to retrieve data.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_team_stats_by_week(1, 1)
{
  "team_points": {
    "coverage_type": "week",
    "total": "95.06",
    "week": "1"
  },
  "team_projected_points": {
    "coverage_type": "week",
    "total": "78.85",
    "week": "1"
  }
}

Returns: Dictionary containing both a YFPY TeamPoints instance and a YFPY TeamProjectedPoints instance with respective keys “team_points” and “team_projected_points”.
Return type: dict[str, TeamPoints | TeamProjectedPoints]

get_user_games()[source]

Retrieve game history for current logged-in user sorted by season/year.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_user_games()
[
  {
    "game": {
      "code": "nfl",
      "game_id": "359",
      "game_key": "359",
      "is_game_over": 1,
      "is_offseason": 1,
      "is_registration_over": 1,
      "name": "Football",
      "season": "2016",
      "type": "full",
      "url": "https://football.fantasysports.yahoo.com/archive/nfl/2016"
    }
  },
  ...
]

Returns: List of dictionaries containing the single key “game” and value of each YFPY Game instance.
Return type: list[dict[str, Game]]

get_user_leagues_by_game_key(game_key)[source]

Retrieve league history for current logged-in user for specific game by game IDs/keys sorted by season/year.

Parameters: game_key (int | str) – The game_id (int) or game_key (str) for a specific Yahoo Fantasy game.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_user_leagues_by_game_key(331)
[
  {
    "league": {
      "allow_add_to_dl_extra_pos": 0,
      "current_week": "16",
      "draft_status": "postdraft",
      "edit_key": "16",
      "end_date": "2018-12-24",
      "end_week": "16",
      "game_code": "nfl",
      "iris_group_chat_id": "<group chat id>",
      "is_cash_league": "0",
      "is_finished": 1,
      "is_pro_league": "0",
      "league_id": "169896",
      "league_key": "380.l.169896",
      "league_type": "private",
      "league_update_timestamp": "1546498723",
      "logo_url": "<logo url>",
      "name": "League Name",
      "num_teams": 12,
      "password": null,
      "renew": "371_52364",
      "renewed": "390_78725",
      "scoring_type": "head",
      "season": "2018",
      "short_invitation_url": "<invite url>",
      "start_date": "2018-09-06",
      "start_week": "1",
      "url": "<league url>",
      "weekly_deadline": null
    }
  }
]

Returns: List of dictionaries containing the single key “league” and value of each YFPY League instance.
Return type: list[dict[str, League]]

get_user_teams()[source]

Retrieve teams for all leagues for current logged-in user for current game sorted by season/year.

Examples

>>> from pathlib import Path
>>> from yfpy.query import YahooFantasySportsQuery
>>> query = YahooFantasySportsQuery(Path("/path/to/auth/directory"), league_id="######")
>>> query.get_user_teams()
[
  {
    "game": {
      "code": "nfl",
      "game_id": "359",
      "game_key": "359",
      "is_game_over": 1,
      "is_offseason": 1,
      "is_registration_over": 1,
      "name": "Football",
      "season": "2016",
      "teams": [
        {
          "team": {
            "draft_grade": "A",
            "draft_position": 9,
            "draft_recap_url": "<draft recap url>",
            "has_draft_grade": 1,
            "league_scoring_type": "head",
            "managers": [
              {
                "manager": {
                  "email": "<manager email>",
                  "guid": "<manager user guid>",
                  "image_url": "<manager user image url>",
                  "is_comanager": "1",
                  "manager_id": "14",
                  "nickname": "<manager nickname>"
                }
              }
            ],
            "name": "Legion",
            "number_of_moves": "48",
            "number_of_trades": "2",
            "roster_adds": {
              "coverage_type": "week",
              "coverage_value": "17",
              "value": "0"
            },
            "team_id": "1",
            "team_key": "359.l.5521.t.1",
            "team_logos": {
              "team_logo": {
                "size": "large",
                "url": "<logo url>"
              }
            },
            "url": "<team url>",
            "waiver_priority": 11
          }
        }
      ],
      "type": "full",
      "url": "https://football.fantasysports.yahoo.com/archive/nfl/2016"
    }
  }

]

Returns: List of dictionaries containing the single key “game” and value of each YFPY Game instance with “teams” field containing list of YFPY Team instances.
Return type: list[dict[str, Game]]

query(url, data_key_list, data_type_class=None, sort_function=None)[source]

Base query class to retrieve requested data from the Yahoo fantasy sports REST API.

Parameters

url (str) – REST API request URL string.
data_key_list (list[str] | list[list[str]]) – List of keys used to extract the specific data desired by the given query (supports strings and lists of strings). Supports lists containing only key strings such as [“game”, “stat_categories”], and also supports lists containing key strings and lists of key strings such as [“team”, [“team_points”, “team_projected_points”]].
data_type_class (Type, optional) – Highest level data model type (if one exists for the retrieved data).
sort_function (Callable of sort function, optional)) – Optional lambda function to return sorted query results.

Returns

Model class instance from yfpy/models.py, dictionary, or list (depending on query), with unpacked and parsed response data.

Return type

object