[Bug] get_player_stats_by_week() Returns Empty Stats

[jcbluemel]

Description

The get_player_stats_by_week() method returns a Player object with an empty player_stats object, even when querying for players who played in that week. The Yahoo Fantasy API returns the data successfully, but yfpy is unable to parse the stats from the response.

Environment

• yfpy version: 1.2.7
• Python version: 3.12
• Sport: NBA (game_code: "nba", game_id: 466)
• Query method: get_player_stats_by_week(player_key, chosen_week, limit_to_league_stats=True/False)

Expected Behavior

When calling get_player_stats_by_week() for a player who played in a given week, the method should return a Player object with populated player_stats containing the weekly statistics.

Actual Behavior

The method returns a Player object with player identity information (name, team, etc.) but player_stats is an empty PlayerStats({}) object with no stats.

player_stats.stats = []  # Empty list
player_stats.coverage_type = ''  # Empty string
player_stats.week = None  # No week information

Reproduction

from yfpy.query import YahooFantasySportsQuery

query = YahooFantasySportsQuery(
    game_code="nba",
    game_id=466,
    league_id=LEAGUE_ID,
    yahoo_consumer_key="YOUR_KEY",
    yahoo_consumer_secret="YOUR_SECRET",
    env_file_location="path/to/.env"
)

# Test with a known player who played in week 4
week_stats = query.get_player_stats_by_week(
    player_key="466.p.6679",  # Brandon Williams
    chosen_week=4,
    limit_to_league_stats=True
)

print(f"Player: {week_stats.name.full}")
print(f"Has player_stats: {hasattr(week_stats, 'player_stats')}")
print(f"player_stats: {week_stats.player_stats}")
print(f"Stats count: {len(week_stats.player_stats.stats)}")

Output:

Player: Brandon Williams
Has player_stats: True
player_stats: PlayerStats({})
Stats count: 0

Investigation

API Response Analysis

The Yahoo Fantasy API does return data successfully. The response is approximately 1400 bytes and contains the player information, but the stats are not being extracted by yfpy.

Testing both query modes:

1. With limit_to_league_stats=True (default):

   • URL: https://fantasysports.yahooapis.com/fantasy/v2/league/466.l.12558/players;player_keys=466.p.6679/stats;type=week;week=4
   • Response: 200 OK (1397 bytes)
   • Result: Empty stats

2. With limit_to_league_stats=False:

   • URL: https://fantasysports.yahooapis.com/fantasy/v2/players;player_keys=466.p.6679/stats;type=week;week=4
   • Response: 200 OK
   • Result: Empty stats

Raw API Response Structure

When examining the raw JSON response from the Yahoo API, the player data is nested in an array structure:

{
  "fantasy_content": {
    "league": [
      { /* league metadata */ },
      {
        "players": {
          "0": {
            "player": [
              [
                { "player_key": "466.p.6679" },
                { "player_id": "6679" },
                { "name": { ... } },
                /* ... player attributes ... */
                /* NOTE: No player_stats object found in this structure */
              ]
            ]
          }
        }
      }
    ]
  }
}

The stats are not included in the response when querying individual players by week, despite the URL including ;type=week;week=4 parameters.

Root Cause

The Yahoo Fantasy Sports API does not return weekly player stats when querying individual players directly through:

• /league/{league_key}/players;player_keys={key}/stats;type=week;week={week}
• /players;player_keys={key}/stats;type=week;week={week}

This appears to be a limitation of the Yahoo Fantasy API itself, not a parsing bug in yfpy.

Workaround

Weekly player stats can be retrieved using the team roster endpoint:

# Instead of querying player directly, query team rosters
standings = query.get_league_standings()

for team in standings.teams:
    roster_stats = query.get_team_roster_player_stats_by_week(
        team.team_id,
        chosen_week=4
    )

    for player in roster_stats:
        if player.player_id == "6679":  # Brandon Williams
            print(f"Player: {player.name.full}")
            print(f"Stats count: {len(player.player_stats.stats)}")
            for stat in player.player_stats.stats:
                print(f"  Stat ID {stat.stat_id}: {stat.value}")

Output:

Player: Brandon Williams
Stats count: 11
  Stat ID 9004003: 0.0  # (FGM/FGA - see composite stats bug)
  Stat ID 5: 0.409     # FG%
  Stat ID 9007006: 0.0  # (FTM/FTA)
  Stat ID 8: 0.875     # FT%
  Stat ID 10: 1.0      # 3PTM
  Stat ID 12: 58.0     # PTS
  Stat ID 15: 16.0     # REB
  Stat ID 16: 23.0     # AST
  Stat ID 17: 7.0      # STL
  Stat ID 18: 0.0      # BLK
  Stat ID 19: 9.0      # TO

Questions for Maintainers

1. Is this a known Yahoo API limitation? Have other sports/endpoints shown similar behavior?

2. Should the method documentation be updated to clarify that weekly player stats are only available through team roster queries?

3. Should get_player_stats_by_week() raise a warning or exception when it detects empty stats, rather than returning an empty PlayerStats object?

Proposed Documentation Update

If this is a Yahoo API limitation rather than a fixable bug, the documentation for get_player_stats_by_week() should include:

def get_player_stats_by_week(self, player_key: str, chosen_week: Union[int, str] = "current",
                             limit_to_league_stats: bool = True) -> Player:
    """Retrieve stats of specific player by player_key and by week for chosen league.

    **Note**: The Yahoo Fantasy API may not return weekly stats when querying
    individual players directly. If player_stats is empty, use
    get_team_roster_player_stats_by_week() instead to retrieve weekly player
    statistics through team rosters.

    Args:
        player_key (str): The player key of chosen player
        chosen_week (int): Selected week for which to retrieve data
        limit_to_league_stats (bool): Limit stats to the selected league

    Returns:
        Player: Player instance (may have empty player_stats for weekly queries)
    """

Additional Context

• This issue was discovered while implementing weekly stat tracking for fantasy basketball matchup summaries
• The team roster method (get_team_roster_player_stats_by_week) works correctly and returns complete weekly stats
• Season stats via get_player_stats_for_season() work correctly for individual player queries
• This may be related to how Yahoo structures their API responses differently for collection vs individual resource queries

Related Issues

• Related to PR Fixed get_team_roster_player_stats_by_week #69 (weekly stats aggregation fix)
• Related to composite stats parsing bug (separate issue)

[onurburak9]

Did you solve this issue?