yahoo-fantasy-api

Yahoo Fantasy Sports API client for Node.js with OAuth 2.0 authentication, automatic token refresh, rate limiting, and CLI tools.

Works with any Yahoo Fantasy sport (MLB, NHL, NFL, NBA).

Installation

npm install yahoo-fantasy-api

Setup

1. Create a Yahoo App

1. Go to Yahoo Developer
2. Create a new app with Fantasy Sports read permissions
3. Set the redirect URI to https://localhost:3000/auth/callback
4. Note your Client ID and Client Secret

2. Configure Environment

Create a .env file:

YAHOO_CLIENT_ID=your_client_id
YAHOO_CLIENT_SECRET=your_client_secret
YAHOO_REDIRECT_URI=https://localhost:3000/auth/callback

3. Generate SSL Certificates

Yahoo requires HTTPS for OAuth callbacks. Generate self-signed certs:

mkdir certs
openssl req -x509 -newkey rsa:2048 -keyout certs/key.pem -out certs/cert.pem -days 365 -nodes -subj '/CN=localhost'

4. Authenticate

npx yahoo-fantasy-api authenticate

This opens an HTTPS server on localhost:3000, prints an authorization URL, and waits for the OAuth callback. The token is saved to .yahoo-token.json and auto-refreshes.

CLI Usage

npx yahoo-fantasy-api authenticate      # Interactive OAuth flow
npx yahoo-fantasy-api token-status      # Check token expiry
npx yahoo-fantasy-api list-leagues      # Discover all your leagues
npx yahoo-fantasy-api league-settings   # Pull settings for all leagues
npx yahoo-fantasy-api league-settings 469.l.75479  # Specific league

Programmatic Usage

require('dotenv').config();
const { createClient } = require('yahoo-fantasy-api');

const { auth, client } = createClient({
  tokenFile: '.yahoo-token.json',
  certsDir: 'certs',
});

// Discover leagues
const leagues = await client.getUserLeagues(['mlb', 'nhl']);

// Get league settings
const settings = await client.getLeagueSettings('469.l.75479');

// Get teams in a league
const teams = await client.getLeagueTeams('469.l.75479');

// Get draft results
const picks = await client.getDraftResults('469.l.75479');

// Raw API call to any endpoint
const data = await client.get('/league/469.l.75479/scoreboard');

createClient(options)

Returns { auth, client } — a YahooAuth instance and a YahooClient instance.

| Option | Default | Description | |--------|---------|-------------| | clientId | YAHOO_CLIENT_ID env | OAuth client ID | | clientSecret | YAHOO_CLIENT_SECRET env | OAuth client secret | | redirectUri | https://localhost:3000/auth/callback | OAuth redirect URI | | tokenFile | .yahoo-token.json | Path to token storage | | certsDir | certs/ | Path to SSL certificates | | minInterval | 2000 | Minimum ms between API calls | | log | console.log | Custom logging function |

Client Methods

client.get(endpoint)

Rate-limited GET request. Handles token refresh on 401 and retries on Yahoo's 999 rate limit. All other methods are built on this.

client.getUserLeagues(gameCodes)

Discover all leagues for the authenticated user. gameCodes defaults to ['mlb', 'nhl'].

client.resolveGameKey(gameCode)

Map a game code ('mlb', 'nhl') to Yahoo's numeric game key. Cached after first call.

client.leagueKey(gameKey, leagueId)

Helper to build a league key string (e.g., '469.l.75479').

client.getLeagueSettings(leagueKey)

Fetch roster positions, stat categories, and league configuration.

client.getLeagueTeams(leagueKey)

Fetch all teams with names and manager info.

client.getDraftResults(leagueKey)

Fetch draft picks with costs (for auction leagues).

Yahoo API Notes

• Base URL: https://fantasysports.yahooapis.com/fantasy/v2
• All endpoints work identically across sports — only the game key differs
• Rate limit: client enforces 2s minimum between calls (configurable)
• Yahoo 999 errors: automatic 5s backoff + retry
• Token auto-refreshes 5 minutes before expiry
• Settings quirk: /league/{key}/settings returns stale predraft data. Use /league/{key};out=settings instead (this client handles it correctly).
• Weekly stats quirk: ;out=stats;type=week;week=N returns wrong data. Use the subresource syntax /players/stats;type=week;week=N (slash before stats).
• Positions are always current: selected_position always reflects the current roster, never historical.

License

MIT