Skip to main content

​
Overview

The draft keepers endpoint provides comprehensive keeper player data for your Yahoo Fantasy Basketball league. It fetches keeper designations for the current season and, when available, automatically retrieves keeper data from the previous season for comparison.

​
Authentication

Requires an active user session with a selected league.

​
Request

This endpoint does not accept any query parameters. It automatically uses the league selected in the user’s session and attempts to fetch previous season data when available.

​
Response

The endpoint returns a structured JSON object containing keeper information organized by team.
​
teams
array
Array of all teams in the league with metadata
​
keepers_by_team
object
Object mapping team keys to arrays of keeper players
​
orphans
array
Array of keeper players without an associated team (rare edge case)
​
metadata
object
Comprehensive metadata about the league and keeper data
​
previous_season
object
Previous season keeper data (only included if previous season exists)

​
Example Success Response

{
  "teams": [
    {
      "team_key": "423.l.12345.t.1",
      "team_name": "Thunder Squad",
      "team_id": "1",
      "manager_name": "John Doe",
      "manager_guid": "ABC123XYZ",
      "is_current_login": true
    }
  ],
  "keepers_by_team": {
    "423.l.12345.t.1": [
      {
        "player_key": "423.p.5479",
        "player_id": "5479",
        "name_full": "Nikola Jokic",
        "display_position": "C",
        "owner_team_key": "423.l.12345.t.1",
        "badge": "Keeper",
        "nba_id": 203999,
        "is_keeper": true
      }
    ]
  },
  "orphans": [],
  "metadata": {
    "league_key": "423.l.12345",
    "league_name": "Fantasy Hoops League",
    "season": "2024",
    "scoring_type": "head",
    "generated_at": "2024-03-15T10:30:00Z",
    "previous_league_key": "418.l.12345",
    "previous_season": "2023",
    "current_keeper_count": 12,
    "previous_keeper_count": 10,
    "user_team_keys": ["423.l.12345.t.1"],
    "user_team_ids": ["1"],
    "user_team_names": ["Thunder Squad"],
    "user_manager_guids": ["ABC123XYZ"],
    "available_seasons": ["2024", "2023"],
    "fallback_to_previous": false
  },
  "previous_season": {
    "league_key": "418.l.12345",
    "season": "2023",
    "teams": [...],
    "keepers_by_team": {...},
    "orphans": []
  }
}

​
Error Responses

​
error
string
Error message describing what went wrong

​
Possible Errors

  • 401 Unauthorized - User not authenticated 
    {"error": "authentication required"}
  • 400 Bad Request - No league selected 
    {"error": "no league chosen"}
  • 502 Bad Gateway or other status - Yahoo API error 
    {"error": "Failed to fetch keeper data from Yahoo."}
  • 500 Internal Server Error - Unexpected error 
    {"error": "Error details"}

​
Example Request

curl -X GET "https://your-domain.com/api/draft/keepers" \
  -H "Cookie: session=your-session-cookie"

​
Implementation Details

This endpoint is implemented in main.py:502-695 and performs a sophisticated multi-step process:

​
Data Fetching

  1. Fetches current season keeper players: fantasy/v2/league/{league_key}/players;status=K;out=ownership
  2. Fetches current season team data: fantasy/v2/league/{league_key}/teams
  3. Optionally fetches league settings for additional context
  4. Attempts to identify and fetch previous season data automatically

​
Previous Season Discovery

The endpoint intelligently discovers previous season league keys through:
  • Checking renewed field in league payload
  • Checking renew field as fallback
  • Normalizing league key formats (handles both game.l.league and game_league formats)

​
NBA Player ID Enrichment

For each keeper player, the endpoint:
  • Calls _lookup_nba_player_id() to match Yahoo player names to NBA API player IDs
  • Uses sophisticated name normalization to handle name variations
  • Caches lookups for performance
  • Returns null if no match is found

​
User Team Identification

The endpoint identifies the current user’s teams using multiple signals:
  • Session team name matching (case-insensitive)
  • Manager GUID matching across seasons
  • Team ID matching across seasons
  • is_current_login flag from Yahoo API
This multi-method approach ensures accurate user team identification even when:
  • Team names change between seasons
  • Multiple teams are owned by the same user
  • Manager accounts are shared

​
Data Organization

Keepers are organized by team key for efficient lookup:
  • Players sorted alphabetically by full name within each team
  • Orphaned players (missing owner_team_key) tracked separately
  • Metadata includes counts for quick overview

​
Use Cases

  • Display keeper selections in draft preparation tools
  • Compare current vs. previous season keeper decisions
  • Build keeper value analysis and trends
  • Show which players are unavailable in upcoming drafts
  • Identify keeper patterns across the league
  • Help users make keeper selection decisions

​
Notes

  • Previous season data is best-effort; not all leagues expose prior season links
  • NBA ID matching is fuzzy and may not find all players (especially rookies)
  • The fallback_to_previous flag suggests when to display previous season data
  • Empty keeper lists may indicate pre-draft timing or leagues without keeper rules
  • Manager GUID matching works across seasons for consistent user identification

Build docs developers (and LLMs) love

Get started for freeTalk to us