Class: SleeperApi::Client

Inherits:
Object
  • Object
show all
Includes:
HTTParty, Helpers
Defined in:
lib/sleeper_api/client.rb

Overview

HTTP client for Sleeper API requests.

Handles all low-level HTTP calls, caching, retries, and error handling. Use via client or create directly.

Examples:

client = SleeperApi::Client.new(config)
league = client.league("123456")
user = client.user("username")

Instance Method Summary collapse

Methods included from Helpers

#deep_symbolize_keys, #player_details

Constructor Details

#initialize(config) ⇒ Client

Returns a new instance of Client.

Parameters:



26
27
28
29
30
 
# File 'lib/sleeper_api/client.rb', line 26

def initialize(config)
  @config = config
  @players_cache = nil
  @cache_timestamp = nil
end

Instance Method Details

#draft(draft_id) ⇒ SleeperApi::Draft

Create a new Draft instance.

Parameters:

  • draft_id (String) —

    Draft identifier

Returns:

See Also:



55
56
57
 
# File 'lib/sleeper_api/client.rb', line 55

def draft(draft_id)
  Draft.new(draft_id, self)
end

#get_draft(draft_id) ⇒ Hash

Fetch draft details.

Parameters:

  • draft_id (String, Integer) —

    Draft ID

Returns:

  • (Hash) —

    Draft metadata

See Also:



178
179
180
 
# File 'lib/sleeper_api/client.rb', line 178

def get_draft(draft_id)
  make_request("/v1/draft/#{draft_id}")
end

#get_draft_picks(draft_id) ⇒ Array<Hash>

Get draft picks.

Parameters:

  • draft_id (String, Integer) —

    Draft ID

Returns:

  • (Array<Hash>) —

    Pick data

See Also:



187
188
189
 
# File 'lib/sleeper_api/client.rb', line 187

def get_draft_picks(draft_id)
  make_request("/v1/draft/#{draft_id}/picks")
end

#get_draft_traded_picks(draft_id) ⇒ Array<Hash>

Get traded draft picks for a draft.

Parameters:

  • draft_id (String, Integer) —

    Draft ID

Returns:

  • (Array<Hash>) —

    Traded picks

See Also:



196
197
198
 
# File 'lib/sleeper_api/client.rb', line 196

def get_draft_traded_picks(draft_id)
  make_request("/v1/draft/#{draft_id}/traded_picks")
end

#get_league(league_id) ⇒ Hash

Fetch league details.

Parameters:

  • league_id (String) —

    League ID

Returns:

  • (Hash) —

    League metadata

See Also:



95
96
97
 
# File 'lib/sleeper_api/client.rb', line 95

def get_league(league_id)
  make_request("/v1/league/#{league_id}")
end

#get_league_drafts(league_id) ⇒ Array<Hash>

Get league drafts.

Parameters:

  • league_id (String, Integer) —

    League ID

Returns:

  • (Array<Hash>) —

    Draft data

See Also:



160
161
162
 
# File 'lib/sleeper_api/client.rb', line 160

def get_league_drafts(league_id)
  make_request("/v1/league/#{league_id}/drafts")
end

#get_league_matchups(league_id, week) ⇒ Array<Hash>

Get matchups for a specific week.

Parameters:

  • league_id (String, Integer) —

    League ID

  • week (Integer) —

    Week number (1-17)

Returns:

  • (Array<Hash>) —

    Matchup data

See Also:



123
124
125
 
# File 'lib/sleeper_api/client.rb', line 123

def get_league_matchups(league_id, week)
  make_request("/v1/league/#{league_id}/matchups/#{week}")
end

#get_league_rosters(league_id) ⇒ Array<Hash>

Get all rosters in a league.

Parameters:

  • league_id (String) —

    League ID

Returns:

  • (Array<Hash>) —

    Roster data

See Also:



104
105
106
 
# File 'lib/sleeper_api/client.rb', line 104

def get_league_rosters(league_id)
  make_request("/v1/league/#{league_id}/rosters")
end

#get_league_traded_picks(league_id) ⇒ Array<Hash>

Get traded draft picks for a league.

Parameters:

  • league_id (String, Integer) —

    League ID

Returns:

  • (Array<Hash>) —

    Traded picks

See Also:



169
170
171
 
# File 'lib/sleeper_api/client.rb', line 169

def get_league_traded_picks(league_id)
  make_request("/v1/league/#{league_id}/traded_picks")
end

#get_league_users(league_id) ⇒ Array<Hash>

Get all users in a league.

Parameters:

  • league_id (String, Integer) —

    League ID

Returns:

  • (Array<Hash>) —

    User data

See Also:



113
114
115
 
# File 'lib/sleeper_api/client.rb', line 113

def get_league_users(league_id)
  make_request("/v1/league/#{league_id}/users")
end

#get_nfl_state(sport = "nfl") ⇒ Hash

Get NFL state (week, season status).

Parameters:

  • sport (String) (defaults to: "nfl") —

    Sport code (default: "nfl")

Returns:

  • (Hash) —

    State data

See Also:



205
206
207
208
209
210
211
 
# File 'lib/sleeper_api/client.rb', line 205

def get_nfl_state(sport = "nfl")
  nfl_state = make_request("/v1/state/#{sport}")
  nfl_state.each_with_object({}) do |(k, v), result|
    key = k.is_a?(String) ? k.to_sym : k
    result[key] = v
  end
end

#get_player_by_id(player_id, sport = "nfl") ⇒ Hash?

Get a specific player by ID.

Parameters:

  • player_id (String) —

    Player ID

  • sport (String) (defaults to: "nfl") —

    Sport code (default: "nfl")

Returns:

  • (Hash, nil) —

    Player data or nil if not found

See Also:



317
318
319
 
# File 'lib/sleeper_api/client.rb', line 317

def get_player_by_id(player_id, sport = "nfl")
  get_players(sport)[player_id]
end

#get_players(sport = "nfl") ⇒ Hash{String => Hash}

Get all player data (cached for 24 hours).

Parameters:

  • sport (String) (defaults to: "nfl") —

    Sport code (default: "nfl")

Returns:

  • (Hash{String => Hash}) —

    Player ID to player data mapping

See Also:



301
302
303
304
305
306
307
308
309
 
# File 'lib/sleeper_api/client.rb', line 301

def get_players(sport = "nfl")
  return @players_cache if @players_cache && @cache_timestamp && (Time.now - @cache_timestamp) < (3600 * 24)

  response = make_request("/v1/players/#{sport}")
  @players_cache = response.parsed_response
  @cache_timestamp = Time.now

  @players_cache
end

#get_playoff_bracket(league_id) ⇒ Array<Hash>

Get playoff winners bracket.

Parameters:

  • league_id (String, Integer) —

    League ID

Returns:

  • (Array<Hash>) —

    Bracket matchups

See Also:



132
133
134
 
# File 'lib/sleeper_api/client.rb', line 132

def get_playoff_bracket(league_id)
  make_request("/v1/league/#{league_id}/winners_bracket")
end

#get_toilet_bowl(league_id) ⇒ Array<Hash>

Get toilet bowl (losers bracket).

Parameters:

  • league_id (String, Integer) —

    League ID

Returns:

  • (Array<Hash>) —

    Bracket matchups

See Also:



141
142
143
 
# File 'lib/sleeper_api/client.rb', line 141

def get_toilet_bowl(league_id)
  make_request("/v1/league/#{league_id}/losers_bracket")
end

#get_transactions(league_id, week) ⇒ Array<Hash>

Get transactions for a specific week.

Parameters:

  • league_id (String, Integer) —

    League ID

  • week (Integer) —

    Week number

Returns:

  • (Array<Hash>) —

    Transaction data

See Also:



151
152
153
 
# File 'lib/sleeper_api/client.rb', line 151

def get_transactions(league_id, week)
  make_request("/v1/league/#{league_id}/transactions/#{week}")
end

#get_user(identifier) ⇒ Hash

Fetch user data by identifier.

Parameters:

  • identifier (String) —

    Username or user ID

Returns:

  • (Hash) —

    Raw user data

See Also:



64
65
66
 
# File 'lib/sleeper_api/client.rb', line 64

def get_user(identifier)
  make_request("/v1/user/#{identifier}")
end

#get_user_drafts(user_id, sport: "nfl", season: Time.now.year) ⇒ Array<Hash>

Get drafts for a user in a specific season.

Parameters:

  • user_id (String) —

    User ID

  • sport (String) (defaults to: "nfl") —

    Sport code (default: "nfl")

  • season (Integer) (defaults to: Time.now.year) —

    Season year (default: current year)

Returns:

  • (Array<Hash>) —

    Draft data

See Also:



86
87
88
 
# File 'lib/sleeper_api/client.rb', line 86

def get_user_drafts(user_id, sport: "nfl", season: Time.now.year)
  make_request("/v1/user/#{user_id}/drafts/#{sport}/#{season}")
end

#get_user_leagues(user_id, sport: "nfl", season: Time.now.year) ⇒ Array<Hash>

Get leagues for a user in a specific season.

Parameters:

  • user_id (String) —

    User ID

  • sport (String) (defaults to: "nfl") —

    Sport code (default: "nfl")

  • season (Integer) (defaults to: Time.now.year) —

    Season year (default: current year)

Returns:

  • (Array<Hash>) —

    League data

See Also:



75
76
77
 
# File 'lib/sleeper_api/client.rb', line 75

def get_user_leagues(user_id, sport: "nfl", season: Time.now.year)
  make_request("/v1/user/#{user_id}/leagues/#{sport}/#{season}")
end

#league(league_id) ⇒ SleeperApi::League

Create a new League instance.

Parameters:

  • league_id (String) —

    League identifier

Returns:

See Also:



37
38
39
 
# File 'lib/sleeper_api/client.rb', line 37

def league(league_id)
  League.new(league_id, self)
end

#projections(season, week: nil, season_type: "regular", sport: "nfl") ⇒ HTTParty::Response

Get per-player projections for one week, or for a whole season.

Same shape and same caveats as #stats, with one of its own: for a season Sleeper has not projected, this still returns a full set of entries — 9,386 of them for 2030 — every one holding only {"adp_dd_ppr" => 1000.0} and no pts_ppr at all. A row count is not evidence of a projection. Filter on the field you actually want.

adp_dd_ppr 1000.0 and pos_rank_* 999.0 are "unknown" sentinels rather than values.

Parameters:

  • season (Integer, String) —

    Season year, e.g. 2026

  • week (Integer, String, nil) (defaults to: nil) —

    Week number, or nil for season totals

  • season_type (String) (defaults to: "regular") —

    "regular" (default), "pre", or "post"

  • sport (String) (defaults to: "nfl") —

    Sport code (default: "nfl")

Returns:

  • (HTTParty::Response) —

    Player id to projections mapping



257
258
259
 
# File 'lib/sleeper_api/client.rb', line 257

def projections(season, week: nil, season_type: "regular", sport: "nfl")
  make_request(weekly_path("projections", sport, season_type, season, week))
end

#schedule(season, season_type: "regular", sport: "nfl") ⇒ HTTParty::Response

Get a season's game schedule.

Undocumented, and served from the host root rather than /v1 — hence the version living in the paths rather than in base_uri.

Returns a flat array of games, each {status, date, home, away, week, game_id}. A team's bye week is the week it appears in no game; that derives exactly, but only within one season type — pre (weeks 1-3) and post (weeks 1-4) restart week numbering, so games from different season types must never be pooled.

A season Sleeper has not scheduled yet answers 200 with an empty array rather than 404, so an empty result is a legitimate answer and not an error.

Parameters:

  • season (Integer, String) —

    Season year, e.g. 2026

  • season_type (String) (defaults to: "regular") —

    "regular" (default), "pre", or "post"

  • sport (String) (defaults to: "nfl") —

    Sport code (default: "nfl")

Returns:

  • (HTTParty::Response) —

    Array of games



280
281
282
 
# File 'lib/sleeper_api/client.rb', line 280

def schedule(season, season_type: "regular", sport: "nfl")
  make_request("/schedule/#{sport}/#{season_type}/#{season}")
end

#stats(season, week: nil, season_type: "regular", sport: "nfl") ⇒ HTTParty::Response

Get per-player statistics for one week, or for a whole season.

Undocumented. Returns an object keyed by player id — plus TEAM_XXX keys for team-level rows — each holding raw counting stats (rec, rush_yd, off_snp, rec_rz_tgt…) alongside Sleeper's three canned point totals pts_ppr / pts_half_ppr / pts_std. 228 distinct fields were observed across one week of 2025.

Nothing here 404s. An unplayed week, a week out of range, and an unrecognised season type all answer 200 with {}, so an empty result is a legitimate answer and is indistinguishable from a typo. Validate the arguments before you trust an empty body.

Omitting week requests season totals, which is a different resource at a shorter path rather than a default of week 1.

pre and post restart week numbering at 1, exactly as #schedule does, so rows from different season types must never be pooled.

Parameters:

  • season (Integer, String) —

    Season year, e.g. 2025

  • week (Integer, String, nil) (defaults to: nil) —

    Week number, or nil for season totals

  • season_type (String) (defaults to: "regular") —

    "regular" (default), "pre", or "post"

  • sport (String) (defaults to: "nfl") —

    Sport code (default: "nfl")

Returns:

  • (HTTParty::Response) —

    Player id to stats mapping



237
238
239
 
# File 'lib/sleeper_api/client.rb', line 237

def stats(season, week: nil, season_type: "regular", sport: "nfl")
  make_request(weekly_path("stats", sport, season_type, season, week))
end

#trending_players(sport = "nfl", type: "add", lookback_hours: 24, limit: 25) ⇒ Array<Hash>

Get trending players.

Parameters:

  • sport (String) (defaults to: "nfl") —

    Sport code (default: "nfl")

  • type (String) (defaults to: "add") —

    Trend type ("add" or "drop", default: "add")

  • lookback_hours (Integer) (defaults to: 24) —

    Hours to look back (default: 24)

  • limit (Integer) (defaults to: 25) —

    Max results (default: 25)

Returns:

  • (Array<Hash>) —

    Trending players

See Also:



292
293
294
 
# File 'lib/sleeper_api/client.rb', line 292

def trending_players(sport = "nfl", type: "add", lookback_hours: 24, limit: 25)
  make_request("/v1/players/#{sport}/trending/#{type}?lookback_hours=#{lookback_hours}&limit=#{limit}")
end

#user(identifier) ⇒ SleeperApi::User

Create a new User instance.

Parameters:

  • identifier (String) —

    Username or user ID

Returns:

See Also:



46
47
48
 
# File 'lib/sleeper_api/client.rb', line 46

def user(identifier)
  User.new(identifier, self)
end