yfpy.query.YahooFantasySportsQuery

class YahooFantasySportsQuery(auth_dir, league_id, game_id=None, game_code='nfl', offline=False, all_output_as_json=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 (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

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 ID 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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) – 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 ID sorted by season/year.

Parameters

game_key (int) – The game_id 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)[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).

Returns

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

Return type

object