mlb

Documentation

Overview

Package mlb is the library behind the mlb command line: the HTTP client, request shaping, and the typed data models for the MLB Stats API (statsapi.mlb.com/api/v1).

The Client here is the spine every command shares. It sets a real User-Agent, paces requests so a busy session stays polite, and retries the transient failures (429 and 5xx) that any public API throws under load. Build your endpoint calls and JSON decoding on top of it.

Index

• Constants
• type Client
  • func NewClient() *Client
  • func (c *Client) Get(ctx context.Context, url string) ([]byte, error)
  • func (c *Client) GetGameByPk(ctx context.Context, gamePk string) (*Game, error)
  • func (c *Client) GetPlayerByID(ctx context.Context, id string) (*Player, error)
  • func (c *Client) GetPlayers(ctx context.Context, season string) ([]*Player, error)
  • func (c *Client) GetSchedule(ctx context.Context, date string) ([]*Game, error)
  • func (c *Client) GetStandings(ctx context.Context, season string) ([]*Standing, error)
  • func (c *Client) GetTeamByID(ctx context.Context, id string) (*Team, error)
  • func (c *Client) GetTeams(ctx context.Context) ([]*Team, error)
• type Config
  • func DefaultConfig() Config
• type Domain
  • func (Domain) Classify(input string) (uriType, id string, err error)
  • func (Domain) Info() kit.DomainInfo
  • func (Domain) Locate(uriType, id string) (string, error)
  • func (Domain) Register(app *kit.App)
• type Game
• type Player
• type Standing
• type Team

Constants

const BaseURL = "https://" + Host

BaseURL is the root every request is built from.

const DefaultUserAgent = "mlb-cli/dev (+https://github.com/tamnd/mlb-cli)"

DefaultUserAgent identifies the client to the MLB Stats API.

const Host = "statsapi.mlb.com"

Host is the Stats API hostname.

Types

type Client

type Client struct {
	HTTP      *http.Client
	UserAgent string
	// Rate is the minimum gap between requests. Zero means no pacing.
	Rate    time.Duration
	Retries int
	// contains filtered or unexported fields
}

Client talks to the MLB Stats API over HTTP.

func NewClient

func NewClient() *Client

NewClient returns a Client with sensible defaults: a 30s timeout, a 200ms minimum gap between requests, and five retries on transient errors.

func (*Client) Get

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

Get fetches url and returns the response body. It paces and retries according to the client's settings. The caller owns nothing extra; the body is read fully and closed here.

func (*Client) GetGameByPk

func (c *Client) GetGameByPk(ctx context.Context, gamePk string) (*Game, error)

GetGameByPk fetches a single game's metadata using the boxscore endpoint.

func (*Client) GetPlayerByID

func (c *Client) GetPlayerByID(ctx context.Context, id string) (*Player, error)

GetPlayerByID fetches a single player by their numeric ID.

func (*Client) GetPlayers

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

GetPlayers fetches all active players for a season year (e.g. "2024").

func (*Client) GetSchedule

func (c *Client) GetSchedule(ctx context.Context, date string) ([]*Game, error)

GetSchedule fetches games for the given date (YYYY-MM-DD).

func (*Client) GetStandings

func (c *Client) GetStandings(ctx context.Context, season string) ([]*Standing, error)

GetStandings fetches standings for both leagues for the given season year.

func (*Client) GetTeamByID

func (c *Client) GetTeamByID(ctx context.Context, id string) (*Team, error)

GetTeamByID fetches a single team by its numeric ID.

func (*Client) GetTeams

func (c *Client) GetTeams(ctx context.Context) ([]*Team, error)

GetTeams fetches all MLB teams.

type Config

type Config struct {
	UserAgent string
	Rate      time.Duration
	Retries   int
	Timeout   time.Duration
}

Config holds user-overridable settings for the client.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns production-ready defaults.

type Domain

type Domain struct{}

Domain is the mlb driver. It carries no state; the per-run client is built by the factory Register hands kit.

func (Domain) Classify

func (Domain) Classify(input string) (uriType, id string, err error)

Classify turns any accepted input into the canonical (type, id). Numeric string -> ("game", input) 3-letter uppercase -> ("team", input) Otherwise -> ("player", input)

func (Domain) Info

func (Domain) Info() kit.DomainInfo

Info describes the scheme, the hostnames a pasted link is matched against, and the identity reused for the binary's help and version.

func (Domain) Locate

func (Domain) Locate(uriType, id string) (string, error)

Locate is the inverse: the live https URL for a (type, id).

func (Domain) Register

func (Domain) Register(app *kit.App)

Register installs the client factory and every operation onto app.

type Game

type Game struct {
	GamePK    int    `kit:"id" json:"game_pk"`
	Date      string `json:"date"`
	HomeTeam  string `json:"home_team"`
	AwayTeam  string `json:"away_team"`
	HomeScore int    `json:"home_score"`
	AwayScore int    `json:"away_score"`
	Status    string `json:"status"`
	Venue     string `json:"venue"`
}

Game is one game entry from the schedule endpoint.

type Player

type Player struct {
	ID       int    `kit:"id" json:"id"`
	FullName string `json:"full_name"`
	Number   string `json:"number"`
	Position string `json:"position"`
	TeamID   int    `json:"team_id"`
}

Player is one player from the players endpoint.

type Standing

type Standing struct {
	Division  string `kit:"id" json:"division"`
	TeamName  string `json:"team_name"`
	Wins      int    `json:"wins"`
	Losses    int    `json:"losses"`
	Pct       string `json:"pct"`
	GamesBack string `json:"games_back"`
	Streak    string `json:"streak"`
}

Standing is one team's row in the standings, flattened with division name.

type Team

type Team struct {
	ID           int    `kit:"id" json:"id"`
	Name         string `json:"name"`
	Abbreviation string `json:"abbreviation"`
	TeamName     string `json:"team_name"`
	Location     string `json:"location"`
	FirstYear    string `json:"first_year"`
}

Team is one team from the teams endpoint.