Acquire pitch-by-pitch data between two timecodes for Major and Minor League games
Source:R/mlb_pbp_diff.R
mlb_pbp_diff.RdAcquire pitch-by-pitch data between two timecodes for Major and Minor League games
Value
Returns a tibble that includes over 100 columns of data provided by the MLB Stats API at a pitch level between the start_timecode and end_timecode
| col_name | types | description |
| game_pk | numeric | MLB game primary key. |
| game_date | character | Game date (YYYY-MM-DD). |
| index | integer | Index of the play event within the at-bat. |
| startTime | character | Event start timestamp (ISO 8601). |
| endTime | character | Event end timestamp (ISO 8601). |
| isPitch | logical | Whether the event is a pitch. |
| type | character | Play event type (e.g. 'pitch', 'action'). |
| playId | character | Unique play event identifier (UUID). |
| pitchNumber | integer | Pitch number within the at-bat. |
| details.description | character | Pitch/event description (e.g. 'Foul', 'Ball'). |
| details.event | character | Event name for non-pitch actions. |
| details.awayScore | integer | Away score recorded at the event. |
| details.homeScore | integer | Home score recorded at the event. |
| details.isScoringPlay | logical | Whether the event is a scoring play. |
| details.hasReview | logical | Whether the event was reviewed. |
| details.code | character | Pitch/result code (e.g. 'F', 'B'). |
| details.ballColor | character | Gameday ball color rgba string. |
| details.isInPlay | logical | Whether the ball was put in play. |
| details.isStrike | logical | Whether the pitch was a strike. |
| details.isBall | logical | Whether the pitch was a ball. |
| details.call.code | character | Umpire call code. |
| details.call.description | character | Umpire call description. |
| count.balls.start | integer | Ball count before the pitch. |
| count.strikes.start | integer | Strike count before the pitch. |
| count.outs.start | integer | Out count before the pitch. |
| player.id | integer | Player id for action-event participant. |
| player.link | character | API relative link to the action player. |
| pitchData.strikeZoneTop | numeric | Top of the batter strike zone (feet). |
| pitchData.strikeZoneBottom | numeric | Bottom of the batter strike zone (feet). |
| details.fromCatcher | logical | Whether the event originated from the catcher. |
| pitchData.coordinates.x | numeric | Pitch x pixel coordinate (Gameday). |
| pitchData.coordinates.y | numeric | Pitch y pixel coordinate (Gameday). |
| hitData.trajectory | character | Batted ball trajectory. |
| hitData.hardness | character | Batted ball hardness. |
| hitData.location | character | Fielding position where the ball was hit. |
| hitData.coordinates.coordX | numeric | Batted ball landing x coordinate. |
| hitData.coordinates.coordY | numeric | Batted ball landing y coordinate. |
| actionPlayId | character | Identifier of an associated action play. |
| details.eventType | character | Event type slug for non-pitch actions. |
| details.runnerGoing | logical | Whether a runner was going on the pitch. |
| position.code | character | Fielding position code for the player. |
| position.name | character | Fielding position name. |
| position.type | character | Fielding position type. |
| position.abbreviation | character | Fielding position abbreviation. |
| battingOrder | character | Batting order slot. |
| atBatIndex | character | At-bat index within the game (factor). |
| result.type | character | Result type (e.g. 'atBat'). |
| result.event | character | At-bat result event. |
| result.eventType | character | At-bat result event slug. |
| result.description | character | Narrative description of the at-bat result. |
| result.rbi | integer | Runs batted in on the at-bat. |
| result.awayScore | integer | Away score after the at-bat. |
| result.homeScore | integer | Home score after the at-bat. |
| about.atBatIndex | integer | At-bat index (numeric). |
| about.halfInning | character | Half inning ('top' or 'bottom'). |
| about.inning | integer | Inning number. |
| about.startTime | character | At-bat start timestamp (ISO 8601). |
| about.endTime | character | At-bat end timestamp (ISO 8601). |
| about.isComplete | logical | Whether the at-bat is complete. |
| about.isScoringPlay | logical | Whether the at-bat is a scoring play. |
| about.hasReview | logical | Whether the at-bat had a review. |
| about.hasOut | logical | Whether the at-bat produced an out. |
| about.captivatingIndex | integer | MLB captivating index for the play. |
| count.balls.end | integer | Ball count after the pitch. |
| count.strikes.end | integer | Strike count after the pitch. |
| count.outs.end | integer | Out count after the pitch. |
| matchup.batter.id | integer | Batter player id. |
| matchup.batter.fullName | character | Batter full name (factor). |
| matchup.batter.link | character | API relative link to the batter. |
| matchup.batSide.code | character | Batter handedness code (e.g. 'L', 'R'). |
| matchup.batSide.description | character | Batter handedness description. |
| matchup.pitcher.id | integer | Pitcher player id. |
| matchup.pitcher.fullName | character | Pitcher full name (factor). |
| matchup.pitcher.link | character | API relative link to the pitcher. |
| matchup.pitchHand.code | character | Pitcher throwing hand code (e.g. 'R'). |
| matchup.pitchHand.description | character | Pitcher throwing hand description. |
| matchup.splits.batter | character | Batter platoon split (e.g. 'vs_RHP'). |
| matchup.splits.pitcher | character | Pitcher platoon split (e.g. 'vs_RHB'). |
| matchup.splits.menOnBase | character | Men on base split (e.g. 'Men_On'). |
| batted.ball.result | factor | Categorized batted ball result. |
| home_team | character | Home team name. |
| home_level_id | integer | Home team level/sport id (1 for MLB). |
| home_level_name | character | Home team level/sport name. |
| home_parentOrg_id | integer | Home team parent organization id (minors). |
| home_parentOrg_name | character | Home team parent organization name (minors). |
| home_league_id | integer | Home team league id. |
| home_league_name | character | Home team league name. |
| away_team | character | Away team name. |
| away_level_id | integer | Away team level/sport id (1 for MLB). |
| away_level_name | character | Away team level/sport name. |
| away_parentOrg_id | integer | Away team parent organization id (minors). |
| away_parentOrg_name | character | Away team parent organization name (minors). |
| away_league_id | integer | Away team league id. |
| away_league_name | character | Away team league name. |
| batting_team | character | Team batting on the play (factor). |
| fielding_team | character | Team fielding on the play (factor). |
| last.pitch.of.ab | character | Whether the pitch was the last of the at-bat (factor). |
| pfxId | character | Pitch f/x tracking identifier. |
| details.trailColor | character | Gameday pitch trail color rgba string. |
| details.type.code | character | Pitch type code (e.g. 'SI', 'CH'). |
| details.type.description | character | Pitch type description (e.g. 'Sinker', 'Changeup'). |
| pitchData.startSpeed | numeric | Pitch release speed (mph). |
| pitchData.endSpeed | numeric | Pitch speed crossing the plate (mph). |
| pitchData.zone | integer | Strike zone region of the pitch. |
| pitchData.typeConfidence | numeric | Pitch type classification confidence. |
| pitchData.plateTime | numeric | Time from release to plate (seconds). |
| pitchData.extension | numeric | Pitcher release extension (feet). |
| pitchData.coordinates.aY | numeric | Pitch acceleration in y (ft/s^2). |
| pitchData.coordinates.aZ | numeric | Pitch acceleration in z (ft/s^2). |
| pitchData.coordinates.pfxX | numeric | Horizontal pitch movement (inches). |
| pitchData.coordinates.pfxZ | numeric | Vertical pitch movement (inches). |
| pitchData.coordinates.pX | numeric | Horizontal pitch location at plate (feet). |
| pitchData.coordinates.pZ | numeric | Vertical pitch location at plate (feet). |
| pitchData.coordinates.vX0 | numeric | Pitch initial velocity in x (ft/s). |
| pitchData.coordinates.vY0 | numeric | Pitch initial velocity in y (ft/s). |
| pitchData.coordinates.vZ0 | numeric | Pitch initial velocity in z (ft/s). |
| pitchData.coordinates.x0 | numeric | Pitch initial x position (feet). |
| pitchData.coordinates.y0 | numeric | Pitch initial y position (feet). |
| pitchData.coordinates.z0 | numeric | Pitch initial z position (feet). |
| pitchData.coordinates.aX | numeric | Pitch acceleration in x (ft/s^2). |
| pitchData.breaks.breakAngle | numeric | Pitch break angle (degrees). |
| pitchData.breaks.breakLength | numeric | Pitch break length (inches). |
| pitchData.breaks.breakY | numeric | Distance from plate where break is measured. |
| pitchData.breaks.spinRate | integer | Pitch spin rate (RPM). |
| pitchData.breaks.spinDirection | integer | Pitch spin direction (degrees). |
| hitData.launchSpeed | numeric | Batted ball exit velocity (mph). |
| hitData.launchAngle | numeric | Batted ball launch angle (degrees). |
| hitData.totalDistance | numeric | Batted ball total distance (feet). |
| injuryType | character | Injury type when the event is injury-related. |
| umpire.id | integer | Umpire person id for the event. |
| umpire.link | character | API relative link to the umpire. |
| details.isOut | logical | Whether the pitch/event resulted in an out. |
| pitchData.breaks.breakVertical | numeric | Total vertical break (inches). |
| pitchData.breaks.breakVerticalInduced | numeric | Induced vertical break (inches). |
| pitchData.breaks.breakHorizontal | numeric | Horizontal break (inches). |
| details.disengagementNum | integer | Pitcher disengagement number on the play. |
| result.isOut | logical | Whether the at-bat resulted in an out. |
| about.isTopInning | logical | Whether the play occurred in the top of the inning. |
| matchup.postOnFirst.id | integer | Runner id on first base after the play. |
| matchup.postOnFirst.fullName | character | Runner name on first base after the play. |
| matchup.postOnFirst.link | character | API relative link to the first base runner. |
Examples
# \donttest{
try(mlb_pbp_diff(game_pk = 632970,
start_timecode = "20210808_231704",
end_timecode = "20210808_233711"))
#> ── MLB Play-by-Play diff data from MLB.com ────────── baseballr 2.0.0 ──
#> ℹ Data updated: 2026-06-12 14:09:44 UTC
#> # A tibble: 50 × 141
#> game_pk game_date index startTime endTime isPitch type playId
#> <dbl> <chr> <int> <chr> <chr> <lgl> <chr> <chr>
#> 1 632970 2021-08-08 2 2021-08-08T23:… 2021-0… TRUE pitch 0c67e…
#> 2 632970 2021-08-08 1 2021-08-08T23:… 2021-0… TRUE pitch 51631…
#> 3 632970 2021-08-08 0 2021-08-08T23:… 2021-0… TRUE pitch e3edf…
#> 4 632970 2021-08-08 2 2021-08-08T23:… 2021-0… TRUE pitch 65870…
#> 5 632970 2021-08-08 1 2021-08-08T23:… 2021-0… TRUE pitch d5fc8…
#> 6 632970 2021-08-08 0 2021-08-08T23:… 2021-0… TRUE pitch 0a6c9…
#> 7 632970 2021-08-08 4 2021-08-08T23:… 2021-0… TRUE pitch 506d0…
#> 8 632970 2021-08-08 3 2021-08-08T23:… 2021-0… TRUE pitch 24f33…
#> 9 632970 2021-08-08 2 2021-08-08T23:… 2021-0… TRUE pitch aae6b…
#> 10 632970 2021-08-08 1 2021-08-08T23:… 2021-0… TRUE pitch 63658…
#> # ℹ 40 more rows
#> # ℹ 133 more variables: pitchNumber <int>, details.description <chr>,
#> # details.event <chr>, details.awayScore <int>,
#> # details.homeScore <int>, details.isScoringPlay <lgl>,
#> # details.hasReview <lgl>, details.code <chr>,
#> # details.ballColor <chr>, details.isInPlay <lgl>,
#> # details.isStrike <lgl>, details.isBall <lgl>, …
# }