openapi: 3.1.0
info:
  title: MLB MLB v3 Headshots MLB v3 Play-by-Play 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 Play-by-Play
paths:
  /v3/mlb/pbp/{format}/PlayByPlay/{gameid}:
    get:
      description: Each invididual play, its type and outcome, complete with player and team stats down to the play level, delivered live in real-time, called by game.
      operationId: mlb_v3_pbp_play_by_play__live___final
      summary: Play By Play [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/PlayByPlay'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
      tags:
      - MLB v3 Play-by-Play
  /v3/mlb/pbp/{format}/PlayByPlayDelta/{date}/{minutes}:
    get:
      description: This method returns all play-by-plays for a given season and week, but only returns plays 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_pbp_play_by_play_delta
      summary: Play By Play Delta
      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 plays 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/PlayByPlay'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
      tags:
      - MLB v3 Play-by-Play
  /v3/mlb/pbp/{format}/PlayByPlayFinal/{gameid}:
    get:
      description: Each invididual play, its type and outcome, complete with player and team stats down to the play level, delivered final (after the game ends), called by game.
      operationId: mlb_v3_pbp_play_by_play__final
      summary: Play By Play [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/PlayByPlay'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
      tags:
      - MLB v3 Play-by-Play
components:
  schemas:
    Inning:
      properties:
        InningID:
          type: integer
          description: The unique ID of this specific inning
        GameID:
          type: integer
          description: The unique ID of the game tied to this Inning
        InningNumber:
          type: integer
          description: The current inning number of the game
        AwayTeamRuns:
          type:
          - integer
          - 'null'
          description: Number of runs scored by the away team in the specific inning
        HomeTeamRuns:
          type:
          - integer
          - 'null'
          description: Number of runs scored by the home team in the specific inning
    Game:
      properties:
        GameID:
          type: integer
          description: The unique ID of this game
        Season:
          type: integer
          description: The MLB season of the game
        SeasonType:
          type: integer
          description: The type of season stage the game belongs to, e.g. Regular season, Post-season. For a description of possible values and how they work, see <a href="https://support.sportsdata.io/hc/en-us/articles/15196612633623-Process-Guide-Season-Types-and-Parameters" target="_blank">here.
        Status:
          type:
          - string
          - 'null'
          description: The status of the game. For a description of possible values, see <a href="https://support.sportsdata.io/hc/en-us/articles/14287629964567-Process-Guide-Game-Status" target="_blank">here.</a> For how suspended and postponed games are handled specifically, see <a href="https://support.sportsdata.io/hc/en-us/articles/4404845580567-Postponed-and-Rescheduled-Games" target="_blank">here</a>.
        Day:
          type:
          - string
          - 'null'
          description: The date of the game
        DateTime:
          type:
          - string
          - 'null'
          description: The date and time of the game (in US Eastern Time)
        AwayTeam:
          type:
          - string
          - 'null'
          description: The abbreviation [Key] of the away team
        HomeTeam:
          type:
          - string
          - 'null'
          description: The abbreviation [Key] of the home team
        AwayTeamID:
          type: integer
          description: The unique TeamID of the away team
        HomeTeamID:
          type: integer
          description: The unique ID of the home team
        RescheduledGameID:
          type:
          - integer
          - 'null'
          description: The GameID of the game that was rescheduled from this game. This only pertains to postponed games that require rescheduling.
        StadiumID:
          type:
          - integer
          - 'null'
          description: The unique ID of the stadium
        Channel:
          type:
          - string
          - 'null'
          description: The television station broadcasting the game
        Inning:
          type:
          - integer
          - 'null'
          description: 'The inning that the game is currently in, or the inning in which the game ended. Possible values include: NULL, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, etc)'
        InningHalf:
          type:
          - string
          - 'null'
          description: 'The inning half that the game is currently in; or the inning half in which the game ended (possible values: T; B; E: M: NULL)'
        AwayTeamRuns:
          type:
          - integer
          - 'null'
          description: Number of runs scored by the away team in the game
        HomeTeamRuns:
          type:
          - integer
          - 'null'
          description: Number of runs scored by the home team in the game
        AwayTeamHits:
          type:
          - integer
          - 'null'
          description: Total hits by the away team in the game
        HomeTeamHits:
          type:
          - integer
          - 'null'
          description: Total hits by the home team in the game
        AwayTeamErrors:
          type:
          - integer
          - 'null'
          description: Total errors committed by the away team in the game
        HomeTeamErrors:
          type:
          - integer
          - 'null'
          description: Total errors committed by the home team in the game
        WinningPitcherID:
          type:
          - integer
          - 'null'
          description: The PlayerID of the pitcher who recorded the win in the game
        LosingPitcherID:
          type:
          - integer
          - 'null'
          description: The PlayerID of the losing pitcher in the game
        SavingPitcherID:
          type:
          - integer
          - 'null'
          description: The PlayerID of the pitcher who recorded the save in the game
        Attendance:
          type:
          - integer
          - 'null'
          description: Total number of people who attended the game
        AwayTeamProbablePitcherID:
          type:
          - integer
          - 'null'
          description: The PlayerID of the away team's probable pitcher
        HomeTeamProbablePitcherID:
          type:
          - integer
          - 'null'
          description: The PlayerID of the home team's probable pitcher
        Outs:
          type:
          - integer
          - 'null'
          description: The number of outs recorded in the current inning of the game
        Balls:
          type:
          - integer
          - 'null'
          description: The number of balls thrown for the current at bat
        Strikes:
          type:
          - integer
          - 'null'
          description: The number of strikes thrown for the current at bat
        CurrentPitcherID:
          type:
          - integer
          - 'null'
          description: The PlayerID of the current pitcher
        CurrentHitterID:
          type:
          - integer
          - 'null'
          description: The PlayerID of the current hitter
        AwayTeamStartingPitcherID:
          type:
          - integer
          - 'null'
          description: The PlayerID of the away team's starting pitcher
        HomeTeamStartingPitcherID:
          type:
          - integer
          - 'null'
          description: The PlayerID of the home team starting pitcher in the game
        CurrentPitchingTeamID:
          type:
          - integer
          - 'null'
          description: The TeamID of the current pitcher's team
        CurrentHittingTeamID:
          type:
          - integer
          - 'null'
          description: The TeamID of the current hitter's team
        PointSpread:
          type:
          - number
          - 'null'
          description: 'The consensus Run Line at game start from the perspective of the HomeTeam (in the Game table, the PointSpread field''s negative numbers indicate the HomeTeam is favored; positive numbers indicate the AwayTeam is favored. Note that this rule does not hold in betting-related tables, where the run line is contingent on the bet line). Note: In MLB, Point Spread may also be referred to as Run Line'
        OverUnder:
          type:
          - number
          - 'null'
          description: The oddsmaker total points line at game start
        AwayTeamMoneyLine:
          type:
          - integer
          - 'null'
          description: Moneyline from the perspective of the away team
        HomeTeamMoneyLine:
          type:
          - integer
          - 'null'
          description: Moneyline from the perspective of the home team
        ForecastTempLow:
          type:
          - integer
          - 'null'
          description: The forecasted low temperature on game day at this venue (in Fahrenheit)
        ForecastTempHigh:
          type:
          - integer
          - 'null'
          description: The forecasted high temperature on game day at this venue (in Fahrenheit)
        ForecastDescription:
          type:
          - string
          - 'null'
          description: 'The description of the weather forecast. Posible values include: Broken Clouds, Clear Sky, Few Clouds, Heavy Intensity Rain, Light Rain, Moderate Rain, Mostly Cloudy, Mostly Sunny, Overcast Clouds, Partly Cloudy, Scattered Clouds, Showers, Thunderstorms'
        ForecastWindChill:
          type:
          - integer
          - 'null'
          description: The forecasted wind chill on game day at this venue.
        ForecastWindSpeed:
          type:
          - integer
          - 'null'
          description: The forecasted wind speed on game day at this venue.
        ForecastWindDirection:
          type:
          - integer
          - 'null'
          description: The wind direction isn't baseball specific.  It refers to the direction that the wind is coming from.  90 would be wind coming from the east.  180 is wind from the south.  270 is a wind from the west ... and so on.
        RescheduledFromGameID:
          type:
          - integer
          - 'null'
          description: The GameID of the originally scheduled, postponed game, that this game was rescheduled from. This only pertains to games that are scheduled as "make up" games.
        RunnerOnFirst:
          type:
          - boolean
          - 'null'
          description: Indicates if there is a runner on first base
        RunnerOnSecond:
          type:
          - boolean
          - 'null'
          description: Indicates if there is a runner on second base
        RunnerOnThird:
          type:
          - boolean
          - 'null'
          description: Indicates if there is a runner on third base
        AwayTeamStartingPitcher:
          type:
          - string
          - 'null'
          description: The first and last name of the away team's starting pitcher for the game
        HomeTeamStartingPitcher:
          type:
          - string
          - 'null'
          description: The first and last name of the home team starting pitcher for the game
        CurrentPitcher:
          type:
          - string
          - 'null'
          description: Indicates the current pitcher's name
        CurrentHitter:
          type:
          - string
          - 'null'
          description: Indicates the current hitter's name
        WinningPitcher:
          type:
          - string
          - 'null'
          description: The name of the pitcher who recorded the win in the game
        LosingPitcher:
          type:
          - string
          - 'null'
          description: The first and last name of the losing pitcher in the game
        SavingPitcher:
          type:
          - string
          - 'null'
          description: The name of the pitcher who recorded the save in the game
        DueUpHitterID1:
          type:
          - integer
          - 'null'
          description: The PlayerID of the hitter due up first from the current hitter
        DueUpHitterID2:
          type:
          - integer
          - 'null'
          description: The PlayerID of the hitter due up second from the current hitter
        DueUpHitterID3:
          type:
          - integer
          - 'null'
          description: The PlayerID of the hitter due up third from the current hitter
        GlobalGameID:
          type: integer
          description: A globally unique ID for this game. This value is guaranteed to be unique across all sports/leagues
        GlobalAwayTeamID:
          type: integer
          description: A globally unique ID for the away team. This value is guaranteed to be unique across all sports/leagues
        GlobalHomeTeamID:
          type: integer
          description: A globally unique ID for the home team. This value is guaranteed to be unique across all sports/leagues.
        PointSpreadAwayTeamMoneyLine:
          type:
          - integer
          - 'null'
          description: The moneyline payout odds when betting on the away team with the run line
        PointSpreadHomeTeamMoneyLine:
          type:
          - integer
          - 'null'
          description: The moneyline payout odds when betting on the home team with the run line
        LastPlay:
          type:
          - string
          - 'null'
          description: The description of the most recent play/event of the game. This is for display purposes and does not include corresponding data points.
        IsClosed:
          type: boolean
          description: 'Indicates whether the game is over and the final score has been verified and closed out. Note: it is recommend for bet resulting to use IsClosed = True rather than simply Final game status'
        Updated:
          type:
          - string
          - 'null'
          description: The date and time of the late update made to this record (in US Eastern Time)
        Innings:
          type: array
          items:
            $ref: '#/components/schemas/Inning'
          description: The inning details associated with the game
        GameEndDateTime:
          type:
          - string
          - 'null'
          description: The date and time that the game ended in US Eastern Time
        HomeRotationNumber:
          type:
          - integer
          - 'null'
          description: Rotation number of home team for this game
        AwayRotationNumber:
          type:
          - integer
          - 'null'
          description: Rotation number of away team for this game
        NeutralVenue:
          type:
          - boolean
          - 'null'
          description: 'Indicates whether this game is played in a neutral venue. Note: Neutral = True, not neutral = False'
        InningDescription:
          type:
          - string
          - 'null'
          description: 'The current status of the inning for display purposes (possible values: Top 2, Mid 2, Bot 2, End 2, etc)'
        OverPayout:
          type:
          - integer
          - 'null'
          description: The sportsbook's payout for the over
        UnderPayout:
          type:
          - integer
          - 'null'
          description: The sportsbook's payout for the under
        SeriesInfo:
          $ref: '#/components/schemas/Series'
          description: Contains relevant series data for postseason series only - HomeTeamWins; AwayTeamWins; GameNumber; and MaxLength
        DateTimeUTC:
          type:
          - string
          - 'null'
          description: The date and time of the game in UTC
        HomeTeamOpener:
          type:
          - boolean
          - 'null'
          description: 'Indicates whether the home team will use an opener as the starting pitcher. NOTE: An opener is a pitcher (typically a relief pitcher) that is only scheduled to pitch the first 1-3 innings of the game'
        AwayTeamOpener:
          type:
          - boolean
          - 'null'
          description: 'Indicates whether the away team will use an opener as the starting pitcher.. NOTE: An opener is a pitcher (typically a relief pitcher) that is only scheduled to pitch the first 1-3 innings of the game'
        SuspensionResumeDay:
          type:
          - string
          - 'null'
          description: The date a game that was suspended in play will be resumed for play. Useful for tracking when a Suspended game will return to an InProgress status.
        SuspensionResumeDateTime:
          type:
          - string
          - 'null'
          description: The date and start-time that the suspended in play game will be resumed for play. Useful for tracking when a Suspended game will return to an InProgress status.
    PlayByPlay:
      properties:
        Game:
          $ref: '#/components/schemas/Game'
          description: The details of the game associated with this play-by-play
        Plays:
          type: array
          items:
            $ref: '#/components/schemas/Play'
          description: The details of the plays associated with this play-by-play
    Play:
      properties:
        PlayID:
          type: integer
          description: The unique ID of the play assigned by SportsDataIO
        InningID:
          type: integer
          description: The unique ID associated with this specific inning in which the play occurred
        InningNumber:
          type:
          - integer
          - 'null'
          description: The inning number in which the particular play occurred
        InningHalf:
          type:
          - string
          - 'null'
          description: 'The inning half that the game is currently in; or the inning half in which the game ended (possible values: T; B; E: M: NULL)'
        PlayNumber:
          type:
          - integer
          - 'null'
          description: The order in which plays occurred in a game
        InningBatterNumber:
          type:
          - integer
          - 'null'
          description: The batter number in the inning where the play occurred.
        AwayTeamRuns:
          type:
          - integer
          - 'null'
          description: Number of runs scored by the away team on this specific play
        HomeTeamRuns:
          type:
          - integer
          - 'null'
          description: Number of runs scored by the home team on this specific play
        HitterID:
          type:
          - integer
          - 'null'
          description: The unique PlayerID of the hitter involved with the play
        PitcherID:
          type:
          - integer
          - 'null'
          description: The PlayerID of the pitcher involved in the play
        HitterTeamID:
          type:
          - integer
          - 'null'
          description: The TeamID of the hitter's team.
        PitcherTeamID:
          type:
          - integer
          - 'null'
          description: The ID of the pitcher's team
        HitterName:
          type:
          - string
          - 'null'
          description: The first and last name of the hitter involved in the play
        PitcherName:
          type:
          - string
          - 'null'
          description: The full name of the pitcher involved in the play
        PitcherThrowHand:
          type:
          - string
          - 'null'
          description: The throwing hand of the pitcher in which the play occurred. (right or left)
        HitterBatHand:
          type:
          - string
          - 'null'
          description: The batter's handedness for which the play occurred. (R; L; S)
        HitterPosition:
          type:
          - string
          - 'null'
          description: The position of the player in which the play occrred. (e.g. P;C;1B; SS; OF)
        Outs:
          type:
          - integer
          - 'null'
          description: The number of outs in which the play occurred
        Balls:
          type:
          - integer
          - 'null'
          description: The number of balls in the count in which the play occurred
        Strikes:
          type:
          - integer
          - 'null'
          description: The number of strikes in the count in which the play occurred
        PitchNumberThisAtBat:
          type:
          - integer
          - 'null'
          description: The number of pitches in the at bat in which the play occurred
        Result:
          type:
          - string
          - 'null'
          description: 'The result of the play. Possible values include: Batter''s Interference, Bunted into Double Play, Catcher''s Interference, Double, Error, Fielder''s Choice, Fly into Double Play, Fly Out, Foul Out, Fouled into Double Play, Ground into Double Play, Ground Out, Hit by Pitch, Home Run, Infield Fly Out, Intentional Walk, Line into Double Play, Lineout, Pop Out, Popped into Double Play, Sacrifice, Sacrifice Fly, Single, Strikeout Bunting, Strikeout Looking, Strikeout Swinging, Triple, Triple Play, Walk, Stolen Base, Caught Stealing, Passed Ball, Wild Pitch, Pick Off, Balk, Error, Fielders Indifference'
        NumberOfOutsOnPlay:
          type:
          - integer
          - 'null'
          description: The number of outs recorded on the play
        RunsBattedIn:
          type:
          - integer
          - 'null'
          description: The number of runs batted in on the play
        AtBat:
          type:
          - boolean
          - 'null'
          description: Whether this plate appearance resulted in an at bat
        Strikeout:
          type:
          - boolean
          - 'null'
          description: Whether the play resulted with a strikeout (returns true/false)
        Walk:
          type:
          - boolean
          - 'null'
          description: Indicates whether the play resulted in a walk for the hitter (returns true/false)
        Hit:
          type:
          - boolean
          - 'null'
          description: Whether this play resulted in a hit (true/false)
        Out:
          type:
          - boolean
          - 'null'
          description: Whether this play resutled in an out (true/false)
        Sacrifice:
          type:
          - boolean
          - 'null'
          description: Whether the play resulted in a sacrifice (returns true/false)
        Error:
          type:
          - boolean
          - 'null'
          description: Whether this play resulted in an error (true/false)
        Updated:
          type:
          - string
          - 'null'
          description: The database generated timestamp of when this record was last updated (in US Eastern Time)
        Description:
          type:
          - string
          - 'null'
          description: The description of the play for display purposes
        Pitches:
          type: array
          items:
            $ref: '#/components/schemas/Pitch'
          description: The details of the pitches associated with this play
        Runner1ID:
          type:
          - integer
          - 'null'
          description: The PlayerID of the player on first as a result of the play (post-play)
        Runner2ID:
          type:
          - integer
          - 'null'
          description: The PlayerID of the player on second as a result of the play (post-play)
        Runner3ID:
          type:
          - integer
          - 'null'
          description: The PlayerID of the player on third as a result of the play (post-play)
    Series:
      properties:
        HomeTeamWins:
          type: integer
          description: 'Number of wins by the home team on in the series. Note: this is for postseason series only.'
        AwayTeamWins:
          type: integer
          description: 'Number of wins by the away team in the series. Note: This is for postseason series only.'
        GameNumber:
          type: integer
          description: 'Game number in series. Note: this applies to postseason series only.'
        MaxLength:
          type: integer
          description: 'Maximum number of games in the series. Note: this is for postseason series only.'
    Unauthorized:
      properties:
        HttpStatusCode:
          type: integer
        Code:
          type: integer
        Description:
          type: string
        Help:
          type: string
    Pitch:
      properties:
        PitchID:
          type: integer
          description: The unique ID of the pitch
        PlayID:
          type: integer
          description: The unique ID of the play assigned by SportsDataIO
        PitchNumberThisAtBat:
          type:
          - integer
          - 'null'
          description: The number of pitches in the at bat in which the pitch occurred.
        PitcherID:
          type:
          - integer
          - 'null'
          description: The PlayerID of the pitcher who threw the pitch
        HitterID:
          type:
          - integer
          - 'null'
          description: The unique PlayerID of the hitter who represents the play
        Outs:
          type:
          - integer
          - 'null'
          description: The number of outs when the pitch occurred
        BallsBeforePitch:
          type:
          - integer
          - 'null'
          description: The number of balls the pitcher has thrown before the current pitch
        StrikesBeforePitch:
          type:
          - integer
          - 'null'
          description: The number of strikes the pitcher has thrown before the current pitch
        Strike:
          type:
          - boolean
          - 'null'
          description: Whether the pitch was a strike (true/false)
        Ball:
          type:
          - boolean
          - 'null'
          description: Whether the pitch was a ball (true/false)
        Foul:
          type:
          - boolean
          - 'null'
          description: Whether the pitch was hit foul (true/false)
        Swinging:
          type:
          - boolean
          - 'null'
          description: Whether the hitter struck out swinging (true/false)
        Looking:
          type:
          - boolean
          - 'null'
          description: Whether or not the hitter struck out looking (returns true/false)
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
    apiKeyQuery:
      type: apiKey
      name: key
      in: query