Major League Baseball Analytics API
Operations pertaining to field tracking and analytics.
Operations pertaining to field tracking and analytics.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/major-league-baseball-analytics-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
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
InningTeamInfoRestObject:
type: object
properties:
copyright:
type: string
runs:
type: integer
format: int32
hits:
type: integer
format: int32
errors:
type: integer
format: int32
leftOnBase:
type: integer
format: int32
BaseballPitch:
type: object
properties:
ballColor:
type: string
trailColor:
type: string
startSpeed:
type: number
format: double
endSpeed:
type: number
format: double
nastyFactor:
type: number
format: double
strikeZoneTop:
type: number
format: double
strikeZoneBottom:
type: number
format: double
strikeZoneWidth:
type: number
format: double
strikeZoneDepth:
type: number
format: double
getaX:
type: number
format: double
getaY:
type: number
format: double
getaZ:
type: number
format: double
pfxX:
type: number
format: double
pfxZ:
type: number
format: double
getpX:
type: number
format: double
getpZ:
type: number
format: double
getvX0:
type: number
format: double
getvY0:
type: number
format: double
getvZ0:
type: number
format: double
x:
type: number
format: double
y:
type: number
format: double
z0:
type: number
format: double
y0:
type: number
format: double
x0:
type: number
format: double
breakAngle:
type: number
format: double
breakLength:
type: number
format: double
breakX:
type: number
format: double
breakY:
type: number
format: double
breakZ:
type: number
format: double
zone:
type: integer
format: int32
spinRate:
type: integer
format: int32
spinDirection:
type: integer
format: int32
typeConfidence:
type: number
format: double
plateTime:
type: number
format: double
extension:
type: number
format: double
WeatherRestObject:
type: object
properties:
copyright:
type: string
condition:
type: string
temp:
type: string
wind:
type: string
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
XrefIdRestObject:
type: object
properties:
copyright:
type: string
xrefId:
type: string
xrefType:
type: string
xrefIdTwo:
type: string
season:
type: string
FranchiseRestObject:
type: object
properties:
copyright:
type: string
franchiseId:
type: integer
format: int32
firstSeasonId:
type: integer
format: int32
lastSeasonId:
type: integer
format: int32
mostRecentTeamId:
type: integer
format: int32
teamName:
type: string
locationName:
type: string
link:
type: string
roster:
$ref: '#/components/schemas/RosterRestObject'
VenueRestObject:
type: object
properties:
copyright:
type: string
hydrations:
type: array
# --- 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