Major League Baseball Game API
Operations pertaining to games
Operations pertaining to games
openapi: 3.0.1
info:
title: Stats API Documentation Analytics Game 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: Game
description: Operations pertaining to games
paths:
/api/v1/game/{game_pk}/playByPlay:
get:
tags:
- Game
summary: Get game play By Play
description: This endpoint allows you to pull the play by play of a game
operationId: playByPlay
parameters:
- name: game_pk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
- name: timecode
in: query
description: 'Use this parameter to return a snapshot of the data at the specified time. Format: YYYYMMDD_HHMMSS'
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
- name: inclusiveTimecode
in: query
description: True to include plays that happen before or at the specified timecode
required: false
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/BaseballPlayByPlayRestObject'
/api/v1/game/{game_pk}/linescore:
get:
tags:
- Game
summary: Get game linescore
description: This endpoint allows you to pull the linescore for a game
operationId: linescore
parameters:
- name: game_pk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
- name: timecode
in: query
description: 'Use this parameter to return a snapshot of the data at the specified time. Format: YYYYMMDD_HHMMSS'
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
- name: inclusiveTimecode
in: query
description: True to include plays that happen before or at the specified timecode
required: false
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/BaseballLinescoreRestObject'
/api/v1/game/{game_pk}/feed/color:
get:
tags:
- Game
summary: Get game color feed.
description: 'This API can return very large payloads. It is STRONGLY recommended that clients ask for diffs and use "Accept-Encoding: gzip" header.'
operationId: colorFeed
parameters:
- name: game_pk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
- name: timecode
in: query
description: 'Use this parameter to return a snapshot of the data at the specified time. Format: YYYYMMDD_HHMMSS'
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;charset=UTF-8:
schema:
type: string
/api/v1/game/{game_pk}/feed/color/timestamps:
get:
tags:
- Game
summary: Retrieve all of the color timestamps for a game.
description: This can be used for replaying games. Endpoint returns all of the timecodes that can be used with diffs for /v1/game/{game_pk}/feed/color
operationId: colorTimestamps
parameters:
- name: game_pk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
responses:
'200':
description: OK
content:
application/json;charset=UTF-8:
schema:
type: array
items:
type: string
/api/v1/game/{game_pk}/content:
get:
tags:
- Game
summary: Retrieve all content for a game.
operationId: content
parameters:
- name: game_pk
in: path
required: true
schema:
type: integer
format: int32
- name: highlightLimit
in: query
description: Number of results to return
required: false
schema:
type: integer
format: int32
responses:
'200':
description: OK
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/GameContentRestObject'
/api/v1/game/{game_pk}/boxscore:
get:
tags:
- Game
summary: Get game boxscore.
description: This endpoint allows you to pull a boxscore
operationId: boxscore
parameters:
- name: game_pk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
- name: timecode
in: query
description: 'Use this parameter to return a snapshot of the data at the specified time. Format: YYYYMMDD_HHMMSS'
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
- name: inclusiveTimecode
in: query
description: True to include plays that happen before or at the specified timecode
required: false
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/BaseballBoxscoreRestObject'
/api/v1/game/{gamePk}/withMetrics:
get:
tags:
- Game
summary: Get game info with metrics
operationId: getGameWithMetrics
parameters:
- name: gamePk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
- name: timecode
in: query
description: 'Use this parameter to return a snapshot of the data at the specified time. Format: YYYYMMDD_HHMMSS'
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:
'*/*':
schema:
$ref: '#/components/schemas/BaseballGameRestObject'
/api/v1/game/{gamePk}/winProbability:
get:
tags:
- Game
summary: Get the win probability for this game
operationId: getWinProbability
parameters:
- name: gamePk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
- name: timecode
in: query
description: 'Use this parameter to return a snapshot of the data at the specified time. Format: YYYYMMDD_HHMMSS'
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
- name: inclusiveTimecode
in: query
description: True to include plays that happen before or at the specified timecode
required: false
schema:
type: boolean
responses:
'200':
description: OK
content:
'*/*':
schema:
type: array
items:
$ref: '#/components/schemas/BaseballPlayRestObject'
/api/v1/game/{gamePk}/contextMetrics:
get:
tags:
- Game
summary: Get the context metrics for this game based on its current state
operationId: getGameContextMetrics
parameters:
- name: gamePk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
- name: timecode
in: query
description: 'Use this parameter to return a snapshot of the data at the specified time. Format: YYYYMMDD_HHMMSS'
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:
'*/*':
schema:
$ref: '#/components/schemas/BaseballGameContextRestObject'
/api/v1/game/changes:
get:
tags:
- Game
summary: View a game change log
operationId: currentGameStats_3
parameters:
- name: updatedSince
in: query
description: 'Format: YYYY-MM-DDTHH:MM:SSZ'
required: false
schema:
type: string
format: date-time
- name: sportId
in: query
description: Top level organization of a sport
required: false
schema:
type: integer
format: int32
x-lookup:
name: Sports
- name: sportIds
in: query
description: Comma delimited list of top level organizations of a sport
required: false
schema:
type: array
items:
type: integer
format: int32
x-lookup:
name: Sports
- name: gameType
in: query
description: Type of Game. Available types in /api/v1/gameTypes
required: false
schema:
$ref: '#/components/schemas/GameTypeEnum'
- name: gameTypes
in: query
description: Comma delimited list of type of Game. Available types in /api/v1/gameTypes
required: false
schema:
type: array
items:
$ref: '#/components/schemas/GameTypeEnum'
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: gamePks
in: query
description: Comma delimited list of unique primary keys
required: false
schema:
uniqueItems: true
type: array
items:
type: integer
format: int32
- name: limit
in: query
description: Number of results to return
required: false
schema:
type: integer
format: int32
- name: offset
in: query
description: The pointer to start for a return set; used for pagination
required: false
schema:
type: integer
format: int32
- 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:
'*/*':
schema:
$ref: '#/components/schemas/ScheduleRestObject'
/api/v1.1/game/{game_pk}/feed/live:
get:
tags:
- Game
summary: Get live game status.
description: 'This API can return very large payloads. It is STRONGLY recommended that clients ask for diffs and use "Accept-Encoding: gzip" header.'
operationId: liveGameV1
parameters:
- name: game_pk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
- name: timecode
in: query
description: 'Use this parameter to return a snapshot of the data at the specified time. Format: YYYYMMDD_HHMMSS'
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
- name: inclusiveTimecode
in: query
description: True to include plays that happen before or at the specified timecode
required: false
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/BaseballGameRestObject'
/api/v1.1/game/{game_pk}/feed/live/timestamps:
get:
tags:
- Game
summary: Retrieve all of the play timestamps for a game.
description: This can be used for replaying games. Endpoint returns all of the timecodes that can be used with diffs for /v1/game/{game_pk}/feed/live
operationId: liveTimestampv11
parameters:
- name: game_pk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
responses:
'200':
description: OK
content:
application/json;charset=UTF-8:
schema:
type: string
/api/v1.1/game/{game_pk}/feed/live/diffPatch:
get:
tags:
- Game
summary: Get live game status.
description: 'This endpoint allows comparison of game files and shows any differences/discrepancies between the two<br/><br/><b>Diff/Patch System:</b> startTimecode and endTimecode can be used for getting diffs.<br/>Expected usage: <br/> 1) Request full payload by not passing startTimecode or endTimecode. This will return the most recent game state.<br/> 2) Find the latest timecode in this response. <br/> 3) Wait X seconds<br/> 4) Use the timecode from 2 as the startTimecode. This will give you a diff of everything that has happened since startTimecode. <br/> 5) If no data is returned, wait X seconds and do the same request. <br/> 6) If data is returned, get a new timeStamp from the response, and use that for the next call as startTimecode.'
operationId: liveGameDiffPatchV1
parameters:
- name: game_pk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
- name: startTimecode
in: query
description: 'Start time code will give you everything since that time. Format: MMDDYYYY_HHMMSS'
required: false
schema:
type: string
- name: endTimecode
in: query
description: 'End time code will give you a snapshot at that specific time. Format: MMDDYYYY_HHMMSS'
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json;charset=UTF-8:
schema:
type: string
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
DraftTypeEnum:
type: string
enum:
- JR
- JS
- NS
- NR
- RV
- AL
- RA
- RT
- JD
- AD
GameStatusRestObject:
type: object
properties:
copyright:
type: string
isCurrentBatter:
type: boolean
isCurrentPitcher:
type: boolean
isOnBench:
type: boolean
isSubstitute:
type: boolean
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
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'
SportTypeEnum:
type: string
enum:
- ALL
- BASEBALL
- HOCKEY
- GOLF
- UNKNOWN
- BASKETBALL
Image:
type: object
properties:
images:
type: object
additionalProperties:
type: string
caption:
type: string
imageType:
$ref: '#/components/schemas/ImageTypeEnum'
url:
type: string
imageTypeAsString:
type: string
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
IFeed:
type: object
properties:
date:
type: string
format: date-time
ScheduleDateRestObject:
type: object
properties:
copyright:
type: string
date:
type: string
format: date
totalItems:
type: integer
format: int32
totalEvents:
type: integer
format: int32
totalGames:
type: integer
format: int32
totalGamesInProgress:
type: integer
format: int32
games:
type: array
items:
$ref: '#/components/schemas/BaseballScheduleItemRestObject'
events:
type: array
items:
$ref: '#/components/schemas/ScheduleEventRestObject'
Venue:
type: object
properties:
requestingUserRole:
# --- truncated at 32 KB (249 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/major-league-baseball/refs/heads/main/openapi/major-league-baseball-game-api-openapi.yml