openapi: 3.1.0
info:
title: MLB MLB v3 Headshots MLB v3 Stats API
version: '1.0'
description: MLB API - OpenAPI 3.1 Specification
servers:
- url: https://api.sportsdata.io
description: Production server
security:
- apiKeyHeader: []
- apiKeyQuery: []
tags:
- name: MLB v3 Stats
paths:
/v3/mlb/stats/{format}/PlayerGameStatsByDate/{date}:
get:
description: Returns the box score statistical record for all involved players across a given date, updated live as the game takes place.
operationId: mlb_v3_stats_player_game_stats___by_date__live___final
summary: Player Game Stats - by Date [Live & Final]
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: date
in: path
description: 'The date of the game(s).
<br>Examples: <code>2017-JUL-31</code>, <code>2017-SEP-01</code>.'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PlayerGame'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/PlayerSeasonStats/{season}:
get:
description: Returns all season-long stats (i.e. the season total, not each individual game record) for all players for a given season.
operationId: mlb_v3_stats_player_season_stats
summary: Player Season Stats
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: season
in: path
description: 'Year of the season.
<br>Examples: <code>2017</code>, <code>2018</code>.'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PlayerSeason'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/PlayerSeasonStatsByTeam/{season}/{team}:
get:
description: Returns all season-long stats (i.e. the season total, not each individual game record) for a given team's players in a given season.
operationId: mlb_v3_stats_player_season_stats___by_team
summary: Player Season Stats - by Team
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: season
in: path
description: 'Year of the season.
<br>Examples: <code>2017</code>, <code>2018</code>.
'
required: true
schema:
type: string
- name: team
in: path
description: 'The abbreviation of the requested team.
<br>Examples: <code>SF</code>, <code>NYY</code>.'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PlayerSeason'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/BoxScores/{date}:
get:
description: Full statistical information for a specified game, down to the team and player stat level, delivered live during the game, called for all games on a given date.
operationId: mlb_v3_stats_box_scores___by_date__live___final
summary: Box Scores - by Date [Live & Final]
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: date
in: path
description: 'The date of the game(s).
<br>Examples: <code>2017-JUL-31</code>, <code>2017-SEP-01</code>.'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BoxScore'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/BoxScore/{gameid}:
get:
description: Full statistical information for a specified game, down to the team and player stat level, delivered live during the game, called per individual game.
operationId: mlb_v3_stats_box_score__live___final
summary: Box Score [Live & Final]
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: gameid
in: path
description: The GameID of an MLB game. GameIDs can be found in the Games API. Valid entries are <code>14620</code> or <code>16905</code>
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BoxScore'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/BoxScoresDelta/{date}/{minutes}:
get:
description: This method returns all box scores for a given date, but only returns player stats that have changed in the last X minutes as specified in your API call. By definition this is a live endpoint, not final.
operationId: mlb_v3_stats_box_scores_delta___by_date
summary: Box Scores Delta - by Date
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: date
in: path
description: 'The date of the game(s).
<br>Examples: <code>2017-JUL-31</code>, <code>2017-SEP-01</code>.'
required: true
schema:
type: string
- name: minutes
in: path
description: 'Only returns player statistics that have changed in the last X minutes. You specify how many minutes in time to go back. Valid entries are:
<code>1</code>, <code>2</code> ... <code>all</code>.'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BoxScore'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/PlayerSeasonSplitStats/{season}/{split}:
get:
description: All players' split stats for the season. Split stats are available for left, right, and switch-handed pitchers and hitters.
operationId: mlb_v3_stats_player_season_split_stats
summary: Player Season Split Stats
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: season
in: path
description: 'Year of the season.
<br>Examples: <code>2017</code>, <code>2018</code>.'
required: true
schema:
type: string
- name: split
in: path
description: 'The desired split of stats. Currently, we support vs. Left/Right/Switch handed pitchers/hitters. Possible values are: <code>L</code>, <code>R</code> and <code>S</code>'
required: true
schema:
type: string
enum:
- L
- R
- S
default: L
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PlayerSeason'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/HitterVsPitcher/{hitterid}/{pitcherid}:
get:
description: Stat records for a given hitter and a given pitcher, called by PlayerId in both cases.
operationId: mlb_v3_stats_batter_vs__pitcher_stats
summary: Batter vs. Pitcher Stats
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: hitterid
in: path
description: 'Unique FantasyData Player ID.
Example:<code>10000031</code>.'
required: true
schema:
type: string
- name: pitcherid
in: path
description: 'Unique FantasyData Player ID.
Example:<code>10000618</code>.'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PlayerSeason'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/PlayerSeasonStatsSplitByTeam/{season}:
get:
description: All a given team's players' split stats for the season. Split stats are available for left, right, and switch-handed pitchers and hitters.
operationId: mlb_v3_stats_player_season_stats_split___by_team
summary: Player Season Stats Split - by Team
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: season
in: path
description: 'Year of the season.
<br>Examples: <code>2017</code>, <code>2018</code>.'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PlayerSeason'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/PlayerSeasonHomeStats/{season}:
get:
description: All players' stats for the season taken only from their home games.
operationId: mlb_v3_stats_player_season_stats___by_home
summary: Player Season Stats - by Home
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: season
in: path
description: 'Year of the season.
<br>Examples: <code>2017</code>, <code>2018</code>.'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PlayerSeason'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/PlayerSeasonAwayStats/{season}:
get:
description: All players' stats for the season taken only from their road games.
operationId: mlb_v3_stats_player_season_stats___by_away
summary: Player Season Stats - by Away
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: season
in: path
description: 'Year of the season.
<br>Examples: <code>2017</code>, <code>2018</code>.'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PlayerSeason'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/TeamHittersVsPitcher/{gameid}/{team}:
get:
description: For a given game, returns a team's hitting record versus the projected or confirmed starting pitcher for the game in question.
operationId: mlb_v3_stats_team_hitting_vs__starting_pitcher
summary: Team Hitting vs. Starting Pitcher
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: gameid
in: path
description: The GameID of an MLB game. GameIDs can be found in the Games API. Valid entries are <code>14620</code> or <code>16905</code>
required: true
schema:
type: string
- name: team
in: path
description: 'The abbreviation of the requested team.
<br>Examples: <code>SF</code>, <code>NYY</code>.'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PlayerSeason'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/PlayerGameStatsBySeason/{season}/{playerid}/{numberofgames}:
get:
description: Specify a season, a player, and number of games (either an integer or <code>all</code>) to see all of their box score logs. Refreshed after their most recent game is complete.
operationId: mlb_v3_stats_player_game_logs___by_season
summary: Player Game Logs - by Season
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: season
in: path
description: Season to get games from. Example <code>2019POST</code>, <code>2020</code>
required: true
schema:
type: string
- name: playerid
in: path
description: 'Unique SportsDataIO Player ID.
Example:<code>10001365</code>.'
required: true
schema:
type: string
- name: numberofgames
in: path
description: How many games to return. Example <code>all</code>, <code>10</code>, <code>25</code>
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PlayerGame'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/PlayerGameStatsByDateFinal/{date}:
get:
description: Returns the box score statistical record for all involved players across all teams' games on a given date after each game has concluded.
operationId: mlb_v3_stats_player_game_stats___by_date__final
summary: Player Game Stats - by Date [Final]
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: date
in: path
description: 'The date of the game(s).
<br>Examples: <code>2017-JUL-31</code>, <code>2017-SEP-01</code>.'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PlayerGame'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/BoxScoreFinal/{gameid}:
get:
description: Full statistical information for a specified game, down to the team and player stat level, delivered after the game is complete.
operationId: mlb_v3_stats_box_score__final
summary: Box Score [Final]
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: gameid
in: path
description: The GameID of an MLB game. GameIDs can be found in the Games API. Valid entries are <code>14620</code> or <code>16905</code>
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BoxScore'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/BoxScoresFinal/{date}:
get:
description: Full statistical information for a specified date for each game that took place, down to the team and player stat level, delivered after the game is complete.
operationId: mlb_v3_stats_box_scores___by_date__final
summary: Box Scores - by Date [Final]
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: date
in: path
description: 'The date of the game(s).
<br>Examples: <code>2017-JUL-31</code>, <code>2017-SEP-01</code>.'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BoxScore'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
/v3/mlb/stats/{format}/FantasyGameStatsByDate/{date}:
get:
description: Returns a simple list of fantasy points and stats for each player for a given date.
operationId: mlb_v3_stats_fantasy_points___by_date
summary: Fantasy Points - by Date
parameters:
- name: format
in: path
description: Desired response format. Valid entries are <code>JSON</code> or <code>XML</code>.
required: true
schema:
type: string
enum:
- JSON
- XML
default: JSON
- name: date
in: path
description: 'The date of the game(s).
<br>Examples: <code>2017-JUL-31</code>, <code>2017-SEP-01</code>.'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FantasyGame'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
tags:
- MLB v3 Stats
components:
schemas:
PlayerGame:
properties:
StatID:
type: integer
description: The unique ID of the stat
TeamID:
type:
- integer
- 'null'
description: The team's unique TeamID as assigned by SportsDataIO
PlayerID:
type:
- integer
- 'null'
description: 'The player''s unique PlayerID as assigned by SportsDataIO. Note: this ID will stay with the player throughout their MLB career'
SeasonType:
type:
- integer
- 'null'
description: The type of season that this record corresponds to (1=Regular Season; 2=Preseason; 3=Postseason; 4=Offseason; 5=AllStar)
Season:
type:
- integer
- 'null'
description: The MLB season of the game
Name:
type:
- string
- 'null'
description: Player's full name
Team:
type:
- string
- 'null'
description: The abbreviation [Key] of the team
Position:
type:
- string
- 'null'
description: 'The player''s position associated with the given game or season. Possible values: 1B, 2B, 3B, C, CF, DH, IF, LF, OF, P, PH, PR, RF, RP, SP, SS'
PositionCategory:
type:
- string
- 'null'
description: 'The player''s position category. Possible values: DH; IF; OF; P; PH; PR'
Started:
type:
- integer
- 'null'
description: 'Whether the player started in the game. Note: started = 1 and not starting = 0'
BattingOrder:
type:
- integer
- 'null'
description: Where the player batted in the lineup for the game (1;2;3; etc.)
FanDuelSalary:
type:
- integer
- 'null'
description: The player's salary for FanDuel daily fantasy contests.
DraftKingsSalary:
type:
- integer
- 'null'
description: The player's salary for DraftKings daily fantasy contests.
FantasyDataSalary:
type:
- integer
- 'null'
description: The player's salary as calculated by SportsDataIO (formerly known as FantasyData). Based on the same salary cap as DraftKings contests ($50,000)
YahooSalary:
type:
- integer
- 'null'
description: The player's salary for Yahoo daily fantasy contests
InjuryStatus:
type:
- string
- 'null'
description: 'The player''s current injury status; in the form of likelihood that player plays. Possible values: Probable; Questionable; Doubtful; Out'
InjuryBodyPart:
type:
- string
- 'null'
description: Indicates the player's injured body part. (e.g. ankle; knee; elbow; etc.)
InjuryStartDate:
type:
- string
- 'null'
description: The day that the injury started or first discovered.
InjuryNotes:
type:
- string
- 'null'
description: Brief description of the player's injury and expected availability
FanDuelPosition:
type:
- string
- 'null'
description: The player's eligible position in FanDuel's daily fantasy sports platform.
DraftKingsPosition:
type:
- string
- 'null'
description: The player's eligible position in DraftKings' daily fantasy sports platform.
YahooPosition:
type:
- string
- 'null'
description: The player's eligible position in Yahoo's daily fantasy sports platform
OpponentRank:
type:
- integer
- 'null'
description: The ranking of the player's opponent with regards to fantasy points allowed
OpponentPositionRank:
type:
- integer
- 'null'
description: The ranking of the player's opponent by position with regards to fantasy points allowed
GlobalTeamID:
type:
- integer
- 'null'
description: A globally unique ID for this team. This value is guaranteed to be unique across all sports/leagues
FantasyDraftSalary:
type:
- integer
- 'null'
description: The player's salary for Fantasy Draft daily fantasy contests.
FantasyDraftPosition:
type:
- string
- 'null'
description: The player's eligible position in Fantasy Drafts daily fantasy sports platform.
GameID:
type:
- integer
- 'null'
description: The unique ID of this game
OpponentID:
type:
- integer
- 'null'
description: The unique ID of the team's opponent
Opponent:
type:
- string
- 'null'
description: The name of the opponent
Day:
type:
- string
- 'null'
description: The day of the game
DateTime:
type:
- string
- 'null'
description: The date and time of the game
HomeOrAway:
type:
- string
- 'null'
description: Whether the team is home or away
IsGameOver:
type: boolean
description: Whether the game is over (true/false)
GlobalGameID:
type:
- integer
- 'null'
description: A globally unique ID for this game. This value is guaranteed to be unique across all sports/leagues.
GlobalOpponentID:
type:
- integer
- 'null'
description: A globally unique ID for this opponent. This value is guaranteed to be unique across all sports/leagues.
Updated:
type:
- string
- 'null'
description: The timestamp of when the record was last updated (US Eastern Time).
Games:
type:
- integer
- 'null'
description: The number of games played.
FantasyPoints:
type:
- number
- 'null'
description: Total fantasy points
AtBats:
type:
- number
- 'null'
description: At bats while hitting
Runs:
type:
- number
- 'null'
description: Total runs scored.
Hits:
type:
- number
- 'null'
description: Total hits
Singles:
type:
- number
- 'null'
description: Total singles
Doubles:
type:
- number
- 'null'
description: Total doubles
Triples:
type:
- number
- 'null'
description: Total triples
HomeRuns:
type:
- number
- 'null'
description: Total home runs
RunsBattedIn:
type:
- number
- 'null'
description: Total runs batted in
BattingAverage:
type:
- number
- 'null'
description: Total batting average
Outs:
type:
- number
- 'null'
description: Total outs
Strikeouts:
type:
- number
- 'null'
description: Total strikeouts
Walks:
type:
- number
- 'null'
description: Total walks
HitByPitch:
type:
- number
- 'null'
description: Total times hit by pitch
Sacrifices:
type:
- number
- 'null'
description: Total sacrifices
SacrificeFlies:
type:
- number
- 'null'
description: Total sacrifice flies
GroundIntoDoublePlay:
type:
- number
- 'null'
description: Total times grounded into double play
StolenBases:
type:
- number
- 'null'
description: Total stolen bases
CaughtStealing:
type:
- number
- 'null'
description: Total caught stealing
PitchesSeen:
type:
- number
- 'null'
description: Total pitches seen
OnBasePercentage:
type:
- number
- 'null'
description: Total on base percentage
SluggingPercentage:
type:
- number
- 'null'
description: Total slugging percentage
O
# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sportsdataio/refs/heads/main/openapi/sportsdataio-mlb-v3-stats-api-openapi.yml