MLB Game Play-by-Play provides detailed, real-time information on every pitch and game event.
Update FrequencyTTL / Cache: This endpoint will update to a 2s TTL (time to live) upon a game moving to inprogress. Upon closed, it will transfer to 120s.
Data Updates: Realtime
Data Points
Boxscore:
Attribute | Parent Element | Type | Description |
---|---|---|---|
|
| Integer | Attendance of a game |
|
| String | Abbreviation of the away team |
|
| String | Duration of a game in hours and minutes |
|
| String | Duration of a game delay in hours and minutes |
|
| Integer | Number of errors for the away team |
|
| String | Number of errors while the away team was batting in an inning |
|
| Integer | Number of hits for the away team |
|
| String | Number of hits for the away team in an inning |
|
| GUID | Unique ID of the away team |
|
| String | Market name of the away team |
|
| String | Team name of the away team |
|
| Integer | Number of runs for the away team in the game |
|
| String | Number of runs for the away team in an inning |
|
| String | Abbreviation of the home team |
|
| Integer | Number of errors for the home team |
|
| String | Number of errors while the home team was batting in an inning |
|
| Integer | Number of hits for the home team |
|
| String | Number of hits for the home team in an inning |
|
| GUID | Unique ID of the home team |
|
| String | Market name of the home team |
|
| String | Team name of the home team |
|
| Integer | Number of runs for the home team in the game |
|
| String | Number of runs for the home team in an inning |
|
| Integer | Number of losses for the away team |
|
| Integer | Number of losses for the home team |
|
| Integer | Number of wins for the away team |
|
| Integer | Number of wins for the home team |
Game:
Attribute | Parent Element | Type | Description |
---|---|---|---|
away_team | game | GUID | Unique ID of the away team ex. 29dd9a87-5bcc-4774-80c3-7f50d985068b |
coverage | game | String | Coverage level of a gamefull , boxscore |
double_header | game | Boolean | Signifies whether a game is part of a double header |
day_night | game | String | Signifies a day or night gameD , N |
entry_mode | game | String | Signifies the type of data entrySTOMP , LDE |
home_team | game | GUID | Unique ID of the home team ex. ef64da7f-cfaf-4300-87b0-9313386b977c |
id | game | GUID | Unique ID of the game ex. 1b554f5e-d8b7-4268-95da-2f4191015c84 |
game_number | game | Integer | Number of the game |
parent_id | game | GUID | Standard parent ID of a game or series. Use this ID to group events (like the World Series or All-Star Game) across seasons. ex. 34e4cbbe-0086-4fad-bb08-840cbcfcabf0 (All-Star Game) |
reference | game | String | Unique MLBAM ID of a game |
scheduled | game | dateTime | Scheduled date and time of a game ex. 2022-09-25T20:10:00+00:00 |
tbd | game | Boolean | Signifies the game start time is to be determined. Placeholder start time is 08:00:00+00:00 |
season_id | game | GUID | Unique ID of the season a game belongs within ex. 6a5c278f-ebce-41f9-b1ba-2160b6af04ce |
season_type | game | String | Code type of the season a game belongs within ex. REG (Regular), PRE (Preseason), PST (Postseason), AST (All-Star) |
season_year | game | Integer | Year of the season a game belongs within |
split_squad | game | Boolean | Signifies a Spring Training split squad game |
status | game | String | The status of a gamescheduled , inprogress , complete , closed , wdelay , fdelay , odelay , canceled , unnecessary , if-necessary , postponed , suspended , maintenance |
id | event | GUID | Unique ID of a deleted event ex. 5e3a0b5d-72fa-40e5-8f9d-a10e6a46a831 |
away | game -time_zones | String | Time zone of the away team ex. US/Pacific |
home | game -time_zones | String | Time zone of the home team ex. US/Eastern |
venue | game -time_zones | String | Time zone of the venue ex. US/Eastern |
Broadcast:
Attribute | Parent Element | Type | Description |
---|---|---|---|
channel | broadcasts - broadcast | String | Name of a game's broadcast channel ex. 213 |
locale | broadcasts - broadcast | String | Signifies the locale of a broadcast ex. Home , Away , National |
network | broadcasts - broadcast | String | Name of a game's broadcast network ex. MLB Network , NBCS-BA , ESPN |
type | broadcasts - broadcast | String | Type of broadcast ex. TV , Internet |
Mound Visits & Reviews:
Attribute | Parent Element | Type | Description |
---|---|---|---|
remaining | mound_visits - home | Integer | Number of mound visits remaining for the home team |
used | mound_visits - home | Integer | Number of used mound visits for the home team |
remaining | mound_visits - away | Integer | Number of mound visits remaining for the away team |
used | mound_visits - away | Integer | Number of used mound visits for the away team |
remaining | reviews - home | Integer | Number of remaining reviews for the home team |
used | reviews - home | Integer | Number of used reviews for the home team |
remaining | reviews - away | Integer | Number of remaining reviews for the away team |
used | reviews - away | Integer | Number of used reviews for the away team |
Weather:
Attribute | Parent Element | Type | Description |
---|---|---|---|
|
| Integer | Current cloud cover of a game in percentage |
|
| String | Current weather condition for a game |
|
| Integer | Current dew point number of a game |
|
| Integer | Current humidity number of a game |
|
| dateTime | Timestamp of the current weather observation |
|
| Integer | Current temperature of a game in Fahrenheit |
|
| String | Direction of wind in the game |
|
| Integer | Wind speed in the game in miles per hour |
|
| Integer | Forecasted cloud cover of a game in percentage |
|
| String | Forecasted weather condition for a game |
|
| Integer | Forecasted dew point number of a game |
|
| Integer | Forecasted humidity number of a game |
|
| dateTime | Timestamp of the forecasted weather observation |
|
| Integer | Forecasted temperature of a game in Fahrenheit |
|
| String | Forecasted direction of wind in the game |
|
| Integer | Forecasted wind speed in a game in miles per hour |
Lineup:
Attribute | Parent Element | Type | Description |
---|---|---|---|
order | lineup | Integer | Batting order number in the lineup for a player (0-9). 0 is used for the pitcher |
description | lineup | String | Text description of a lineup change ex. Albert Pujols pinch-hitting for Corey Dickerson. |
position | lineup | Integer | Position number for a player (1-10). 10 is used for the designated hitter |
id | lineup | GUID | Unique ID of a lineup entry ex. 616d0907-26f1-4adf-875f-c0928d6d1b22 |
first_name | lineup | String | First name of a player ex. Markus |
full_name | lineup | String | Full name of a player ex. Mookie Betts |
suffix | lineup | String | Name suffix of a player ex. Jr. |
player_id | lineup | GUID | Unique ID of a player ex. 084d2514-9ffb-414e-ae16-3bc690aaad51 |
jersey_number | lineup | Integer | Number of a player's jersey |
last_name | lineup | String | Last name of a player ex. Betts |
preferred_name | lineup | String | Preferred name of a player ex. Mookie |
team_id | lineup | GUID | Unique ID of a player's team ex. ef64da7f-cfaf-4300-87b0-9313386b977c |
Play-By-Play - At Bat:
Attribute | Parent Element | Type | Description |
---|---|---|---|
first_name | hitter | String | First name of a hitter ex. Markus |
full_name | hitter | String | Full name of a hitter ex. Mookie Betts |
suffix | hitter | String | Name suffix of a hitter ex. Jr. |
hitter_hand | at_bat | String | Handedness of a hitter |
hitter_id | at_bat | GUID | Unique ID of a hitter ex. 084d2514-9ffb-414e-ae16-3bc690aaad51 |
jersey_number | hitter | Integer | Number of a hitter's jersey |
last_name | hitter | String | Last name of a hitter ex. Betts |
preferred_name | hitter | String | Preferred name of a player ex. Mookie |
id | at_bat | GUID | Unique ID of an at bat entry ex. c1e69331-8909-4f1c-b132-5b33079355b4 |
first_name | pitcher | String | First name of a pitcher ex. Adam |
full_name | pitcher | String | Full name of a pitcher ex. Adam Wainwright |
suffix | pitcher | String | Name suffix of a pitcher ex. Jr. |
pitcher_hand | at_bat | String | Handedness of a pitcher |
pitcher_id | at_bat | GUID | Unique ID of a pitcher ex. 084d2514-9ffb-414e-ae16-3bc690aaad51 |
jersey_number | pitcher | Integer | Number of a pitcher's jersey |
last_name | pitcher | String | Last name of a pitcher ex. Wainwright |
preferred_name | pitcher | String | Preferred name of a pitcher ex. Adam |
description | - | String | Text description of a play ex. Will Smith singles to center field. Freddie Freeman to third. |
sequence_number | at_bat | Integer | Sequence number of an event within a game |
Play-By-Play - Base Runner:
Attribute | Parent Element | Type | Description |
---|---|---|---|
|
| Integer | Runner's base at the end of a play |
|
| String | First name of a runner |
|
| String | Full name of a runner |
|
| String | Name suffix of a runner |
|
| Integer | Number of a runner's jersey |
|
| String | Last name of a runner |
|
| Boolean | Signifies the runner was out on a play |
|
| String | ID of a runner outcome on a play. Check our FAQ for a list of valid outcomes and their definitions |
| String | Text description of a runner outcome | |
|
| GUID | Unique ID of a player of a runner |
|
| String | Preferred name of a runner |
|
| Integer | Runner's base at the start of a play |
|
| dateTime | Timestamp of a runner placed at 2nd base to start an inning |
|
| GUID | Unique ID of a runner placed at 2nd base to start an inning |
|
| Boolean | Signifies whether the API is ingesting data directly from the league at the time of the event. |
|
| Integer | Sequential number of a runner placed event in a game |
|
| String | Status of a runner placed event. Can be utilized to determine if a play is or was under review |
|
| dateTime | Timestamp of a runner placed event |
Play-By-Play - Hitter:
Attribute | Parent Element | Type | Description |
---|---|---|---|
first_name | hitter | String | First name of a hitter ex. Markus |
full_name | hitter | String | Full name of a hitter ex. Mookie Betts |
suffix | hitter | String | Name suffix of a hitter ex. Jr. |
hitter_hand | pitcher | String | Handedness of a hitter |
id | hitter | GUID | Unique ID of a player of a hitter ex. ea1a2111-44cc-4996-babb-9439465e6760 |
jersey_number | hitter | Integer | Number of a hitter's jersey |
last_name | hitter | String | Last name of a hitter ex. Betts |
preferred_name | hitter | String | Preferred name of a hitter ex. Mookie |
Play-By-Play - Count:
Attribute | Parent Element | Type | Description |
---|---|---|---|
balls | count | Integer | Number of balls in an at bat |
outs | count | Integer | Number of outs in an at bat |
pitch_count | count | Integer | Number of pitches in an at bat |
strikes | count | Integer | Number of strikes in an at bat |
Play-By-Play - Errors:
Attribute | Parent Element | Type | Description |
---|---|---|---|
first_name | error | String | First name of a player committing an error ex. Gavin |
full_name | error | String | Full name of a player committing an error ex. Gavin Lux |
suffix | error | String | Name suffix of a player committing an error ex. Jr. |
id | error | GUID | Unique ID of a player of a player committing an error ex. ea1a2111-44cc-4996-babb-9439465e6760 |
jersey_number | error | Integer | Jersey number a player committing an error |
last_name | error | String | Last name of a player committing an error ex. Lux |
preferred_name | error | String | Preferred name of a player committing an error ex. Gavin |
type | error | String | Type of fielding errorfielding , throwing , interference |
Play-By-Play - Fielding:
Attribute | Parent Element | Type | Description |
---|---|---|---|
first_name | assist | String | First name of a player recording an assist ex. Gavin |
full_name | assist | String | Full name of a player recording an assist ex. Gavin Lux |
suffix | assist | String | Name suffix of a player recording an assist ex. Jr. |
id | assist | GUID | Unique ID of a player of a player recording an assist ex. ea1a2111-44cc-4996-babb-9439465e6760 |
jersey_number | assist | Integer | Jersey number a player recording an assist |
last_name | assist | String | Last name of a player recording an assist ex. Lux |
preferred_name | assist | String | Preferred name of a player recording an assist ex. Gavin |
sequence | assist | Integer | Sequential number of an assist |
first_name | putout | String | First name of a player recording a putout ex. Byron |
full_name | putout | String | Full name of a player recording a putout ex. Byron Buxton |
suffix | putout | String | Name suffix of a player recording a putout ex. Jr. |
id | putout | GUID | Unique ID of a player of a player recording a putout ex. ea1a2111-44cc-4996-babb-9439465e6760 |
jersey_number | putout | Integer | Jersey number a player recording a putout |
last_name | putout | String | Last name of a player recording a putout ex. Buxton |
preferred_name | putout | String | Preferred name of a player recording a putout ex. Gavin |
sequence | putout | Integer | Sequential number of a putout |
Play-By-Play - Hit Data:
Please note that attributes within
mlb_hit_data
may not be present for every event
Attribute | Parent Element | Type | Description |
---|---|---|---|
|
| Decimal | X coordinate marked by operator of where the ball was fielded |
|
| Decimal | Y coordinate marked by operator of where the ball was fielded |
|
| String | Amount of hard contact on a hit |
|
| Decimal | Vertical angle relative to the horizon at which a hit was launched |
|
| Decimal | Measured speed of a hit ball |
|
| Integer | Positional number (1-9) of the player nearest to a hit ball location. Please see our FAQ for fielding position numbers and definitions |
|
| Integer | Total distance a hit ball traveled (in feet) |
|
| String | Trajectory of a batted ball into the field of play |
|
| Integer | Number code of hit ball location (1-35). Please see our FAQ for a diagram of our field and its corresponding hit location zones |
|
| String | Type of hit |
Play-By-Play - Inning:
Attribute | Parent Element | Type | Description |
---|---|---|---|
type | inning_half | String | Indicates top or bottom inning halfT , B |
number | inning | Integer | Number of an inning |
sequence | inning | Integer | Sequential number of an inning |
Play-By-Play - Pitch:
Attribute | Parent Element | Type | Description |
---|---|---|---|
|
| GUID | Unique ID of a pitch |
|
| Integer | Number as a percentage distance from the center of the strike zone, in positive or negative values from approximately -300% to positive 300% |
|
| Integer | Number as a percentage distance from the center of the strike zone, in positive or negative values from approximately -200% to positive 200% |
|
| dateTime | Timestamp of a thrown pitch |
|
| Integer | Number of pitches for a pitcher in a game |
|
| Boolean | Signifies whether the API is ingesting data directly from the league at the time of the event. |
|
| String | ID of a pitch outcome on a play. Check our FAQ for a list of valid outcomes and their definitions |
|
| String | Unique MLBAM ID of a pitch |
|
| Integer | Sequential number of a pitch in a game |
|
| String | Speed of a pitch in MPH |
|
| String | Code for a type of pitch |
|
| Integer | Number corresponding to the pitch strike zone (1-13) |
|
| String | Status of a pitch. Can be utilized to determine if a play is or was under review |
|
| dateTime | Timestamp of a pitch update |
|
| dateTime | Timestamp of an event end time |
|
| dateTime | Timestamp of an event start time |
Play-By-Play - Pitcher:
Attribute | Parent Element | Type | Description |
---|---|---|---|
first_name | pitcher | String | First name of a pitcher ex. Clayton |
full_name | pitcher | String | Full name of a pitcher ex. Clayton Kershaw |
suffix | pitcher | String | Name suffix of a pitcher ex. Jr. |
pitcher_hand | pitcher | String | Handedness of a pitcher |
id | pitcher | GUID | Unique ID of a player of a pitcher ex. ea1a2111-44cc-4996-babb-9439465e6760 |
jersey_number | pitcher | Integer | Number of a pitcher's jersey |
last_name | pitcher | String | Last name of a pitcher ex. Kershaw |
preferred_name | pitcher | String | Preferred name of a pitcher ex. Clayton |
Play-By-Play - Play Flags:
Attribute | Parent Element | Type | Description |
---|---|---|---|
is_ab_over | flags | Boolean | Indicates an at bat has ended on a pitch |
is_bunt | flags | Boolean | Indicates a bunt play |
is_double_play | flags | Boolean | Indicates a double play |
is_passed_ball | flags | Boolean | Indicates a passed ball |
is_hit | flags | Boolean | Indicates a hit |
is_triple_play | flags | Boolean | Indicates a triple play |
is_wild_pitch | flags | Boolean | Indicates a wild pitch |
ci | at_bat - pitch - pitching | Integer | Signifies an at bat ended with a batter reaching on catcher interference when ci="1" |
ci | at_bat - pitch - hitting | Integer | Signifies an at bat ended with a batter reaching on catcher interference when ci="1" |
rov | at_bat - pitch - pitching | Integer | Signifies an at bat ended with a batter reaching on a violation when rov="1" |
rov | at_bat - pitch - hitting | Integer | Signifies an at bat ended with a batter reaching on a violation when rov="1" |
Play-By-Play - Score:
Attribute | Parent Element | Type | Description |
---|---|---|---|
away_team_runs | at_bat - score | Integer | Away team runs for an at bat |
home_team_runs | at_bat - score | Integer | Home team runs for an at bat |
away_team_runs | pitch / steal - score | Integer | Away team runs for an event |
home_team_runs | pitch / steal - score | Integer | Home team runs for an event |
Play-By-Play - Steal:
Attribute | Parent Element | Type | Description |
---|---|---|---|
|
| dateTime | Timestamp of a steal attempt |
|
| GUID | Unique ID of a steal attempt |
|
| Boolean | Signifies whether the API is ingesting data directly from the league at the time of the event. |
|
| Integer | Sequence number of an event within a game |
|
| String | Status of a pitch/play. Can be utilized to determine if a play is or was under review |
|
| dateTime | Timestamp of a steal attempt update |
Play-By-Play - Warming Up:
Attribute | Parent Element | Type | Description |
---|---|---|---|
first_name | warming_up | String | First name of a pitcher warming up in the bullpen ex. Brusdar |
full_name | warming_up | String | Full name of a pitcher warming up in the bullpen ex. Brusdar Graterol |
suffix | warming_up | String | Name suffix of a pitcher warming up in the bullpen ex. Jr. |
id | warming_up | GUID | Unique ID of a warming up event ex. ea1a2111-44cc-4996-babb-9439465e6760 |
player_id | warming_up | GUID | Unique ID of a player of a pitcher warming up in the bullpen ex. 43862b88-c119-4625-b138-f3c5ea1b8b06 |
jersey_number | warming_up | Integer | Number of a pitcher's jersey |
last_name | warming_up | String | Last name of a pitcher warming up in the bullpen ex. Graterol |
preferred_name | warming_up | String | Preferred name of a pitcher warming up in the bullpen ex. Brusdar |
team_id | warming_up | GUID | Unique team ID of a pitcher warming up in the bullpen ex. 75729d34-bca7-4a0f-b3df-6f26c6ad3719 |
Play-By-Play - Pitch Data:
Please note that attributes within
mlb_pitch_data
may not be present for every event
Attribute | Parent Element | Type | Description |
---|---|---|---|
|
| Decimal | Degrees clockwise (batter’s view) that the plane ofthe pitch deviates from the vertical |
|
| Decimal | Max distance (in inches) that the pitch separates from the straight line between pitch start and pitch end |
|
| Decimal | Distance (in feet) from home plate where the break is greatest |
|
| Decimal | The axis of rotation for the ball at release given as an angle that reflects how the spin will influence the ball trajectory. Pure back-spin is 180 degrees, pure side-spin that puts the ball to the 1b side is 90 degrees, pure-side spin that pulls the ball to the 3b side is 270 degrees, and pure top-spin is 0 or 360 degrees |
|
| Decimal | Rate of spin on the ball (in RPMs) after it was released by pitcher. |
|
| String | Two-letter code for a type of pitch. |
|
| Decimal | Ball acceleration on the x axis |
|
| Decimal | Ball acceleration on the y axis |
|
| Decimal | Ball acceleration on the z axis |
|
| Decimal | Horizontal position in feet of the ball as it crosses the front axis of home plate |
|
| Decimal | Vertical position in feet above home plate of the ball as it crosses the front axis of home plate |
|
| Decimal | Horizontal movement of the ball in inches |
|
| Decimal | Vertical movement of the ball in inches |
|
| Decimal | Velocity of the ball from the x axis |
|
| Decimal | Velocity of the ball from the y axis; this is negative because 0,0,0 is behind the batter and the ball travels from pitcher mound towards 0,0,0 |
|
| Decimal | Velocity of the ball from the z axis |
|
| Decimal | X coordinate where a pitch crossed the front of home plate |
|
| Decimal | Coordinate location of the ball at the point it was released from the pitchers hand on the x axis (time = 0) |
|
| Decimal | Y coordinate where a pitch crossed the front of home plate |
|
| Decimal | Coordinate location of the ball at the point it was released from the pitchers hand on the y axis (time = 0) |
|
| Decimal | Coordinate location of the ball at the point it was released from the pitchers hand on the z axis (time = 0) |
|
| String | Text description of a pitch |
|
| Decimal | Speed in MPH of the ball as it crosses the front edge of home plate (0,0 in the x axis) |
|
| Decimal | Measure of the true release point from pitching rubber - distance in feet closer to home plate than the 60.5 ft from pitching rubber to home |
|
| Decimal | Time from pitchers release until the ball is projected to reach the back tip of home plate or struck by the bat |
|
| Decimal | Speed in MPH of the ball at 50 feet in front of homeplate |
|
| Decimal | Distance in feet from ground to bottom of batter strike zone |
|
| Decimal | Distance in feet from ground to top of batter strike zone |
Venue:
Attribute | Parent Element | Type | Description |
---|---|---|---|
address | venue | String | Address of a venue ex. 1000 Vin Scully Avenue |
capacity | venue | String | Capacity of a venue ex. 56000 |
city | venue | String | City of a venue ex. Los Angeles |
country | venue | String | Country of a venue ex. USA |
field_orientation | venue | String | Field orientation of a venue ex. NE |
id | venue | GUID | Unique ID of a venue ex. 66a19c3d-24fe-477d-bee7-c6ef1b98352f |
lat | location | Decimal | Latitude of a venue ex. 34.0745409 |
lng | location | Decimal | Longitude of a venue ex. -118.2408881 |
market | venue | String | Market of a venue ex. Los Angeles |
name | venue | String | Name of a venue ex. Dodger Stadium |
stadium_type | venue | String | Type of a venue ex. outdoor |
state | venue | String | State of a venue ex. CA |
surface | venue | String | Surface type of a venue ex. grass |
time_zone | venue | String | Time zone of a venue ex. US/Central |
zip | venue | Integer | ZIP code of a venue ex. 90012 |