mlb-sdk

⚾ Idiomatic Go library for the public MLB Stats API.

A typed Go client for statsapi.mlb.com. MLB does not publish an OpenAPI specification, so this repo authors one and generates the underlying client from it. Builds on years of community reverse engineering by toddrob99/MLB-StatsAPI (Python) and BillPetti/baseballr (R); the public surface in pkg/mlb hides the API's quirks behind idiomatic helpers.

📦 Install

go get github.com/retr0h/mlb-sdk/pkg/mlb

⚙️ Endpoints

40+ endpoints (click to expand)

Endpoint	Docs	Example
/api/v1/schedule	Client.Schedule	schedule.go
/api/v1/game/changes	Client.GameChanges	gamechanges.go
/api/v1/game/{gamePk}/boxscore	Client.Boxscore	boxscore.go
/api/v1/game/{gamePk}/playByPlay	Client.PlayByPlay	playbyplay.go
/api/v1.1/game/{gamePk}/feed/live	Client.LiveFeed	livefeed.go
/api/v1/gamePace	Client.GamePace	gamepace.go
/api/v1/highLow/{orgType}	Client.HighLow	highlow.go
/api/v1/jobs/umpires	Client.Umpires	umpires.go
/api/v1/stats/leaders	Client.StatsLeaders	statsleaders.go
/api/v1/game/{gamePk}/feed/live/timestamps	Client.GameTimestamps	gametimestamps.go
/api/v1/game/{gamePk}/feed/color/timestamps	Client.GameColorTimestamps	gamecolortimestamps.go
/api/v1/game/{gamePk}/contextMetrics	Client.ContextMetrics	contextmetrics.go
/api/v1/game/{gamePk}/linescore	Client.Linescore	linescore.go
/api/v1/standings	Client.Standings	standings.go
/api/v1/teams/{teamId}/coaches	Client.Coaches	coaches.go
/api/v1/teams/{teamId}/personnel	Client.Personnel	personnel.go
/api/v1/teams/{teamId}/roster	Client.Roster	roster.go
/api/v1/teams/{teamId}/stats	Client.TeamStats	teamstats.go
/api/v1/venues/{venueId}	Client.Venue	venue.go
/api/v1/conferences	Client.Conferences	conferences.go
/api/v1/divisions	Client.Divisions	divisions.go
/api/v1/draft/{year}	Client.Draft	draft.go
/api/v1/league	Client.Leagues	leagues.go
/api/v1/attendance	Client.Attendance	attendance.go
/api/v1/awards/{awardId}/recipients	Client.AwardRecipients	awards.go
/api/v1/transactions	Client.Transactions	transactions.go
/api/v1/seasons	Client.Seasons	seasons.go
/api/v1/seasons/{seasonId}	Client.Season	season.go
/api/v1/sports	Client.Sports	sports.go
/api/v1/people/{personId}	Client.Person	person.go
/api/v1/people	Client.People	people.go
/api/v1/people/freeAgents	Client.FreeAgents	freeagents.go
/api/v1/teams	Client.Teams	teams.go
/api/v1/teams/{teamId}	Client.Team	team.go
/api/v1/teams/affiliates	Client.TeamsAffiliates	teamsaffiliates.go
/api/v1/teams/history	Client.TeamsHistory	teamshistory.go
/api/v1/schedule/games/tied	Client.ScheduleTied	scheduletied.go

Run any example with go run examples/<name>.go. Roadmap for additional endpoints lives in docs/roadmap.md.

✨ Features

Feature	Description
OpenAPI-first	Hand-authored spec + generated client (oapi-codegen)
Idiomatic surface	time.Time, typed mlb.TeamID, helper methods
Hides API quirks	e.g. box.Team(mlb.LAD).DoublePlaysTurned()
Test-friendly	WithBaseURL injects an httptest.Server for fixtures

💡 Inspiration

This module exists because the MLB Stats API is undocumented and the most useful prior art is in Python and R:

• toddrob99/MLB-StatsAPI
• appac/mlb-data-api-docs
• BillPetti/baseballr

📖 Documentation

See the package documentation on pkg.go.dev for API details.

🤝 Contributing

See the Development guide for prerequisites, setup, and conventions. See the Contributing guide before submitting a PR.

🔗 Related projects

Project	Description
mlb-mcp	MCP server that exposes this SDK as tools for LLMs

⚖️ Copyright notice

This package and its author are not affiliated with MLB or any MLB team. This module is a typed Go client for MLB's public Stats API. Use of MLB data is subject to the notice posted at http://gdx.mlb.com/components/copyright.txt.

📄 License

The MIT License.