--- title: "Play By Play Simulation" method: GET path: "/v3/nfl/pbp/{format}/SimulatedPlayByPlay/{numberofplays}" tags: ["NFL v3 Play-by-Play"] --- # Play By Play Simulation `GET /v3/nfl/pbp/{format}/SimulatedPlayByPlay/{numberofplays}` ## Request - Base URL: `https://api.sportsdata.io` - URL: `https://api.sportsdata.io/v3/nfl/pbp/{format}/SimulatedPlayByPlay/{numberofplays}` - Auth: one of: - API key in header `Ocp-Apim-Subscription-Key` - API key in query parameter `key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Gets simulated live play-by-play of NFL games, covering the Conference Championship games on January 21, 2018. ## Path parameters - `format` 'JSON' | 'XML', required - `numberofplays` string, required ## Response `200` Success - PlayByPlay[] - `Score` Score - `GameKey` string, nullable: A 9 digit unique code identifying the game that this record corresponds to. The GameID is composed of Season; SeasonType; Week and HomeTeam. Note: This value will be NULL for bye weeks - `SeasonType` integer: The type of season that this game corresponds to (1=Regular Season, 2=Preseason, 3=Postseason, 4=Offseason, 5=All-Star). - `Season` integer: The NFL season of the game - `Week` integer: The NFL week of the game (regular season: 1 to 18; preseason: 0 to 4; postseason: 1 to 4). Note: seasons after 2021 will have only 3 preseason weeks - `Date` string, nullable: The date and time of the game (in US Eastern Time) - `AwayTeam` string, nullable: The abbreviation [Key} of the away team - `HomeTeam` string, nullable: The abbreviation [Key] of the home team - `AwayScore` integer, nullable: The final score of the Away Team - `HomeScore` integer, nullable: The final score of the Home Team - `Channel` string, nullable: The television station broadcasting the game - `PointSpread` number, nullable: The oddsmaker point spread at game start from the perspective of the team (negative numbers indicate the HomeTeam is favored; positive numbers indicate the AwayTeam is favored) - `OverUnder` number, nullable: The total points line (over/under) at game start - `Quarter` string, nullable: The current quarter of the game (1, 2, 3, 4, HALF, OT, F, F/OT or NULL if game has not yet started) - `TimeRemaining` string, nullable: The amount of time remaining in the current quarter (e.g. 11:23; 5:34; NULL if game is not in progress or at halftime) - `Possession` string, nullable: The team that currently has possession of the ball (Ex. PHI; NE; NULL if game is not in progress or at halftime) - `Down` integer, nullable: The current down in the game (1, 2, 3, 4 or NULL) - `Distance` string, nullable: The yards to go for a first down (this can be any positive number or "Goal") - `YardLine` integer, nullable: the yard line of the ball's current position on the field as of the most recently completed play - `YardLineTerritory` string, nullable: The team's side of the field that the ball is on when the play occurred - `RedZone` string, nullable: The team abbreviation [Key] that currently has the ball in the opponent's red zone (Ex: "SF"; "BAL" or NULL) - `AwayScoreQuarter1` integer, nullable: Points scored by the away team in Quarter 1 - `AwayScoreQuarter2` integer, nullable: Points scored by the away team in Quarter 2 - `AwayScoreQuarter3` integer, nullable: Points scored by the away team in Quarter 3 - `AwayScoreQuarter4` integer, nullable: Points scored by the away team in Quarter 4 - `AwayScoreOvertime` integer, nullable: Points scored by the away team in overtime - `HomeScoreQuarter1` integer, nullable: Points scored by the home team in Quarter 1 - `HomeScoreQuarter2` integer, nullable: Points scored by the home team in Quarter 2 - `HomeScoreQuarter3` integer, nullable: Points scored by the home team in Quarter 3 - `HomeScoreQuarter4` integer, nullable: Points scored by the home team in Quarter 4 - `HomeScoreOvertime` integer, nullable: Points scored by the home team in overtime - `HasStarted` boolean: Whether the game has started (true/false) - `IsInProgress` boolean: Whether the game is currently in progress (true/false) - `IsOver` boolean: Whether the game is over (true/false) - `Has1stQuarterStarted` boolean: Whether the 1st quarter has started - `Has2ndQuarterStarted` boolean: Whether the 2nd quarter has started - `Has3rdQuarterStarted` boolean: Whether the 3rd quarter has started - `Has4thQuarterStarted` boolean: Whether the 4th quarter has started - `IsOvertime` boolean: Whether this game went into overtime - `DownAndDistance` string, nullable: The description of the down and distance for display purposes - `QuarterDescription` string, nullable: Description of the current quarter for display purposes - `StadiumID` integer, nullable: The unique ID of the team's current home stadium - `LastUpdated` string, nullable: The date and time that this game was last updated (in US Eastern Time) - `GeoLat` number, nullable: The geographic latitude coordinate of the venue where the game is taking place - `GeoLong` number, nullable: The geographic longitude coordinate of the venue where the game is taking place - `ForecastTempLow` integer, nullable: The forecasted low temperature on game day at this venue (Fahrenheit) - `ForecastTempHigh` integer, nullable: The forecasted high temperature on game day at this venue (Fahrenheit) - `ForecastDescription` string, nullable: The forecast description on game day at this venue. - `ForecastWindChill` integer, nullable: The forecasted wind chill on game day at this venue. - `ForecastWindSpeed` integer, nullable: The forecasted wind speed on game day at this venue. - `AwayTeamMoneyLine` integer, nullable: The sportsbook's moneyline for the away team - `HomeTeamMoneyLine` integer, nullable: The sportsbook's moneyline for the home team - `Canceled` boolean, nullable: Indicates whether the game was canceled - `Closed` boolean, nullable: 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 - `LastPlay` string, nullable: The description of the most recent play/event of the game. Note: This is for display purposes and does not include corresponding data points - `Day` string, nullable: The date of the game (in US Eastern Time) - `DateTime` string, nullable: The date and time of the game (in US Eastern Time) - `AwayTeamID` integer, nullable: The unique ID of the away team - `HomeTeamID` integer, nullable: The unique ID of the home team - `GlobalGameID` integer, nullable: A globally unique ID for this game. This value is guaranteed to be unique across all sports/leagues - `GlobalAwayTeamID` integer, nullable: A globally unique ID for the away team. This value is guaranteed to be unique across all sports/leagues - `GlobalHomeTeamID` integer, nullable: A globally unique ID for the home team. This value is guaranteed to be unique across all sports/leagues - `PointSpreadAwayTeamMoneyLine` integer, nullable: The payout on the away team's spread - `PointSpreadHomeTeamMoneyLine` integer, nullable: The payout on the home team's spread - `ScoreID` integer: Unique ID of the Score/Game - `StadiumDetails` Stadium - `StadiumID` integer: The unique ID of the stadium - `Name` string, nullable: The full name of the stadium - `City` string, nullable: The city where the stadium is located - `State` string, nullable: The city where the venue is located - `Country` string, nullable: The 3-digit country code where the stadium is located - `Capacity` integer, nullable: The estimated seating capacity of the stadium - `PlayingSurface` string, nullable: The playing surface of the stadium (Grass, Artificial or Dome) - `GeoLat` number, nullable: The geographic latitude coordinate of this venue - `GeoLong` number, nullable: The geographic longitude coordinate of this venue. - `Type` string, nullable: The type of the stadium (possible values: Outdoor, Dome, RetractableDome) - `Status` string, nullable: The status of the game. For a description of possible values, see here. For how suspended and postponed games are handled specifically, see here. - `GameEndDateTime` string, nullable: The date and time of when the game officially ended. Note: This field is populated after the game and score are finalized - `HomeRotationNumber` integer, nullable: Rotation number of home team in this game - `AwayRotationNumber` integer, nullable: Rotation number of away team in this game - `NeutralVenue` boolean, nullable: Indicates whether this game is played in a neutral venue - `RefereeID` integer, nullable: The unique ID of the head referee - `OverPayout` integer, nullable: The sportsbook's payout for over the total points line - `UnderPayout` integer, nullable: The sportsbook's payout for the under - `HomeTimeouts` integer, nullable: The number of timeouts remaining for the Home Team - `AwayTimeouts` integer, nullable: The number of timeouts remaining for the Away Team - `DateTimeUTC` string, nullable: The date and time of the game (in UTC) - `Attendance` integer: The total attendance for the game - `IsClosed` boolean, nullable: Indicates whether the game is over and the final score has been verified and closed out. - `Deleted` boolean: Indicates whether the game or event has been soft deleted and never existed on the real-life schedule. Deleted records have their Status set to Canceled and are retained for reference only. - `Quarters` Quarter[]: The details of the quarters (including overtime periods) for the given game - `QuarterID` integer: The unique ID of the quarter - `ScoreID` integer: The unique ID of the score this quarter belongs to - `Number` integer: The Number (Order) of the Quarter in the scope of the Game. - `Name` string, nullable: The Name of the Quarter (possible values: 1, 2, 3, 4, OT, OT2, OT3, etc) - `Description` string, nullable: The long description of the quarter - `AwayTeamScore` integer, nullable: The total points scored by the away team in this Quarter. - `HomeTeamScore` integer, nullable: The total points scored by the home team in this Quarter. - `Updated` string, nullable: The database generated timestamp of when this Quarter was last updated (in US Eastern time) - `Created` string, nullable: The database generated timestamp of when this Quarter was first created (in US Eastern Time) - `Plays` Play[]: The list of plays for the given game - `PlayID` integer: The unique ID of the play - `QuarterID` integer: The unique ID of the quarter in which the play occurred - `QuarterName` string, nullable: The name of the quarter in which the play occurred - `Sequence` integer, nullable: The order in which this play and/or event happened over the course of the game - `TimeRemainingMinutes` integer, nullable: The minutes of the time remaining in the Quarter, when this play occurred. - `TimeRemainingSeconds` integer, nullable: The seconds of the time remaining in the Quarter, when this play occurred. - `PlayTime` string, nullable: The estimated timestamp of when this Play occurred on the field. Please note that we do not have scouts at the venue; so this is an estimate based on our TV feed and estimated TV feed delay - `Updated` string, nullable: The database generated timestamp of when this Play was last updated (in US Eastern time) - `Created` string, nullable: The database generated timestamp of when this Play was first created (in US Eastern Time) - `Team` string, nullable: The abbreviation [Key] of the team that completed the play - `Opponent` string, nullable: The abbreviation [Key] of the opponent of the team that this play relates to - `Down` integer, nullable: The Down when this Play occurred. - `Distance` integer, nullable: The yards to go for a first down. Note: this can be any positive number or "Goal" - `YardLine` integer, nullable: the yard line of the ball's current position on the field when this play occurred - `YardLineTerritory` string, nullable: The team's side of the field that the ball is on when the play occurred - `YardsToEndZone` integer, nullable: The number of yards to go to reach the end zone at the start of the play - `Type` string, nullable: The Type of Play that occurred (possible values: Rush, PassCompleted, PassIncomplete, PassIntercepted, TwoPointConversion, Punt, Kickoff, FieldGoal, ExtraPoint, Fumble, Penalty, Sack, Timeout, Period) - `YardsGained` integer, nullable: The number of yards gained or lost on the play - `Description` string, nullable: The description of the Play. - `IsScoringPlay` boolean, nullable: Indicates whether this Play was a scoring play. - `ScoringPlay` ScoringPlay - `GameKey` string, nullable: A 9 digit unique code identifying the game that this record corresponds to. The GameID is composed of Season; SeasonType; Week and HomeTeam. Note: This value will be NULL for bye weeks - `SeasonType` integer: The type of season that this game corresponds to (1=Regular Season; 2=Preseason; 3=Postseason; 4=Offseason; 5=All-Star) - `ScoringPlayID` integer: Unique ID of the scoring play - `Season` integer: The NFL season of the game - `Week` integer: The NFL week of the game (regular season: 1 to 18; preseason: 0 to 4; postseason: 1 to 4). Note: seasons after 2021 will have only 3 preseason weeks - `AwayTeam` string, nullable: The abbreviation [Key} of the away team - `HomeTeam` string, nullable: The abbreviation [Key] of the home team - `Date` string, nullable: The date and time of the game (in US Eastern Time) - `Sequence` integer, nullable: The order in which the scoring play happened - `Team` string, nullable: The abbreviation [Key] of the team - `Quarter` string, nullable: The quarter of the scoring play (1; 2; 3; 4; OT) - `TimeRemaining` string, nullable: The amount of time remaining in the current quarter when the scoring play occurred (e.g. 11:23; 5:34; NULL if game is not in progress or at halftime) - `PlayDescription` string, nullable: The detailed description of the play for display purposes - `AwayScore` integer, nullable: The away team's score as a result of the scoring play (includes point after) - `HomeScore` integer, nullable: The home team's score as a result of the scoring play (includes point after) - `ScoreID` integer: Unique ID of the score/game - `PlayStats` PlayStat[]: The list of player stats accumulated during the play - `PlayStatID` integer: The unique ID of the PlayStat on the play - `PlayID` integer: The unique ID of the play in which the PlayStat occurred - `Sequence` integer: The order in which the play stat was registered to the Play. - `PlayerID` integer: The unique PlayerID of the player whose stats are tied to the play. Note: this ID will stay with the player throughout their entire career - `Name` string, nullable: The Name of the Player whose stats this represents. - `Team` string, nullable: The abbreviation [Key] of the team the player belongs to - `Opponent` string, nullable: The abbreviation [Key] of the opponent team of the player who recorded the stat - `HomeOrAway` string, nullable: Whether the Player was Home or Away (possible values: HOME, AWAY) - `Direction` string, nullable: The Direction this Play occurred (possible values: Left, Middle, Right) - `Updated` string, nullable: The database generated timestamp of when this PlayStat was last updated (in US Eastern time) - `Created` string, nullable: The database generated timestamp of when this PlayStat was first created (in US Eastern Time) - `PassingAttempts` integer, nullable: Total passes thrown by the player on the play - `PassingCompletions` integer, nullable: Total passing completions by the player on the play - `PassingYards` integer, nullable: Total passing yards by the player on the play - `PassingTouchdowns` integer, nullable: Total passing touchdowns thrown by the player on the play - `PassingInterceptions` integer, nullable: Total interceptions thrown by the player on the play - `PassingSacks` integer, nullable: The total number of times the player was sacked on the play - `PassingSackYards` integer, nullable: Total yards lost by the player as a result of being sacked on the play - `RushingAttempts` integer, nullable: Rushing attempts by the player on the play. Note: this field is expected to be 1 or 0 - `RushingYards` integer, nullable: Total rushing yards by the player on the play - `RushingTouchdowns` integer, nullable: Total rushing touchdowns by the player on the play. Note: this field is expected to be 1 or 0 - `ReceivingTargets` integer, nullable: Total receiving targets by the player on the play. Note: this field is expected to be 1 or 0 - `Receptions` integer, nullable: Total receptions by the player on the play. Note: this field is expected to be 1 or 0 - `ReceivingYards` integer, nullable: Total receiving yards by the player on the play - `ReceivingTouchdowns` integer, nullable: Total receiving touchdowns by the player on the play. Note: this field is expected to be 1 or 0 - `Fumbles` integer, nullable: Times the player fumbled on the play - `FumblesLost` integer, nullable: Fumbles lost by the player on the play - `TwoPointConversionAttempts` integer, nullable: Total two point conversion attempts by the player on the play. Note: this field is expected to be 1 or 0 - `TwoPointConversionPasses` integer, nullable: Total successful two point conversion passes by the player on the play. Note: this field is expected to be 1 or 0 - `TwoPointConversionRuns` integer, nullable: Total two point conversion rushes by the player on the play. Note: this field is expected to be 1 or 0 - `TwoPointConversionReceptions` integer, nullable: Total successful two point conversion receptions by the player on the play. Note: this field is expected to be 1 or 0 - `TwoPointConversionReturns` integer, nullable: Total successful two point conversion returns by the player on the play. Note: this field is expected to be 1 or 0 - `SoloTackles` integer, nullable: Total defensive solo (unassisted) tackles by the player on the play. Note: this field is expected to be 1 or 0 - `AssistedTackles` integer, nullable: Total defensive assisted tackles by the player on the play - `TacklesForLoss` integer, nullable: Tackles for loss of yards by the player on the play. Note: These are tackles behind the line of scrimmage for loss of yards (including sacks) - also this field is expected to be 1 or 0 - `Sacks` number, nullable: Total Sacks by this player on the play. Note: this field is expected to be 1 or 0 - `SackYards` number, nullable: Total sack yards by this player on the play - `PassesDefended` integer, nullable: Total passes defended by the player on the play - `Safeties` integer, nullable: Total defensive safeties by the player on the play. Note: this field is expected to be 1 or 0 - `FumblesForced` integer, nullable: Fumbles forced by the player on the play - `FumblesRecovered` integer, nullable: Defensive fumbles recovered by the player on the play - `FumbleReturnYards` integer, nullable: Fumble recoveries returned yards by the player on the play - `FumbleReturnTouchdowns` integer, nullable: Fumble recoveries returned for touchdowns by the player on the play - `Interceptions` integer, nullable: Interceptions by the player on the play - `InterceptionReturnYards` integer, nullable: Interception return yards by the player on the play - `InterceptionReturnTouchdowns` integer, nullable: Interception return touchdowns by the player on the play - `PuntReturns` integer, nullable: Total punts returned by the player on the play - `PuntReturnYards` integer, nullable: Total punt return yards by the player on the play - `PuntReturnTouchdowns` integer, nullable: Punt returns for touchdowns by the player on the play. Note: this field is expected to be 1 or 0 - `KickReturns` integer, nullable: Kicks returned by the player on the play - `KickReturnYards` integer, nullable: Kicks return yards by the player on the play - `KickReturnTouchdowns` integer, nullable: Kicks returned for touchdowns by the player on the play - `BlockedKicks` integer, nullable: Blocked kicks by the player on the play. Note: BlockedKicks include Field Goals and Punts but NOT Extra Points - `BlockedKickReturns` integer, nullable: Blocked kick recovery returns by the player on the play - `BlockedKickReturnYards` integer, nullable: Blocked kick recovery return yards by the player on the play - `BlockedKickReturnTouchdowns` integer, nullable: Blocked kick recovery return touchdowns by the player on the play - `FieldGoalReturns` integer, nullable: Field goal returns by the player on the play - `FieldGoalReturnYards` integer, nullable: Field goal return yards by the player on the play. Note: This field excludes blocked field goals - `FieldGoalReturnTouchdowns` integer, nullable: Field goal return touchdowns by the player on the play. Note: This field excludes blocked field goals - `Kickoffs` integer, nullable: Total kickoffs by this player on the play - `KickoffYards` integer, nullable: Gross kickoff yards by the player on the play - `KickoffTouchbacks` integer, nullable: Kickoff touchbacks by the player on the play - `Punts` integer, nullable: Total number of punts by the player on the play. Note: this field is expected to be 1 or 0 - `PuntYards` integer, nullable: Total gross punt yards by the player on the play - `PuntTouchbacks` integer, nullable: Total punt touchbacks by the player on the play. Note: this field is expected to be either 1 or 0 - `PuntsHadBlocked` integer, nullable: Total punts by the player that were blocked on the play. Note: this field is expected to be 1 or 0 - `FieldGoalsAttempted` integer, nullable: Field goals attempted by the player on the play - `FieldGoalsMade` integer, nullable: Field goals made by the player on the play - `FieldGoalsYards` integer, nullable: Field goal yards attempted by the player on the play - `FieldGoalsHadBlocked` integer, nullable: Field goals attempted by the player that were blocked on the play - `ExtraPointsAttempted` integer, nullable: Extra points attempted by the player on the play - `ExtraPointsMade` integer, nullable: Extra points made by the player on the play - `ExtraPointsHadBlocked` integer, nullable: Extra point attempts by the player that were blocked on the play - `Penalties` integer, nullable: Indicates the number of penalties against a player on a play. Note: This serves as a placeholder for data intended to be added in the future - `PenaltyYards` integer, nullable: Total penalty yards enforced against the player on the play ## Other responses - `401`: Unauthorized ## Changes - **2026-11-07** `2dca8b6e9675`: 1 info - added the optional property `items/Score/Deleted` to the response with the `200` status [Operation history](https://skmtc.dev/sportsdata/apis/nfl-api/changes/v3/nfl/pbp/:format/SimulatedPlayByPlay/:numberofplays/get.md) --- [API](https://skmtc.dev/sportsdata/apis/nfl-api.md) - [All operations](https://skmtc.dev/sportsdata/apis/nfl-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sportsdata/apis/nfl-api/revisions/2dca8b6e9675?raw)