Major League Baseball League API
Operations pertaining to leagues
Operations pertaining to leagues
openapi: 3.0.1
info:
title: Stats API Documentation Analytics League API
description: Official API for Major League Baseball.
version: 2.0.0
servers:
- url: https://statsapi.mlb.com
description: Production
- url: https://beta-statsapi.mlb.com
description: Beta
- url: https://qa-statsapi.mlb.com
description: QA
- url: http://localhost:8080
description: Local
tags:
- name: League
description: Operations pertaining to leagues
paths:
/api/v1/league:
get:
tags:
- League
summary: View league info
operationId: league
parameters:
- name: leagueId
in: path
description: Unique League Identifier
required: true
schema:
type: integer
format: int32
- name: leagueIds
in: query
description: Comma delimited list of Unique league identifiers
required: false
schema:
type: array
items:
type: integer
format: int32
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: seasons
in: query
description: Comma delimited list of Seasons of play
required: false
schema:
type: array
items:
type: string
- name: fields
in: query
description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
required: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: sportId
in: query
description: Top level organization of a sport
required: false
schema:
type: integer
format: int32
x-lookup:
name: Sports
- name: activeStatus
in: query
description: Flag for fetching leagues that are currently active (Y), inactive (N), pending (P), or all teams (B)
required: false
schema:
$ref: '#/components/schemas/LeagueActiveStatusEnum'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LeaguesRestObject'
post:
tags:
- League
summary: Update league cache
operationId: leagueIdsUpdate
parameters:
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: sportId
in: query
description: Top level organization of a sport
required: false
schema:
type: integer
format: int32
x-lookup:
name: Sports
responses:
'200':
description: OK
content:
'*/*':
schema:
type: string
/api/v1/leagues:
get:
tags:
- League
summary: View league info
operationId: league_2
parameters:
- name: leagueId
in: path
description: Unique League Identifier
required: true
schema:
type: integer
format: int32
- name: leagueIds
in: query
description: Comma delimited list of Unique league identifiers
required: false
schema:
type: array
items:
type: integer
format: int32
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: seasons
in: query
description: Comma delimited list of Seasons of play
required: false
schema:
type: array
items:
type: string
- name: fields
in: query
description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
required: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: sportId
in: query
description: Top level organization of a sport
required: false
schema:
type: integer
format: int32
x-lookup:
name: Sports
- name: activeStatus
in: query
description: Flag for fetching leagues that are currently active (Y), inactive (N), pending (P), or all teams (B)
required: false
schema:
$ref: '#/components/schemas/LeagueActiveStatusEnum'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LeaguesRestObject'
post:
tags:
- League
summary: Update league cache
operationId: leagueIdsUpdate_1
parameters:
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: sportId
in: query
description: Top level organization of a sport
required: false
schema:
type: integer
format: int32
x-lookup:
name: Sports
responses:
'200':
description: OK
content:
'*/*':
schema:
type: string
/api/v1/league/{leagueId}/allStarWriteIns:
get:
tags:
- League
summary: All-Star write-ins
operationId: allStarWriteIns
parameters:
- name: leagueId
in: path
description: Unique League Identifier
required: true
schema:
type: integer
format: int32
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: fields
in: query
description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
required: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PeopleRestObject'
/api/v1/leagues/{leagueId}/allStarWriteIns:
get:
tags:
- League
summary: All-Star write-ins
operationId: allStarWriteIns_1
parameters:
- name: leagueId
in: path
description: Unique League Identifier
required: true
schema:
type: integer
format: int32
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: fields
in: query
description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
required: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PeopleRestObject'
/api/v1/league/{leagueId}/allStarFinalVote:
get:
tags:
- League
summary: All-Star final vote
operationId: allStarFinalVote
parameters:
- name: leagueId
in: path
description: Unique League Identifier
required: true
schema:
type: integer
format: int32
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: fields
in: query
description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
required: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PeopleRestObject'
/api/v1/leagues/{leagueId}/allStarFinalVote:
get:
tags:
- League
summary: All-Star final vote
operationId: allStarFinalVote_1
parameters:
- name: leagueId
in: path
description: Unique League Identifier
required: true
schema:
type: integer
format: int32
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: fields
in: query
description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
required: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PeopleRestObject'
/api/v1/league/allStarBallot:
get:
tags:
- League
summary: All-Star Ballot
operationId: allStarBallot
parameters:
- name: leagueId
in: path
description: Unique League Identifier
required: true
schema:
type: integer
format: int32
- name: leagueIds
in: query
description: Comma delimited list of Unique league identifiers
required: false
schema:
type: array
items:
type: integer
format: int32
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: fields
in: query
description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
required: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PeopleRestObject'
/api/v1/league/{leagueId}/allStarBallot:
get:
tags:
- League
summary: All-Star Ballot
operationId: allStarBallot_1
parameters:
- name: leagueId
in: path
description: Unique League Identifier
required: true
schema:
type: integer
format: int32
- name: leagueIds
in: query
description: Comma delimited list of Unique league identifiers
required: false
schema:
type: array
items:
type: integer
format: int32
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: fields
in: query
description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
required: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PeopleRestObject'
/api/v1/leagues/allStarBallot:
get:
tags:
- League
summary: All-Star Ballot
operationId: allStarBallot_2
parameters:
- name: leagueId
in: path
description: Unique League Identifier
required: true
schema:
type: integer
format: int32
- name: leagueIds
in: query
description: Comma delimited list of Unique league identifiers
required: false
schema:
type: array
items:
type: integer
format: int32
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: fields
in: query
description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
required: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PeopleRestObject'
/api/v1/leagues/{leagueId}/allStarBallot:
get:
tags:
- League
summary: All-Star Ballot
operationId: allStarBallot_3
parameters:
- name: leagueId
in: path
description: Unique League Identifier
required: true
schema:
type: integer
format: int32
- name: leagueIds
in: query
description: Comma delimited list of Unique league identifiers
required: false
schema:
type: array
items:
type: integer
format: int32
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: fields
in: query
description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
required: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PeopleRestObject'
/api/v1/league/{leagueId}:
get:
tags:
- League
summary: View league info
operationId: league_1
parameters:
- name: leagueId
in: path
description: Unique League Identifier
required: true
schema:
type: integer
format: int32
- name: leagueIds
in: query
description: Comma delimited list of Unique league identifiers
required: false
schema:
type: array
items:
type: integer
format: int32
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: seasons
in: query
description: Comma delimited list of Seasons of play
required: false
schema:
type: array
items:
type: string
- name: fields
in: query
description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
required: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: sportId
in: query
description: Top level organization of a sport
required: false
schema:
type: integer
format: int32
x-lookup:
name: Sports
- name: activeStatus
in: query
description: Flag for fetching leagues that are currently active (Y), inactive (N), pending (P), or all teams (B)
required: false
schema:
$ref: '#/components/schemas/LeagueActiveStatusEnum'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LeaguesRestObject'
/api/v1/leagues/{leagueId}:
get:
tags:
- League
summary: View league info
operationId: league_3
parameters:
- name: leagueId
in: path
description: Unique League Identifier
required: true
schema:
type: integer
format: int32
- name: leagueIds
in: query
description: Comma delimited list of Unique league identifiers
required: false
schema:
type: array
items:
type: integer
format: int32
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: seasons
in: query
description: Comma delimited list of Seasons of play
required: false
schema:
type: array
items:
type: string
- name: fields
in: query
description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
required: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: sportId
in: query
description: Top level organization of a sport
required: false
schema:
type: integer
format: int32
x-lookup:
name: Sports
- name: activeStatus
in: query
description: Flag for fetching leagues that are currently active (Y), inactive (N), pending (P), or all teams (B)
required: false
schema:
$ref: '#/components/schemas/LeagueActiveStatusEnum'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LeaguesRestObject'
components:
schemas:
TeamStatData:
type: object
properties:
requestingUserRole:
$ref: '#/components/schemas/Role'
note:
type: string
summary:
type: object
additionalProperties:
type: string
writeOnly: true
catchersInterference:
type: integer
format: int32
average:
type: string
onBasePercentage:
type: string
onBasePlusSlugging:
type: string
stolenBases:
type: integer
format: int32
caughtStealing:
type: integer
format: int32
slugging:
type: string
outs:
type: integer
format: int32
gidp:
type: integer
format: int32
gitp:
type: integer
format: int32
homeRuns:
type: integer
format: int32
numberOfPitches:
type: integer
format: int32
totalBases:
type: integer
format: int32
gidpOpportunites:
type: integer
format: int32
walks:
type: integer
format: int32
hitByPitch:
type: integer
format: int32
strikeouts:
type: integer
format: int32
airOuts:
type: integer
format: int32
goAo:
type: string
pitchesPerPlateAppearance:
type: number
format: double
intentionalWalks:
type: integer
format: int32
groundOuts:
type: integer
format: int32
flyOuts:
type: integer
format: int32
games:
type: integer
format: int32
gamesStarted:
type: integer
format: int32
doubles:
type: integer
format: int32
hits:
type: integer
format: int32
triples:
type: integer
format: int32
singles:
type: integer
format: int32
runs:
type: integer
format: int32
atBats:
type: integer
format: int32
pickoffs:
type: integer
format: int32
stolenBasePercentage:
type: string
wildPitches:
type: integer
format: int32
sacFlies:
type: integer
format: int32
sacBunts:
type: integer
format: int32
putouts:
type: integer
format: int32
assists:
type: integer
format: int32
chances:
type: integer
format: int32
streak:
type: integer
format: int32
battingOrder:
type: string
totalSwings:
type: integer
format: int32
swingsAndMisses:
type: integer
format: int32
ballsInPlay:
type: integer
format: int32
popOuts:
type: integer
format: int32
lineOuts:
type: integer
format: int32
flyHits:
type: integer
format: int32
popHits:
type: integer
format: int32
lineHits:
type: integer
format: int32
groundHits:
type: integer
format: int32
winStreak:
type: integer
format: int32
lossStreak:
type: integer
format: int32
plateAppearances:
type: integer
format: int32
stolenBasePercentageOrNull:
type: string
pitchesPerPlateAppearanceStr:
type: string
AdditionalBio:
type: object
properties:
id:
type: integer
format: int32
homeTown:
type: string
GameStatusRestObject:
type: object
properties:
copyright:
type: string
isCurrentBatter:
type: boolean
isCurrentPitcher:
type: boolean
isOnBench:
type: boolean
isSubstitute:
type: boolean
DraftTypeEnum:
type: string
enum:
- JR
- JS
- NS
- NR
- RV
- AL
- RA
- RT
- JD
- AD
WeatherRestObject:
type: object
properties:
copyright:
type: string
condition:
type: string
temp:
type: string
wind:
type: string
DraftTypeEnumRestObject:
type: object
properties:
copyright:
type: string
code:
type: string
description:
type: string
BaseballDefenseRestObject:
type: object
properties:
copyright:
type: string
pitcher:
$ref: '#/components/schemas/BaseballPersonRestObject'
catcher:
$ref: '#/components/schemas/BaseballPersonRestObject'
first:
$ref: '#/components/schemas/BaseballPersonRestObject'
second:
$ref: '#/components/schemas/BaseballPersonRestObject'
third:
$ref: '#/components/schemas/BaseballPersonRestObject'
shortstop:
$ref: '#/components/schemas/BaseballPersonRestObject'
left:
$ref: '#/components/schemas/BaseballPersonRestObject'
center:
$ref: '#/components/schemas/BaseballPersonRestObject'
right:
$ref: '#/components/schemas/BaseballPersonRestObject'
batter:
$ref: '#/components/schemas/BaseballPersonRestObject'
onDeck:
$ref: '#/components/schemas/BaseballPersonRestObject'
inHole:
$ref: '#/components/schemas/BaseballPersonRestObject'
battingOrder:
type: integer
format: int32
team:
$ref: '#/components/schemas/BaseballTeamRestObject'
EducationRestObject:
type: object
properties:
copyright:
type: string
highschools:
type: array
items:
$ref: '#/components/schemas/SchoolRestObject'
colleges:
type: array
items:
$ref: '#/components/schemas/SchoolRestObject'
StatContainer:
type: object
properties:
type:
$ref: '#/components/schemas/StatType'
group:
$ref: '#/components/schemas/StatGroup'
splits:
type: array
items:
$ref: '#/components/schemas/StatSplits'
splitsTiedWithOffset:
type: array
items:
$ref: '#/components/schemas/StatSplits'
splitsTiedWithLimit:
type: array
items:
$ref: '#/components/schemas/StatSplits'
stats:
$ref: '#/components/schemas/StatData'
totalSplits:
type: integer
format: int32
player:
$ref: '#/components/schemas/BaseballPerson'
team:
$ref: '#/components/schemas/BaseballTeam'
sport:
$ref: '#/components/schemas/Sport'
season:
type: string
gameType:
$ref: '#/components/schemas/GameTypeEnum'
playerPool:
$ref: '#/components/schemas/PlayerPoolEnum'
exemptions:
type: array
items:
$ref: '#/components/schemas/PlayerListPerson'
parameters:
type: object
additionalProperties:
type: object
disclaimers:
uniqueItems: true
type: array
items:
type: string
totalSplitsIfNotSet:
type: integer
format: int32
writeOnly: true
FieldInfoRestObject:
type: object
properties:
copyright:
type: string
capacity:
type: integer
format: int32
turfType:
type: string
roofType:
type: string
leftLine:
type: integer
format: int32
left:
type: integer
format: int32
leftCenter:
type: integer
format: int32
center:
type: integer
format: int32
rightCenter:
type: integer
format: int32
right:
type: integer
format: int32
rightLine:
type: integer
format: int32
BaseballTeamStandingsRecord:
type: object
properties:
team:
$ref: '#/components/schemas/BaseballTeam'
wins:
type: integer
format: int32
losses:
type: integer
format: int32
ties:
type: integer
format: int32
gamesBack:
type: string
wildCardGamesBack:
type: string
leagueGamesBack:
type: string
springLeagueGamesBack:
type: string
sportGamesBack:
type: string
divisionGamesBack:
type: string
conferenceGamesBack:
type: string
divisionChamp:
type: boolean
season:
type: string
streak:
type: string
lastUpdated:
type: string
format: date-time
home:
type: string
away:
type: string
lastTen:
type: string
points:
type: integer
format: int32
clinchIndicator:
type: string
divisionRank:
type: string
conferenceRank:
type: string
springLeagueRank:
type: string
leagueRank:
type: string
sportRank:
type: string
wildCardRank:
type: string
gamesPlayed:
type: integer
format: int32
place:
type: integer
format: int32
wildcardPlace:
type: integer
format: int32
wildcardOdds:
type: number
format: double
divisionOdds:
type: number
format: double
playoffOdds:
type: number
format: double
runsAllowed:
type: integer
format: int32
runsScored:
type: integer
format: int32
hasWildcard:
type: boolean
clinched:
type: boolean
eliminationNumber:
type: string
eliminationNumberWildcard:
type: string
magicNumber:
type: string
hasPlayoffPoints:
type: boolean
vsWest:
type: string
vsCentral:
type: string
vsEast:
type: string
vsInterleague:
type: string
vsRight:
type: string
vsRightHomeWin:
type: string
vsRightHomeLoss:
type: string
vsRightAwayWin:
type: string
vsRightAwayLoss:
type: string
vsLeft:
type: string
vsLeftHomeWin:
type: string
vsLeftHomeLoss:
type: string
vsLeftAwayWin:
type: string
vsLeftAwayLoss:
type: string
vsWinners:
type: string
extraInnings:
type: string
expectedWinLoss:
type: string
expectedWinLossSeason:
type: string
oneRunGames:
type: string
turf:
type: string
grass:
type: string
night:
type: string
day:
type: string
isWildCardTeam:
type: boolean
writeOnly: true
isDivisionLeader:
type: boolean
writeOnly: true
divisionRecords:
type: array
items:
$ref: '#/components/schemas/WinLossRecord'
conferenceRecords:
type: array
items:
$ref: '#/components/schemas/WinLossRecord'
leagueRecords:
type: array
items:
$ref: '#/components/schemas/WinLossRecord'
splitRecords:
type: array
items:
$ref: '#/components/schemas/WinLossRecord'
expectedRecords:
type: array
items:
$ref: '#/components/schemas/WinLossRecord'
overallRecords:
type: array
items:
$ref: '#/components/schemas/WinLossRecord'
conference:
$ref: '#/components/schemas/Conference'
wildCardLeader:
type: boolean
runDifferental:
type: integer
format: int32
winningPercentage:
type: number
format: double
RunnerDetailType:
type: string
enum:
- START_BASE
- SEQUENCE
- RUNNER_GOING
- END_BASE
- RUNNER_OUT
- FORCED_OUT
- ADVANCED_ON_FORCE
- ADVANCED_ON_THROW
- ADVANCED_ON_PLAY
- DOUBLED_OFF
- THROWN_OUT
- TAGGED_OUT
- OUT_STRETCHING
- LEFT_EARLY
- FIELDERS_CHOICE
- OUT_ON_APPEAL
- OUT_ADVANCING
- DEFENSIVE_INDIFFERENCE
- INTERFERENCE
- HIT_BY_BATTED_BALL
- OUT_OVER_RUNNING
- OUT_RETURNING
- RUNDOWN
- CAUGHT_STEALING_2B
- CAUGHT_STEALING_3B
- CAUGHT_STEALING_HOME
- PICKOFF_CAUGHT_STEALING_2B
- PICKOFF_CAUGHT_STEALING_3B
- PICKOFF_CAUGHT_STEALING_HOME
- STOLEN_BASE_2B
- STOLEN_BASE_3B
- STOLEN_BASE_HOME
- PICKOFF_1B
- PICKOFF_2B
- PICKOFF_3B
- PICKOFF_ERROR_1B
- PICKOFF_ERROR_2B
- PICKOFF_ERROR_3B
- UNKNOWN
VenueMetadata:
type: object
properties:
active:
type: boolean
capacity:
type: integer
format: int32
startYear:
type: integer
format: int32
endYear:
type: integer
format: int32
types:
type: array
items:
$ref: '#/components/schemas/VenueTypeEnum'
Image:
type: object
properties:
images:
type: object
additionalProperties:
type: string
caption:
type: string
imageType:
$ref: '#/components/schemas/ImageTypeEnum'
url:
type: string
imageTypeAsString:
type: string
SportTypeEnum:
type: string
enum:
- ALL
- BASEBALL
- HOCKEY
- GOLF
- UNKNOWN
- BASKETBALL
IFeed:
type: object
properties:
date:
type: string
format: date-time
Schedu
# --- truncated at 32 KB (239 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/major-league-baseball/refs/heads/main/openapi/major-league-baseball-league-api-openapi.yml