mlb, kbo, or npb as the league. All three expose schedules, teams,
players, rosters, venues, standings, current odds/props, and baseball composites.
Statistics and historical reads require the stats entitlement.
Game workflow
The game projection includes optional weather measurements such as
temp_f,
feels_like_f, dew_point_f, wind_mph, wind_deg, wind_dir, humidity_pct,
precip_prob_pct, cloud_pct, and pressure_hpa. Display missing values as
unavailable. game_type distinguishes regular, postseason, spring, exhibition,
all-star, and other when known; a schedule does not promise all of these
categories have been ingested.
Lineup cards
/games/{id}/lineup-card?side=home|away can limit the card to one team.
Each side reports lineup_source=confirmed|projected|estimated; estimates use
prior lineups and roster evidence. Label each side separately, because one
team can be confirmed while the other remains estimated.
The card’s full flag distinguishes MLB’s advanced card from KBO/NPB’s lighter
card. MLB can supply all, vs_rhp, vs_lhp, vs_starter, and
vs_pitch_mix per batter, matched to the opposing probable starter. KBO/NPB
cards currently supply season lines without those advanced blocks. Missing
starter or metric data should not be replaced with zero.
Player and team context
| Route | Behavior | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | |/players/{id}/profile | Identity, season line, splits, recent form, and injury in one call; data.data. |
| /players/{id}/game-log | Newest-first games; role=batter | pitcher, season, last. data.data.games. |
| /players/compare?ids=A,B | Two to six players, one shared season, scope; for exactly two, metric deltas. Additional IDs beyond six are ignored. data.data. |
| /teams/{id}/snapshot | Standings, injuries, and next game; data.data. |
| /teams/{id}/fielding-stats?season=YEAR | Season fielding profile. |
| /teams/{id}/injuries, /injuries | MLB injury entries; KBO/NPB registration and roster status. |
Game-log defaults to 25 games without a season; last caps at 200. With
season and no last, it returns the full completed regular-season log.
Comparison without a season resolves one season shared by the requested
players rather than comparing unrelated seasons.
Deep statistics by league
The routes below use/v1/{league} and player/team IDs as indicated.
Several MLB deep-stat reads require season=YEAR, including player batting,
pitching, arsenal, pitch-type, discipline, zone, and first-inning reads. A
missing season is a validation error on those routes. Use the reference’s
required flag rather than assuming every endpoint selects the latest season.
Player batting/pitching split scopes include
all, home, away, recent
windows such as l3, l7, l10, and handedness splits: vs_lhp/vs_rhp
for batting, vs_lhh/vs_rhh for pitching, where the league’s stored
derivations support them. A supported parameter does not guarantee a populated
split for every player. Team-stat responses can contain several scopes at once;
do not assume a player scope filter applies to a team route.
Many advanced-stat blocks are provider-derived documents. Metric names,
availability, and units follow that block’s league/source contract; retain
returned keys rather than renaming camelCase to snake_case automatically.
MLB’s NRFI response includes a probability/model and market comparison when
available. KBO/NPB also return a nullable nrfi_probability with
model="heuristic_v1", using first-inning inputs and neutral park context;
they use a different shape and omit MLB’s market/park comparison fields.
Play-by-play and recaps
MLB’s generic play-by-play object containsgame, pitches, and plays.
KBO and NPB have static routes at the same public path and their own DTOs.
Recaps expose moment_basis: win-probability-based rankings and run-impact
rankings should be labeled according to the returned basis. A final game can
still be missing detailed play or box-score enrichment.
See Odds, Props & Signals for pricing/edge reads and
IDs, Assets & Availability for source and
freshness conventions.
Metric definitions and units
The reference includes the producer fields for derived batting, pitching, arsenal, zone, and team-stat documents. These blocks retain camelCase metric names even when the surrounding API uses snake_case. Older seasons and source coverage can omit fields; null rates indicate missing inputs or an undefined denominator.
Do not infer units from a
Pct suffix across sources. KBO preserves some
upstream metrics, such as wrcPlusFromSource and warFromSource, rather than
recomputing them as MLB derivations. Zone grids differ: MLB’s
zoneSystem="statcast14" uses zones 1–9 and 11–14, while KBO exposes a nine-zone
grid. Use the grid identifier and sample counts when rendering heatmaps.