Major League Baseball Analytics API
Operations pertaining to field tracking and analytics.
Operations pertaining to field tracking and analytics.
openapi: 3.0.1
info:
title: Stats API Documentation Analytics 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: Analytics
description: Operations pertaining to field tracking and analytics.
x-tag-expanded: 'true'
paths:
/api/v1/game/{gamePk}/{guid}/contextMetricsAverages:
get:
tags:
- Analytics
summary: 'Get the field tracking data for a specific play. '
description: 'Returns a json file containing raw coordinate data and refined calculated metrics.<br/><br/>This responses can be very large, so it is strongly recommended that you pass "Accept-Encoding: gzip" as a header to have the responses compressed.'
operationId: contextMetricsWithAverages
parameters:
- name: gamePk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
- name: guid
in: path
description: Unique identifier for a play within a game
required: true
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: array
items:
$ref: '#/components/schemas/CalculatedMetricRestObject'
post:
tags:
- Analytics
summary: 'Get the field tracking data for a specific play. '
description: 'Returns a json file containing raw coordinate data and refined calculated metrics.<br/><br/>This responses can be very large, so it is strongly recommended that you pass "Accept-Encoding: gzip" as a header to have the responses compressed.'
operationId: contextMetricsWithAveragesPost
parameters:
- name: gamePk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
- name: guid
in: path
description: Unique identifier for a play within a game
required: true
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: array
items:
$ref: '#/components/schemas/CalculatedMetricRestObject'
/api/v1/game/{gamePk}/{guid}/homeRunBallparks:
get:
tags:
- Analytics
summary: 'Get the field tracking data for a specific play. '
description: 'Returns a json file containing raw coordinate data and refined calculated metrics.<br/><br/>This responses can be very large, so it is strongly recommended that you pass "Accept-Encoding: gzip" as a header to have the responses compressed.'
operationId: homeRunBallparks
parameters:
- name: gamePk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
- name: guid
in: path
description: Unique identifier for a play within a game
required: true
schema:
type: string
- name: isHomeRunParks
in: query
required: true
schema:
type: boolean
- 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:
$ref: '#/components/schemas/VenuesRestObject'
/api/v1/game/{gamePk}/{guid}/contextMetrics:
get:
tags:
- Analytics
summary: 'Get the field tracking data for a specific play. '
description: 'Returns a json file containing raw coordinate data and refined calculated metrics.<br/><br/>This responses can be very large, so it is strongly recommended that you pass "Accept-Encoding: gzip" as a header to have the responses compressed.'
operationId: contextMetrics
parameters:
- name: gamePk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
- name: guid
in: path
description: Unique identifier for a play within a game
required: true
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: array
items:
$ref: '#/components/schemas/CalculatedMetricRestObject'
/api/v1/game/{gamePk}/{guid}/analytics:
get:
tags:
- Analytics
summary: Tracking data by play/guid
description: 'Returns a json file containing raw coordinate data and refined calculated metrics.<br/><br/>This responses can be very large, so it is strongly recommended that you pass "Accept-Encoding: gzip" as a header to have the responses compressed.'
operationId: parsedJsonFormattedAnalytics
parameters:
- name: gamePk
in: path
description: Unique Primary Key Representing a Game
required: true
schema:
type: integer
format: int32
- name: guid
in: path
description: Unique identifier for a play within a game
required: true
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:
$ref: '#/components/schemas/AnalyticsRestObject'
/api/v1/game/{gamePk}/guids:
get:
tags:
- Analytics
summary: Get play GUIDs by game
description: This endpoint returns Statcast data for all plays in a specific game.
operationId: gameGuids
parameters:
- name: gamePk
in: path
description: Unique Primary Key Representing a Game
required: true
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
- name: gameModeId
in: query
description: 'Statcast game mode. Format: 0 = Batting Practive, 1 = Warmup 2 = Live'
required: false
schema:
type: integer
format: int32
- name: isPitch
in: query
description: If there was a pitch
required: false
schema:
type: boolean
- name: isHit
in: query
description: If there was a hit ball tracked
required: false
schema:
type: boolean
- name: isPickoff
in: query
description: If there was a pickoff
required: false
schema:
type: boolean
- name: hasUpdates
in: query
description: True if updated by an auditor
required: false
schema:
type: boolean
- name: since
in: query
description: 'Returns all data that was created after the specified timestamp. Format: YYYY-MM-DDTHH:MM:SSZ'
required: false
schema:
type: string
format: date-time
- name: updatedSince
in: query
description: 'Return data updated since a specified date. Format: YYYY-MM-DDTHH:MM:SSZ'
required: false
schema:
type: string
format: date-time
- name: lastPlayTime
in: query
description: 'Returns all data that was created after the specified timestamp. Format: YYYY-MM-DDTHH:MM:SSZ'
required: false
schema:
type: string
format: date-time
- name: lastUpdatedTime
in: query
description: 'Return data updated since a specified date. Format: YYYY-MM-DDTHH:MM:SSZ'
required: false
schema:
type: string
format: date-time
- name: lastMetricsUpdatedTime
in: query
description: The last time the metrics were built for this play
required: false
schema:
type: string
format: date-time
- name: lastAuditUpdatedTime
in: query
description: 'Return data updated since a specified date. Format: YYYY-MM-DDTHH:MM:SSZ'
required: false
schema:
type: string
format: date-time
- name: lastVideoUpdatedTime
in: query
description: The last time SportyBot video was updated
required: false
schema:
type: string
format: date-time
responses:
'200':
description: OK
content:
application/json;charset=UTF-8:
schema:
type: array
items:
$ref: '#/components/schemas/AnalyticsPlayMetadataRestObject'
/api/v1/game/lastPitch:
get:
tags:
- Analytics
summary: Get the last pitch for a list of games
operationId: gameLastPitch
parameters:
- name: gamePks
in: query
description: Unique Primary Key Representing a Game
required: true
schema:
type: array
items:
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:
application/json;charset=UTF-8:
schema:
type: array
items:
$ref: '#/components/schemas/AnalyticsPlayMetadataRestObject'
/api/v1/analytics/guids:
get:
tags:
- Analytics
summary: Tracking data by date/time
operationId: gameGuidsFromPostgresRange
parameters:
- 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: gameModeId
in: query
description: 'Statcast game mode. Format: 0 = Batting Practive, 1 = Warmup 2 = Live'
required: false
schema:
type: integer
format: int32
- name: isPitch
in: query
description: If there was a pitch
required: false
schema:
type: boolean
- name: isHit
in: query
description: If there was a hit ball tracked
required: false
schema:
type: boolean
- name: isPickoff
in: query
description: If there was a pickoff
required: false
schema:
type: boolean
- name: isNonStatcast
in: query
description: If non statcast games need to be included
required: false
schema:
type: boolean
- name: gamedayType
in: query
description: Indicates the level of Gameday (tracking, play-by-play, linescore, etc...)
required: false
schema:
type: string
x-lookup:
name: Gameday Types
- name: hasUpdates
in: query
description: True if updated by an auditor
required: false
schema:
type: boolean
- name: lastPlayTime
in: query
description: 'Returns all data that was created after the specified timestamp. Format: YYYY-MM-DDTHH:MM:SSZ'
required: false
schema:
type: string
format: date-time
- name: lastUpdatedTime
in: query
description: 'Return data updated since a specified date. Format: YYYY-MM-DDTHH:MM:SSZ'
required: false
schema:
type: string
format: date-time
- name: lastMetricsUpdatedTime
in: query
description: 'Return data updated since a specified date. Format: YYYY-MM-DDTHH:MM:SSZ'
required: false
schema:
type: string
format: date-time
- name: lastAuditUpdatedTime
in: query
description: 'Return data updated since a specified date. Format: YYYY-MM-DDTHH:MM:SSZ'
required: false
schema:
type: string
format: date-time
- name: lastVideoUpdatedTime
in: query
description: The last time SportyBot video was updated
required: false
schema:
type: string
format: date-time
- name: gameDate
in: query
description: 'Date of Game. Format: YYYY-MM-DD'
required: false
schema:
type: string
format: date
- name: sportId
in: query
description: Top level organization of a sport
required: false
schema:
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'
x-lookup:
name: Game Types
- name: season
in: query
description: Season of play
required: false
schema:
type: string
- name: sortBy
in: query
description: Sort the set of data by the specified field
required: false
schema:
type: string
- 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
responses:
'200':
description: OK
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/AnalyticsPlayMetadataWrapperRestObject'
/api/v1/analytics/game:
get:
tags:
- Analytics
summary: Get tracking metadata for games
operationId: gameGuidsFromPostgresRangeByGame
parameters:
- 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: gameModeId
in: query
description: 'Statcast game mode. Format: 0 = Batting Practive, 1 = Warmup 2 = Live'
required: false
schema:
type: integer
format: int32
- name: isPitch
in: query
description: If there was a pitch
required: false
schema:
type: boolean
- name: isHit
in: query
description: If there was a hit ball tracked
required: false
schema:
type: boolean
- name: isPickoff
in: query
description: If there was a pickoff
required: false
schema:
type: boolean
- name: isNonStatcast
in: query
description: If non statcast games need to be included
required: false
schema:
type: boolean
- name: gamedayType
in: query
description: Indicates the level of Gameday (tracking, play-by-play, linescore, etc...)
required: false
schema:
type: string
x-lookup:
name: Gameday Types
- name: hasUpdates
in: query
description: True if updated by an auditor
required: false
schema:
type: boolean
- name: lastPlayTime
in: query
description: 'Returns all data that was created after the specified timestamp. Format: YYYY-MM-DDTHH:MM:SSZ'
required: false
schema:
type: string
format: date-time
- name: lastVideoUpdatedTime
in: query
description: The last time SportyBot video was updated
required: false
schema:
type: string
format: date-time
- name: lastUpdatedTime
in: query
description: 'Return data updated since a specified date. Format: YYYY-MM-DDTHH:MM:SSZ'
required: false
schema:
type: string
format: date-time
- name: lastMetricsUpdatedTime
in: query
description: 'Return data updated since a specified date. Format: YYYY-MM-DDTHH:MM:SSZ'
required: false
schema:
type: string
format: date-time
- name: lastAuditUpdatedTime
in: query
description: 'Return data updated since a specified date. Format: YYYY-MM-DDTHH:MM:SSZ'
required: false
schema:
type: string
format: date-time
- name: gameDate
in: query
description: Comma delimited list of top level organizations of a sport
required: false
schema:
type: string
format: date
x-lookup:
name: Sports
- name: sportId
in: query
description: Top level organization of a sport
required: false
schema:
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: season
in: query
description: Season of play
required: false
schema:
type: string
- name: sortBy
in: query
description: Sort the set of data by the specified field
required: false
schema:
type: string
- 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
responses:
'200':
description: OK
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/AnalyticsGameMetadataWrapperRestObject'
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
RestObject:
type: object
properties:
copyright:
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
BatPositionRestObject:
type: object
properties:
copyright:
type: string
positionId:
type: string
description: Identifier for which part of the bat the positions/timeStamp represent. For now this will only be the “head” and the “handle”, but is subject to change in the future.
positions:
type: array
description: Locations of the head of the bat at the given timeStamps.
items:
$ref: '#/components/schemas/PositionRestObject'
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:
# --- truncated at 32 KB (265 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/major-league-baseball/refs/heads/main/openapi/major-league-baseball-analytics-api-openapi.yml