sleeper

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 13, 2026 License: MIT Imports: 11 Imported by: 0

README

go-sleeper

A Go client library for the Sleeper fantasy sports API.

Features

  • Full coverage of Sleeper's public API (leagues, users, drafts, players, transactions, rosters, avatars, sport state)
  • Built-in rate limiter to stay within Sleeper's API guidelines

Installation

go get github.com/dsheehan167/go-sleeper

Usage

package main

import (
	"context"
	"fmt"
	sleeper "github.com/dsheehan167/go-sleeper"
)

func main() {
	ctx := context.Background()

	client, err := sleeper.NewClient(ctx, sleeper.Config{})
	if err != nil {
		panic(err)
	}

	user, err := client.GetUser(ctx, "my_username")
	if err != nil {
		panic(err)
	}
	fmt.Println(user.DisplayName)

	leagues, err := client.GetUserLeagues(ctx, user.UserID, sleeper.SportNFL, "2024")
	if err != nil {
		panic(err)
	}
	fmt.Println(len(leagues), "leagues")
}

Configuration

All fields are optional — zero values use the defaults shown below.

client, err := sleeper.NewClient(ctx, sleeper.Config{
	APIVersion:   sleeper.APIVersion1, // default: v1
	Timeout:      10 * time.Second,    // default: 30s
	RateLimitRPS: 10,                  // default: 15 requests/sec
	RateLimitBurst: 20,                // default: burst of 30
})

Per Sleeper's documentation, staying under 1000 requests per minute avoids IP blocks. The default rate limiter (15 RPS, burst 30) is well within that limit.

API Coverage

Area Methods
Users GetUser, GetUserLeagues
Leagues GetLeague, GetLeagueRosters, GetLeagueUsers, GetLeagueMatchups, GetTransactions, GetLeagueTradedPicks, GetLeagueWinnersBracket, GetLeagueLosersBracket
Drafts GetDraft, GetUserDrafts, GetLeagueDrafts, GetDraftPicks, GetDraftTradedPicks
Players ListNFLPlayers, ListTrendingPlayers
Avatars GetAvatarImage, GetAvatarThumbnail
Sport State GetSportState

Supported sports: SportNFL, SportNBA, SportMLB, SportNHL.

NFL Players

ListNFLPlayers returns the full player map (~5 MB). Sleeper recommends calling this at most once per day and caching the result on your own server rather than fetching it per-request.

To embed Sleeper's official trending list in a web page:

<iframe src="https://sleeper.app/embed/players/nfl/trending/add?lookback_hours=24&limit=25" width="350" height="500" allowtransparency="true" frameborder="0"></iframe>

Please give attribution to Sleeper if you use their trending data.

Documentation

Contributing

This repo uses Conventional Commits. Commit subjects on main should start with one of:

  • feat: — new functionality (minor bump pre-1.0, would be minor post-1.0)
  • fix: — bug fix (patch bump)
  • feat!: / fix!: or BREAKING CHANGE: in body — breaking change (major bump, or minor pre-1.0)
  • chore: / docs: / refactor: / test: / ci: — no release

release-please watches main and opens a release PR that bumps the version, updates CHANGELOG.md, and creates a git tag (e.g. v0.2.0) when merged. Tags are what go get consumes.

License

MIT

Documentation

Index

Constants

View Source 
const (
	TransactionTypeTrade     transactionType = "trade"
	TransactionTypeWaiver    transactionType = "waiver"
	TransactionTypeFreeAgent transactionType = "free_agent"
)
View Source 
const ADPUndrafted = 999.0

ADPUndrafted is the sentinel ADP reported for players not being drafted in a format; filter ADP values below it to get real draft positions.

View Source 
const (
	APIVersion1 apiVersion = "v1"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ADPType added in v0.3.0 

type ADPType string

ADPType selects a league format's average draft position (lower = earlier pick); use it with ProjectionStats.ADP or ProjectionOptions.OrderBy. These match the ADP shown in the Sleeper draft lobby, including for dynasty leagues. All types except ADPTypeDynasty are populated every season. ADPTypeDynasty is erratic — Sleeper filled it for 2022 and 2025 but not 2023, 2024, or 2026 — so prefer the scoring-specific ADPTypeDynasty* types. 

const (
	ADPTypeStandard        ADPType = "adp_std"
	ADPTypeHalfPPR         ADPType = "adp_half_ppr"
	ADPTypePPR             ADPType = "adp_ppr"
	ADPType2QB             ADPType = "adp_2qb"
	ADPTypeDynasty         ADPType = "adp_dynasty"
	ADPTypeDynastyStandard ADPType = "adp_dynasty_std"
	ADPTypeDynastyHalfPPR  ADPType = "adp_dynasty_half_ppr"
	ADPTypeDynastyPPR      ADPType = "adp_dynasty_ppr"
	ADPTypeDynasty2QB      ADPType = "adp_dynasty_2qb"
	ADPTypeIDP             ADPType = "adp_idp"
	ADPTypeIDP1QB          ADPType = "adp_idp_1qb"
)

type APIError 

type APIError struct {
	StatusCode int
	Message    string
}

APIError represents an error response from the Sleeper API

func (*APIError) Error 

func (e *APIError) Error() string

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client represents a client connection to the Sleeper API. A rate limiter is included to help prevent exceeding the API's usage limits. According to the Sleeper API documentation, making more than 1000 requests per minute may result in your IP being blocked. The rate limiter enforces a safe request rate.

func NewClient 

func NewClient(ctx context.Context, config Config) (*Client, error)

NewClient creates a new Client using the provided configuration.

func (*Client) GetAvatarImage 

func (c *Client) GetAvatarImage(ctx context.Context, avatarID string) ([]byte, error)

GetAvatarImage downloads the full-size avatar image and returns the raw bytes

func (*Client) GetAvatarThumbnail 

func (c *Client) GetAvatarThumbnail(ctx context.Context, avatarID string) ([]byte, error)

GetAvatarThumbnail downloads the thumbnail avatar image and returns the raw bytes

func (*Client) GetDraft 

func (c *Client) GetDraft(ctx context.Context, draftID string) (*Draft, error)

GetDraft retrieves a single draft by draft ID from the Sleeper API. See: https://docs.sleeper.com/#get-draft

func (*Client) GetDraftPicks 

func (c *Client) GetDraftPicks(ctx context.Context, draftID string) ([]*DraftPick, error)

GetDraftPicks retrieves all picks for a given draft from the Sleeper API. See: https://docs.sleeper.com/#get-draft-picks

func (*Client) GetDraftTradedPicks 

func (c *Client) GetDraftTradedPicks(ctx context.Context, draftID string) ([]*TradedDraftPick, error)

GetDraftTradedPicks retrieves all traded picks for a given draft from the Sleeper API. See: https://docs.sleeper.com/#get-draft-traded-picks

func (*Client) GetLeague 

func (c *Client) GetLeague(ctx context.Context, leagueID string) (*League, error)

GetLeague retrieves a League by league ID.

func (*Client) GetLeagueDrafts 

func (c *Client) GetLeagueDrafts(ctx context.Context, leagueID string) ([]*Draft, error)

GetLeagueDrafts retrieves all drafts for a given league from the Sleeper API. See: https://docs.sleeper.com/#get-league-drafts

func (*Client) GetLeagueLosersBracket 

func (c *Client) GetLeagueLosersBracket(ctx context.Context, leagueID string) ([]*PlayoffMatchup, error)

GetLeagueLosersBracket retrieves the losers bracket for a given league ID.

func (*Client) GetLeagueMatchups 

func (c *Client) GetLeagueMatchups(ctx context.Context, leagueID string, week int) ([]*Matchup, error)

GetLeagueMatchups retrieves all matchups for a given league ID and week.

func (*Client) GetLeagueRosters 

func (c *Client) GetLeagueRosters(ctx context.Context, leagueID string) ([]*Roster, error)

GetLeagueRosters retrieves all rosters for a given league ID.

func (*Client) GetLeagueTradedPicks 

func (c *Client) GetLeagueTradedPicks(ctx context.Context, leagueID string) ([]*TradedDraftPick, error)

GetLeagueTradedPicks retrieves all traded draft picks for a given league ID.

func (*Client) GetLeagueUsers 

func (c *Client) GetLeagueUsers(ctx context.Context, leagueID string) ([]*User, error)

GetLeagueUsers retrieves all users for a given league ID.

func (*Client) GetLeagueWinnersBracket 

func (c *Client) GetLeagueWinnersBracket(ctx context.Context, leagueID string) ([]*PlayoffMatchup, error)

GetLeagueWinnersBracket retrieves the winners bracket for a given league ID.

func (*Client) GetPlayerValues added in v0.3.0 

func (c *Client) GetPlayerValues(ctx context.Context, sport Sport, season string, format ScoringFormat, options PlayerValuesOptions) (map[string]float64, error)

GetPlayerValues retrieves player values from a hidden Sleeper endpoint. This endpoint is not listed in the official Sleeper API documentation and may change or disappear without notice.

The response maps player IDs to a value score where a higher value indicates a more valuable player. This is a value model, not draft position: values correlate with ADP but do not match the ADP shown in the Sleeper draft lobby. For actual average draft positions, use the adp_* stats from ListProjections.

The format is the only scoring dimension the endpoint supports; there are no finer-grained variants (TEP, superflex, best ball) — unknown formats and query parameters are silently ignored and return an empty result. NFL supports all scoring formats; other sports may only return data for ScoringFormatStandard and the current season.

func (*Client) GetSportState 

func (c *Client) GetSportState(ctx context.Context, sport Sport) (*SportState, error)

func (*Client) GetTransactions 

func (c *Client) GetTransactions(ctx context.Context, leagueID string, week int) ([]*Transaction, error)

GetTransactions retrieves all transactions for a given league ID and week.

func (*Client) GetUser 

func (c *Client) GetUser(ctx context.Context, identity string) (*User, error)

GetUser retrieves a User by identity (username or user_id of the user).

func (*Client) GetUserDrafts 

func (c *Client) GetUserDrafts(ctx context.Context, userID string, sport Sport, season string) ([]*Draft, error)

GetUserDrafts retrieves all drafts for a given user, sport, and season from the Sleeper API. See: https://docs.sleeper.com/#get-user-drafts

func (*Client) GetUserLeagues 

func (c *Client) GetUserLeagues(ctx context.Context, userID string, sport Sport, season string) ([]*League, error)

GetUserLeagues retrieves all leagues for a user is a member of for a given user id (must be the user_id, cannot be the username), sport, and season (season should be the year, e.g. 2025).

func (*Client) ListNFLPlayers 

func (c *Client) ListNFLPlayers(ctx context.Context) (map[string]Player, error)

ListNFLPlayers retrieves the full map of NFL players from the Sleeper API. This endpoint returns a large payload (~5MB) and should only be called once per day to update your local cache of player IDs and metadata. The response maps player IDs (e.g., "1042", "2403", "CAR") to player information, which is necessary for resolving player references in rosters and draft picks. Do not call this endpoint on every lookup; instead, store the results on your own server and refresh them daily at most.

func (*Client) ListProjections added in v0.3.0 

func (c *Client) ListProjections(ctx context.Context, sport Sport, season string, options ProjectionOptions) ([]PlayerProjection, error)

ListProjections retrieves player projections from a hidden Sleeper endpoint. This endpoint is not listed in the official Sleeper API documentation and may change or disappear without notice.

Each entry's Stats holds projected season stats alongside the player's average draft position in every league format. To build a ranked ADP list, keep entries where Stats.ADP(adpType) < ADPUndrafted and sort ascending.

func (*Client) ListTrendingPlayers 

func (c *Client) ListTrendingPlayers(ctx context.Context, sport Sport, trendingType TrendingType, options TrendingPlayerOptions) ([]*Player, error)

ListTrendingPlayers retrieves a list of trending players based on adds or drops in the past 24 hours from the Sleeper API. Please give attribution to Sleeper if you use their trending data. This endpoint can be used to get trending players for a given sport and type ("add" or "drop") with optional lookback_hours and limit parameters.

If you wish to embed the official trending list in your app or website, use the following HTML snippet provided by Sleeper:

<iframe src="https://sleeper.app/embed/players/nfl/trending/add?lookback_hours=24&limit=25" width="350" height="500" allowtransparency="true" frameborder="0"></iframe>

type Config 

type Config struct {
	APIVersion     apiVersion
	Timeout        time.Duration
	RateLimitRPS   float64 // Requests per second (default: 15)
	RateLimitBurst int     // Burst capacity (default: 30)
}

Config holds configuration options for creating a Client.

type Draft 

type Draft struct {
	Created         int64          `json:"created"`
	Creators        []string       `json:"creators"`
	DraftID         string         `json:"draft_id"`
	DraftOrder      map[string]int `json:"draft_order"`
	LastMessageID   string         `json:"last_message_id"`
	LastMessageTime int64          `json:"last_message_time"`
	LastPicked      *int64         `json:"last_picked"`
	LeagueID        string         `json:"league_id"`
	Metadata        *DraftMetadata `json:"metadata"`
	Season          string         `json:"season"`
	SeasonType      string         `json:"season_type"`
	Settings        *DraftSettings `json:"settings"`
	SlotToRosterID  map[string]int `json:"slot_to_roster_id"`
	Sport           string         `json:"sport"`
	StartTime       *int64         `json:"start_time"`
	Status          string         `json:"status"`
	Type            string         `json:"type"`
}

Draft represents a draft object in the Sleeper API.

type DraftMetadata 

type DraftMetadata struct {
	Description      string `json:"description"`
	Name             string `json:"name"`
	ScoringType      string `json:"scoring_type"`
	ShowTeamNames    string `json:"show_team_names,omitempty"`
	LeagueType       string `json:"league_type,omitempty"`
	ElapsedPickTimer string `json:"elapsed_pick_timer,omitempty"`
	IsAutopaused     string `json:"is_autopaused,omitempty"`
}

DraftMetadata contains metadata for a draft in the Sleeper API.

type DraftPick 

type DraftPick struct {
	DraftID   string              `json:"draft_id"`
	DraftSlot int                 `json:"draft_slot"`
	IsKeeper  interface{}         `json:"is_keeper"`
	Metadata  *DraftPickMetadata  `json:"metadata"`
	PickNo    int                 `json:"pick_no"`
	PickedBy  string              `json:"picked_by"`
	PlayerID  string              `json:"player_id"`
	Reactions map[string][]string `json:"reactions"`
	RosterID  int                 `json:"roster_id"`
	Round     int                 `json:"round"`
}

DraftPick represents a single pick in a draft in the Sleeper API.

type DraftPickMetadata 

type DraftPickMetadata struct {
	FirstName     string `json:"first_name"`
	InjuryStatus  string `json:"injury_status"`
	LastName      string `json:"last_name"`
	NewsUpdated   string `json:"news_updated"`
	Number        string `json:"number"`
	PlayerID      string `json:"player_id"`
	Position      string `json:"position"`
	Sport         string `json:"sport"`
	Status        string `json:"status"`
	Team          string `json:"team"`
	TeamAbbr      string `json:"team_abbr"`
	TeamChangedAt string `json:"team_changed_at"`
	YearsExp      string `json:"years_exp"`
}

DraftPickMetadata contains metadata for a draft pick in the Sleeper API.

type DraftSettings 

type DraftSettings struct {
	AlphaSort             int `json:"alpha_sort"`
	AutopauseEnabled      int `json:"autopause_enabled"`
	AutopauseEndTime      int `json:"autopause_end_time"`
	AutopauseStartTime    int `json:"autopause_start_time"`
	Autostart             int `json:"autostart"`
	CPUAutopick           int `json:"cpu_autopick"`
	EnforcePositionLimits int `json:"enforce_position_limits"`
	NominationTimer       int `json:"nomination_timer"`
	PickTimer             int `json:"pick_timer"`
	PlayerType            int `json:"player_type"`
	ReversalRound         int `json:"reversal_round"`
	Rounds                int `json:"rounds"`
	Teams                 int `json:"teams"`

	// Roster slots - NFL
	SlotsBN        int `json:"slots_bn,omitempty"`
	SlotsFlex      int `json:"slots_flex,omitempty"`
	SlotsQB        int `json:"slots_qb,omitempty"`
	SlotsRB        int `json:"slots_rb,omitempty"`
	SlotsSuperFlex int `json:"slots_super_flex,omitempty"`
	SlotsTE        int `json:"slots_te,omitempty"`
	SlotsWR        int `json:"slots_wr,omitempty"`
	SlotsDEF       int `json:"slots_def,omitempty"`
	SlotsK         int `json:"slots_k,omitempty"`

	// Roster slots - NBA
	SlotsC    int `json:"slots_c,omitempty"`
	SlotsF    int `json:"slots_f,omitempty"`
	SlotsG    int `json:"slots_g,omitempty"`
	SlotsPF   int `json:"slots_pf,omitempty"`
	SlotsPG   int `json:"slots_pg,omitempty"`
	SlotsSF   int `json:"slots_sf,omitempty"`
	SlotsSG   int `json:"slots_sg,omitempty"`
	SlotsUtil int `json:"slots_util,omitempty"`
}

DraftSettings contains settings for a draft in the Sleeper API.

type FlexibleString 

type FlexibleString string

FlexibleString can unmarshal from either a string or int

func (FlexibleString) Int 

func (f FlexibleString) Int() (int, error)

Int converts to int, returns error if conversion fails

func (FlexibleString) String 

func (f FlexibleString) String() string

String returns the string value

func (*FlexibleString) UnmarshalJSON 

func (f *FlexibleString) UnmarshalJSON(data []byte) error

type League 

type League struct {
	Avatar                  string           `json:"avatar,omitempty"`
	Sport                   string           `json:"sport,omitempty"`
	LastMessageID           string           `json:"last_message_id,omitempty"`
	LastMessageTime         int64            `json:"last_message_time,omitempty"`
	Shard                   int              `json:"shard,omitempty"`
	LastTransactionID       int64            `json:"last_transaction_id,omitempty"`
	LastPinnedMessageID     string           `json:"last_pinned_message_id,omitempty"`
	PreviousLeagueID        string           `json:"previous_league_id,omitempty"`
	LoserBracketOverridesID int64            `json:"loser_bracket_overrides_id,omitempty"`
	RosterPositions         []string         `json:"roster_positions,omitempty"`
	LastAuthorIsBot         bool             `json:"last_author_is_bot,omitempty"`
	BracketID               int64            `json:"bracket_id,omitempty"`
	CompanyID               string           `json:"company_id,omitempty"`
	Status                  string           `json:"status,omitempty"`
	LoserBracketID          int64            `json:"loser_bracket_id,omitempty"`
	ScoringSettings         *ScoringSettings `json:"scoring_settings,omitempty"`
	DisplayOrder            int              `json:"display_order,omitempty"`
	BracketOverridesID      string           `json:"bracket_overrides_id,omitempty"`
	LastReadID              string           `json:"last_read_id,omitempty"`
	Name                    string           `json:"name,omitempty"`
	Season                  string           `json:"season,omitempty"`
	LastAuthorAvatar        string           `json:"last_author_avatar,omitempty"`
	LeagueID                string           `json:"league_id,omitempty"`
	DraftID                 string           `json:"draft_id,omitempty"`
	GroupID                 string           `json:"group_id,omitempty"`
	Metadata                *LeagueMetadata  `json:"metadata,omitempty"`
	LastMessageAttachment   string           `json:"last_message_attachment,omitempty"`
	LastAuthorDisplayName   string           `json:"last_author_display_name,omitempty"`
	LastAuthorID            string           `json:"last_author_id,omitempty"`
	TotalRosters            int              `json:"total_rosters,omitempty"`
	Settings                *Settings        `json:"settings,omitempty"`
	SeasonType              string           `json:"season_type,omitempty"`
	LastMessageTextMap      string           `json:"last_message_text_map,omitempty"`
}

League represents a Sleeper fantasy league.

type LeagueMetadata 

type LeagueMetadata struct {
	AutoContinue               string `json:"auto_continue,omitempty"`
	KeeperDeadline             string `json:"keeper_deadline,omitempty"`
	LatestLeagueWinnerRosterID string `json:"latest_league_winner_roster_id,omitempty"`
}

LeagueMetadata contains additional information about a league.

type Matchup 

type Matchup struct {
	Points         float64            `json:"points,omitempty"`
	Players        []string           `json:"players,omitempty"`
	RosterID       int                `json:"roster_id,omitempty"`
	CustomPoints   *float64           `json:"custom_points,omitempty"`
	MatchupID      int                `json:"matchup_id,omitempty"`
	Starters       []string           `json:"starters,omitempty"`
	StartersPoints []float64          `json:"starters_points,omitempty"`
	PlayersPoints  map[string]float64 `json:"players_points,omitempty"`
}

Matchup represents a weekly matchup in a league.

type Player 

type Player struct {
	PlayerID              string          `json:"player_id"`
	FirstName             string          `json:"first_name"`
	LastName              string          `json:"last_name"`
	FullName              string          `json:"full_name"`
	Status                string          `json:"status"`
	Sport                 string          `json:"sport"`
	Position              string          `json:"position"`
	Team                  *string         `json:"team"`
	TeamAbbr              *string         `json:"team_abbr"`
	Number                *int            `json:"number"`
	Age                   *int            `json:"age"`
	Height                string          `json:"height"`
	Weight                string          `json:"weight"`
	College               string          `json:"college"`
	HighSchool            *string         `json:"high_school"`
	BirthDate             *string         `json:"birth_date"`
	BirthCity             *string         `json:"birth_city"`
	BirthState            *string         `json:"birth_state"`
	BirthCountry          *string         `json:"birth_country"`
	YearsExp              int             `json:"years_exp"`
	Active                bool            `json:"active"`
	SearchRank            int             `json:"search_rank"`
	SearchFirstName       string          `json:"search_first_name"`
	SearchLastName        string          `json:"search_last_name"`
	SearchFullName        string          `json:"search_full_name"`
	FantasyPositions      []string        `json:"fantasy_positions"`
	DepthChartPosition    *string         `json:"depth_chart_position"`
	DepthChartOrder       *int            `json:"depth_chart_order"`
	InjuryStatus          *string         `json:"injury_status"`
	InjuryBodyPart        *string         `json:"injury_body_part"`
	InjuryNotes           *string         `json:"injury_notes"`
	InjuryStartDate       *string         `json:"injury_start_date"`
	PracticeParticipation *string         `json:"practice_participation"`
	PracticeDescription   *string         `json:"practice_description"`
	NewsUpdated           *int64          `json:"news_updated"`
	TeamChangedAt         *string         `json:"team_changed_at"`
	Hashtag               string          `json:"hashtag"`
	Metadata              *PlayerMetadata `json:"metadata"`

	// Third-party IDs
	ESPNID        *int    `json:"espn_id"`
	YahooID       *int    `json:"yahoo_id"`
	RotowireID    *int    `json:"rotowire_id"`
	RotoworldID   *int    `json:"rotoworld_id"`
	GSIID         *string `json:"gsis_id"`
	SportradarID  string  `json:"sportradar_id"`
	StatsID       *int    `json:"stats_id"`
	FantasyDataID *int    `json:"fantasy_data_id"`
	SwishID       *int    `json:"swish_id"`
	OptaID        *string `json:"opta_id"`
	PandascoreID  *string `json:"pandascore_id"`
	OddsjamID     *string `json:"oddsjam_id"`
	KalshiID      *string `json:"kalshi_id"`
}

Player represents a player in the Sleeper system

type PlayerMetadata 

type PlayerMetadata struct {
	ChannelID  string `json:"channel_id"`
	RookieYear string `json:"rookie_year"`
}

type PlayerProjection added in v0.3.0 

type PlayerProjection struct {
	PlayerID     string          `json:"player_id,omitempty"`
	Sport        string          `json:"sport,omitempty"`
	Season       string          `json:"season,omitempty"`
	SeasonType   string          `json:"season_type,omitempty"`
	Category     string          `json:"category,omitempty"`
	Company      string          `json:"company,omitempty"`
	GameID       string          `json:"game_id,omitempty"`
	Team         string          `json:"team,omitempty"`
	Stats        ProjectionStats `json:"stats,omitempty"`
	Player       *Player         `json:"player,omitempty"`
	UpdatedAt    int64           `json:"updated_at,omitempty"`
	LastModified int64           `json:"last_modified,omitempty"`

	// Null for season-long projections; populated in per-game entries.
	Week     int    `json:"week,omitempty"`
	Opponent string `json:"opponent,omitempty"`
	Status   string `json:"status,omitempty"`
	Date     string `json:"date,omitempty"`
}

PlayerProjection is one entry from the projections endpoint: a player's projected season stats plus their average draft position in every format.

type PlayerValuesOptions added in v0.3.0 

type PlayerValuesOptions struct {
	IncludeIDP bool // Include defensive (IDP) players in the response
	IsDynasty  bool // Sent as is_dynasty to match the Sleeper app, but the server ignores it; dynasty values are selected via the dynasty_* formats
}

type PlayoffMatchup 

type PlayoffMatchup struct {
	Round     int                 `json:"r,omitempty"`       // The round for this matchup, 1st, 2nd, 3rd round, etc.
	MatchID   int                 `json:"m,omitempty"`       // The match id of the matchup, unique for all matchups within a bracket.
	Team1     *int                `json:"t1,omitempty"`      // The roster_id of a team in this matchup OR {w: 1} which means the winner of match id 1.
	Team2     *int                `json:"t2,omitempty"`      // The roster_id of the other team in this matchup OR {l: 1} which means the loser of match id 1.
	Winner    *int                `json:"w,omitempty"`       // The roster_id of the winning team, if the match has been played.
	Loser     *int                `json:"l,omitempty"`       // The roster_id of the losing team, if the match has been played.
	Team1From *PlayoffMatchupFrom `json:"t1_from,omitempty"` // Where t1 comes from, either winner or loser of the match id, necessary to show bracket progression.
	Team2From *PlayoffMatchupFrom `json:"t2_from,omitempty"` // Where t2 comes from, either winner or loser of the match id, necessary to show bracket progression.
	Placement *int                `json:"p,omitempty"`       // Position/placement (e.g., 1st place, 3rd place, 5th place).
}

PlayoffMatchup represents a playoff bracket matchup.

type PlayoffMatchupFrom 

type PlayoffMatchupFrom struct {
	WinnerOfMatch *int `json:"w,omitempty"` // Winner of match id
	LoserOfMatch  *int `json:"l,omitempty"` // Loser of match id
}

PlayoffMatchupFrom describes where a playoff team comes from in the bracket.

type ProjectionOptions added in v0.3.0 

type ProjectionOptions struct {
	Positions  []string // Filters on fantasy_positions (case-sensitive): "QB", "RB", "WR", "TE", "K", "DEF", or IDP "DL", "LB", "DB". Empty returns every position, including non-fantasy ones.
	SeasonType string   // "regular" (default), "pre", or "post"
	OrderBy    string   // any stat key, e.g. "adp_dynasty_2qb" or "pts_ppr"; controls server-side ordering only
}

type ProjectionStats added in v0.3.0 

type ProjectionStats struct {
	// Average draft position per league format (999 = not being drafted).
	// ADPRookie exists in responses but has never been populated.
	ADPStandard        float64 `json:"adp_std,omitempty"`
	ADPHalfPPR         float64 `json:"adp_half_ppr,omitempty"`
	ADPPPR             float64 `json:"adp_ppr,omitempty"`
	ADP2QB             float64 `json:"adp_2qb,omitempty"`
	ADPDynasty         float64 `json:"adp_dynasty,omitempty"`
	ADPDynastyStandard float64 `json:"adp_dynasty_std,omitempty"`
	ADPDynastyHalfPPR  float64 `json:"adp_dynasty_half_ppr,omitempty"`
	ADPDynastyPPR      float64 `json:"adp_dynasty_ppr,omitempty"`
	ADPDynasty2QB      float64 `json:"adp_dynasty_2qb,omitempty"`
	ADPIDP             float64 `json:"adp_idp,omitempty"`
	ADPIDP1QB          float64 `json:"adp_idp_1qb,omitempty"`
	ADPRookie          float64 `json:"adp_rookie,omitempty"`

	// Projected fantasy points per scoring format
	GamesPlayed float64 `json:"gp,omitempty"`
	PtsStandard float64 `json:"pts_std,omitempty"`
	PtsHalfPPR  float64 `json:"pts_half_ppr,omitempty"`
	PtsPPR      float64 `json:"pts_ppr,omitempty"`

	// Passing
	PassAtt        float64 `json:"pass_att,omitempty"`
	PassCmp        float64 `json:"pass_cmp,omitempty"`
	PassCmpPct     float64 `json:"cmp_pct,omitempty"`
	PassYd         float64 `json:"pass_yd,omitempty"`
	PassTD         float64 `json:"pass_td,omitempty"`
	PassInt        float64 `json:"pass_int,omitempty"`
	PassIntTD      float64 `json:"pass_int_td,omitempty"`
	PassFirstDowns float64 `json:"pass_fd,omitempty"`
	Pass2Pt        float64 `json:"pass_2pt,omitempty"`

	// Rushing
	RushAtt        float64 `json:"rush_att,omitempty"`
	RushYd         float64 `json:"rush_yd,omitempty"`
	RushTD         float64 `json:"rush_td,omitempty"`
	RushFirstDowns float64 `json:"rush_fd,omitempty"`
	Rush2Pt        float64 `json:"rush_2pt,omitempty"`

	// Receiving (rec_N_M buckets are receptions by yardage gained)
	Rec           float64 `json:"rec,omitempty"`
	RecYd         float64 `json:"rec_yd,omitempty"`
	RecTD         float64 `json:"rec_td,omitempty"`
	RecFirstDowns float64 `json:"rec_fd,omitempty"`
	Rec2Pt        float64 `json:"rec_2pt,omitempty"`
	Rec0To4       float64 `json:"rec_0_4,omitempty"`
	Rec5To9       float64 `json:"rec_5_9,omitempty"`
	Rec10To19     float64 `json:"rec_10_19,omitempty"`
	Rec20To29     float64 `json:"rec_20_29,omitempty"`
	Rec30To39     float64 `json:"rec_30_39,omitempty"`
	Rec40Plus     float64 `json:"rec_40p,omitempty"`

	// Reception bonuses by position
	BonusRecRB float64 `json:"bonus_rec_rb,omitempty"`
	BonusRecTE float64 `json:"bonus_rec_te,omitempty"`
	BonusRecWR float64 `json:"bonus_rec_wr,omitempty"`

	// Fumbles
	FumLost float64 `json:"fum_lost,omitempty"`

	// Kicking
	XPM          float64 `json:"xpm,omitempty"`
	XPMiss       float64 `json:"xpmiss,omitempty"`
	FGM40To49    float64 `json:"fgm_40_49,omitempty"`
	FGM50Plus    float64 `json:"fgm_50p,omitempty"`
	FGMYds       float64 `json:"fgm_yds,omitempty"`
	FGMiss40To49 float64 `json:"fgmiss_40_49,omitempty"`
	FGMiss50Plus float64 `json:"fgmiss_50p,omitempty"`

	// Team defense / special teams (DEF)
	DefSack        float64 `json:"sack,omitempty"`
	DefInt         float64 `json:"int,omitempty"`
	DefFumRec      float64 `json:"fum_rec,omitempty"`
	DefFumTD       float64 `json:"def_fum_td,omitempty"`
	DefSafety      float64 `json:"safe,omitempty"`
	DefBlockKick   float64 `json:"blk_kick,omitempty"`
	DefKRTD        float64 `json:"def_kr_td,omitempty"`
	DefPRTD        float64 `json:"pr_td,omitempty"`
	DefPtsAllow0   float64 `json:"pts_allow_0,omitempty"`
	DefYdsAllow100 float64 `json:"yds_allow_0_100,omitempty"`

	// Individual defensive players (IDP)
	IDPTackle       float64 `json:"idp_tkl,omitempty"`
	IDPTackleSolo   float64 `json:"idp_tkl_solo,omitempty"`
	IDPTackleAssist float64 `json:"idp_tkl_ast,omitempty"`
	IDPSack         float64 `json:"idp_sack,omitempty"`
	IDPInt          float64 `json:"idp_int,omitempty"`
	IDPForcedFum    float64 `json:"idp_ff,omitempty"`
	IDPFumRec       float64 `json:"idp_fum_rec,omitempty"`
	IDPSafety       float64 `json:"idp_safe,omitempty"`
	IDPBlockKick    float64 `json:"idp_blk_kick,omitempty"`
}

ProjectionStats holds a player's projected season stats and per-format ADP. Only the fields relevant to the player's position are populated; absent stats decode to zero. Field set observed across the 2022-2026 seasons.

func (ProjectionStats) ADP added in v0.3.0 

func (s ProjectionStats) ADP(adpType ADPType) float64

ADP returns the player's average draft position for the given format (ADPUndrafted if not being drafted, 0 if the stat was absent).

type Roster 

type Roster struct {
	CoOwners []string        `json:"co_owners,omitempty"`
	Keepers  []string        `json:"keepers,omitempty"`
	LeagueID string          `json:"league_id,omitempty"`
	Metadata *RosterMetadata `json:"metadata,omitempty"`
	OwnerID  string          `json:"owner_id,omitempty"`
	Players  []string        `json:"players,omitempty"`
	Reserve  []string        `json:"reserve,omitempty"`
	RosterID int             `json:"roster_id,omitempty"`
	Settings *RosterSettings `json:"settings,omitempty"`
	Starters []string        `json:"starters,omitempty"`
	Taxi     []string        `json:"taxi,omitempty"`
}

Roster represents a fantasy team roster in a Sleeper league.

type RosterMetadata 

type RosterMetadata struct {
	AllowPnNews                   string            `json:"allow_pn_news,omitempty"`
	AllowPnScoring                string            `json:"allow_pn_scoring,omitempty"`
	AllowPnInactiveStarters       string            `json:"allow_pn_inactive_starters,omitempty"`
	AllowPnPlayerInjuryStatus     string            `json:"allow_pn_player_injury_status,omitempty"`
	RestrictPnScoringStartersOnly string            `json:"restrict_pn_scoring_starters_only,omitempty"`
	Record                        string            `json:"record,omitempty"`
	Streak                        string            `json:"streak,omitempty"`
	PlayerNicknames               map[string]string `json:"-"`
}

RosterMetadata contains metadata and player nicknames for a roster.

func (*RosterMetadata) UnmarshalJSON 

func (rm *RosterMetadata) UnmarshalJSON(data []byte) error

UnmarshalJSON handles both regular fields and dynamic playerNickname fields

type RosterSettings 

type RosterSettings struct {
	Fpts               int `json:"fpts,omitempty"`
	FptsAgainst        int `json:"fpts_against,omitempty"`
	FptsAgainstDecimal int `json:"fpts_against_decimal,omitempty"`
	FptsDecimal        int `json:"fpts_decimal,omitempty"`
	Losses             int `json:"losses,omitempty"`
	Ppts               int `json:"ppts,omitempty"`
	PptsDecimal        int `json:"ppts_decimal,omitempty"`
	Ties               int `json:"ties,omitempty"`
	TotalMoves         int `json:"total_moves,omitempty"`
	WaiverBudgetUsed   int `json:"waiver_budget_used,omitempty"`
	WaiverPosition     int `json:"waiver_position,omitempty"`
	Wins               int `json:"wins,omitempty"`
}

RosterSettings contains scoring and record settings for a roster.

type ScoringFormat added in v0.3.0 

type ScoringFormat string

ScoringFormat selects the league format used to compute player values. 

const (
	ScoringFormatStandard        ScoringFormat = "std"
	ScoringFormatHalfPPR         ScoringFormat = "half_ppr"
	ScoringFormatPPR             ScoringFormat = "ppr"
	ScoringFormat2QB             ScoringFormat = "2qb"
	ScoringFormatDynastyStandard ScoringFormat = "dynasty_std"
	ScoringFormatDynastyHalfPPR  ScoringFormat = "dynasty_half_ppr"
	ScoringFormatDynastyPPR      ScoringFormat = "dynasty_ppr"
	ScoringFormatDynasty2QB      ScoringFormat = "dynasty_2qb"
	ScoringFormatIDP             ScoringFormat = "idp"
)

type ScoringSettings 

type ScoringSettings struct {
	Sack         float64 `json:"sack,omitempty"`
	FGM4049      float64 `json:"fgm_40_49,omitempty"`
	FGMYds       float64 `json:"fgm_yds,omitempty"`
	PassInt      float64 `json:"pass_int,omitempty"`
	PtsAllow0    float64 `json:"pts_allow_0,omitempty"`
	Pass2pt      float64 `json:"pass_2pt,omitempty"`
	StTd         float64 `json:"st_td,omitempty"`
	FGMYdsOver30 float64 `json:"fgm_yds_over_30,omitempty"`
	RecTd        float64 `json:"rec_td,omitempty"`
	FGM3039      float64 `json:"fgm_30_39,omitempty"`
	FGM5059      float64 `json:"fgm_50_59,omitempty"`
	XPMiss       float64 `json:"xpmiss,omitempty"`
	RushTd       float64 `json:"rush_td,omitempty"`
	DefPrTd      float64 `json:"def_pr_td,omitempty"`
	Def4AndStop  float64 `json:"def_4_and_stop,omitempty"`
	Rec2pt       float64 `json:"rec_2pt,omitempty"`
	PassIntTd    float64 `json:"pass_int_td,omitempty"`
	StFumRec     float64 `json:"st_fum_rec,omitempty"`
	FGMiss       float64 `json:"fgmiss,omitempty"`
	FF           float64 `json:"ff,omitempty"`
	Rec          float64 `json:"rec,omitempty"`
	PtsAllow1420 float64 `json:"pts_allow_14_20,omitempty"`
	FGM019       float64 `json:"fgm_0_19,omitempty"`
	DefKrTd      float64 `json:"def_kr_td,omitempty"`
	Int          float64 `json:"int,omitempty"`
	DefStFumRec  float64 `json:"def_st_fum_rec,omitempty"`
	FumLost      float64 `json:"fum_lost,omitempty"`
	PtsAllow16   float64 `json:"pts_allow_1_6,omitempty"`
	FGM2029      float64 `json:"fgm_20_29,omitempty"`
	PtsAllow2127 float64 `json:"pts_allow_21_27,omitempty"`
	XPM          float64 `json:"xpm,omitempty"`
	Rush2pt      float64 `json:"rush_2pt,omitempty"`
	FumRec       float64 `json:"fum_rec,omitempty"`
	DefStTd      float64 `json:"def_st_td,omitempty"`
	FGM50p       float64 `json:"fgm_50p,omitempty"`
	DefTd        float64 `json:"def_td,omitempty"`
	Safe         float64 `json:"safe,omitempty"`
	PassYd       float64 `json:"pass_yd,omitempty"`
	BlkKick      float64 `json:"blk_kick,omitempty"`
	PassTd       float64 `json:"pass_td,omitempty"`
	RushYd       float64 `json:"rush_yd,omitempty"`
	Fum          float64 `json:"fum,omitempty"`
	PtsAllow2834 float64 `json:"pts_allow_28_34,omitempty"`
	PtsAllow35p  float64 `json:"pts_allow_35p,omitempty"`
	FumRecTd     float64 `json:"fum_rec_td,omitempty"`
	RecYd        float64 `json:"rec_yd,omitempty"`
	DefStFF      float64 `json:"def_st_ff,omitempty"`
	PtsAllow713  float64 `json:"pts_allow_7_13,omitempty"`
	StFF         float64 `json:"st_ff,omitempty"`
}

ScoringSettings holds the scoring rules for a league.

type Settings 

type Settings struct {
	BestBall                 int `json:"best_ball,omitempty"`
	LastReport               int `json:"last_report,omitempty"`
	WaiverBudget             int `json:"waiver_budget,omitempty"`
	DisableAdds              int `json:"disable_adds,omitempty"`
	CapacityOverride         int `json:"capacity_override,omitempty"`
	TaxiDeadline             int `json:"taxi_deadline,omitempty"`
	DraftRounds              int `json:"draft_rounds,omitempty"`
	ReserveAllowNA           int `json:"reserve_allow_na,omitempty"`
	StartWeek                int `json:"start_week,omitempty"`
	PlayoffSeedType          int `json:"playoff_seed_type,omitempty"`
	PlayoffTeams             int `json:"playoff_teams,omitempty"`
	VetoVotesNeeded          int `json:"veto_votes_needed,omitempty"`
	Squads                   int `json:"squads,omitempty"`
	NumTeams                 int `json:"num_teams,omitempty"`
	DailyWaiversHour         int `json:"daily_waivers_hour,omitempty"`
	PlayoffType              int `json:"playoff_type,omitempty"`
	TaxiSlots                int `json:"taxi_slots,omitempty"`
	SubStartTimeEligibility  int `json:"sub_start_time_eligibility,omitempty"`
	LastScoredLeg            int `json:"last_scored_leg,omitempty"`
	DailyWaiversDays         int `json:"daily_waivers_days,omitempty"`
	SubLockIfStarterActive   int `json:"sub_lock_if_starter_active,omitempty"`
	PlayoffWeekStart         int `json:"playoff_week_start,omitempty"`
	WaiverClearDays          int `json:"waiver_clear_days,omitempty"`
	ReserveAllowDoubtful     int `json:"reserve_allow_doubtful,omitempty"`
	CommissionerDirectInvite int `json:"commissioner_direct_invite,omitempty"`
	VetoAutoPoll             int `json:"veto_auto_poll,omitempty"`
	ReserveAllowDNR          int `json:"reserve_allow_dnr,omitempty"`
	TaxiAllowVets            int `json:"taxi_allow_vets,omitempty"`
	WaiverDayOfWeek          int `json:"waiver_day_of_week,omitempty"`
	PlayoffRoundType         int `json:"playoff_round_type,omitempty"`
	ReserveAllowOut          int `json:"reserve_allow_out,omitempty"`
	ReserveAllowSus          int `json:"reserve_allow_sus,omitempty"`
	VetoShowVotes            int `json:"veto_show_votes,omitempty"`
	TradeDeadline            int `json:"trade_deadline,omitempty"`
	TaxiYears                int `json:"taxi_years,omitempty"`
	DailyWaivers             int `json:"daily_waivers,omitempty"`
	FaabSuggestions          int `json:"faab_suggestions,omitempty"`
	DisableTrades            int `json:"disable_trades,omitempty"`
	PickTrading              int `json:"pick_trading,omitempty"`
	Type                     int `json:"type,omitempty"`
	MaxKeepers               int `json:"max_keepers,omitempty"`
	WaiverType               int `json:"waiver_type,omitempty"`
	MaxSubs                  int `json:"max_subs,omitempty"`
	LeagueAverageMatch       int `json:"league_average_match,omitempty"`
	TradeReviewDays          int `json:"trade_review_days,omitempty"`
	BenchLock                int `json:"bench_lock,omitempty"`
	OffseasonAdds            int `json:"offseason_adds,omitempty"`
	Leg                      int `json:"leg,omitempty"`
	ReserveSlots             int `json:"reserve_slots,omitempty"`
	ReserveAllowCov          int `json:"reserve_allow_cov,omitempty"`
	DailyWaiversLastRan      int `json:"daily_waivers_last_ran,omitempty"`
}

Settings contains configuration options for a league.

type Sport added in v0.2.0 

type Sport string
const (
	SportNFL Sport = "nfl"
	SportMLB Sport = "mlb"
	SportNBA Sport = "nba"
	SportNHL Sport = "nhl"
)

type SportState 

type SportState struct {
	Week               int            `json:"week,omitempty"`              // week
	SeasonType         string         `json:"season_type,omitempty"`       // pre, post, regular
	SeasonStartDate    string         `json:"season_start_date,omitempty"` // regular season start
	Season             string         `json:"season,omitempty"`            // current season
	PreviousSeason     FlexibleString `json:"previous_season,omitempty"`
	Leg                int            `json:"leg,omitempty"`                  // week of regular season
	LeagueSeason       string         `json:"league_season,omitempty"`        // active season for leagues
	LeagueCreateSeason string         `json:"league_create_season,omitempty"` // flips in December
	DisplayWeek        int            `json:"display_week,omitempty"`         // Which week to display in UI, can be different than week
}

type TradedDraftPick 

type TradedDraftPick struct {
	Season          string `json:"season,omitempty"`            // the season this draft pick belongs to
	Round           int    `json:"round,omitempty"`             // which round this draft pick is
	RosterID        int    `json:"roster_id,omitempty"`         // original owner's roster_id
	PreviousOwnerID int    `json:"previous_owner_id,omitempty"` // previous owner's roster id (in this trade)
	OwnerID         int    `json:"owner_id,omitempty"`          // the new owner of this pick after the trade
}

TradedDraftPick represents a draft pick that was traded

type Transaction 

type Transaction struct {
	Type          transactionType      `json:"type,omitempty"`
	TransactionID string               `json:"transaction_id,omitempty"`
	StatusUpdated int64                `json:"status_updated,omitempty"`
	Status        string               `json:"status,omitempty"`
	Settings      *TransactionSettings `json:"settings,omitempty"`   // trades do not use this field
	RosterIDs     []int                `json:"roster_ids,omitempty"` // roster_ids involved in this transaction
	Metadata      *TransactionMetadata `json:"metadata,omitempty"`
	Leg           int                  `json:"leg,omitempty"` // in football, this is the week
	Drops         map[string]int       `json:"drops,omitempty"`
	DraftPicks    []*TradedDraftPick   `json:"draft_picks,omitempty"` // picks that were traded
	Creator       string               `json:"creator,omitempty"`     // user id who initiated the transaction
	Created       int64                `json:"created,omitempty"`
	ConsenterIDs  []int                `json:"consenter_ids,omitempty"` // roster_ids of the people who agreed to this transaction
	Adds          map[string]int       `json:"adds,omitempty"`
	WaiverBudget  []*WaiverBudget      `json:"waiver_budget,omitempty"` // roster_id 2 sends 55 FAAB dollars to roster_id 3
}

Transaction represents a transaction in a league

type TransactionMetadata 

type TransactionMetadata struct {
	Notes string `json:"notes,omitempty"`
}

TransactionMetadata can contain notes about why a transaction didn't go through

type TransactionSettings 

type TransactionSettings struct {
	WaiverBid int `json:"waiver_bid,omitempty"`
}

TransactionSettings holds settings for waiver transactions

type TrendingPlayerOptions 

type TrendingPlayerOptions struct {
	LookbackHours int `json:"lookback_hours,omitempty"` // Number of hours to look back for trending players (default: 24)
	Limit         int `json:"limit,omitempty"`          // Maximum number of players to return (default: 10, max: 50)
}

type TrendingType added in v0.2.0 

type TrendingType string
const (
	TrendingTypeAdd  TrendingType = "add"
	TrendingTypeDrop TrendingType = "drop"
)

type User 

type User struct {
	Avatar      string `json:"avatar,omitempty"`
	DisplayName string `json:"display_name,omitempty"`
	IsBot       bool   `json:"is_bot"`
	UserID      string `json:"user_id"`
	Username    string `json:"username"`
}

User represents a Sleeper user/league member.

type WaiverBudget 

type WaiverBudget struct {
	Sender   int `json:"sender,omitempty"`
	Receiver int `json:"receiver,omitempty"`
	Amount   int `json:"amount,omitempty"`
}

WaiverBudget represents a waiver amount involved in a trade

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.