Categories

Coverage
Integration
Player Statuses
Play Outcomes
Hit Types & Location
Pitch / Hit Data Descriptions
Roster Updates
All-Star Game
Seasonal Statistics
Ohtani Rule
Data Failover

Game Statuses
Data Workflow
Lineup Positions
Pitch Zone, Speed, Types & Location
Transaction Codes & Types
Standings & Rankings
Spring Training
Umpire Assignments
Statcast Data
ID Handling

.

Coverage

How is each MLB game covered?

Coverage information for MLB can be found here.

Integration

Are simulations available for this API?

Yes! You can replay past games as though they were live using our on-demand Simulations service.

What format are date fields presented in?

Date values are presented in the ISO 8601 standard format.

Timestamp fields are in UTC. These could include scheduled start times or play-by-play event timestamps. Examples: scheduled="2024-02-11T23:30:00+00:00", created_at="2024-02-11T23:43:20+00:00"

Date-only fields reflect local league convention and are not UTC-adjusted. These could include season start dates and birth dates. Examples: start_date="2024-08-16", date_of_birth="1984-09-22"

How do I locate the TTL (Time to Live)/cache on an API endpoint?

The cache (in seconds) can be accessed in the returned header information on each RESTful API call, under cache-control.

ex. cache-control: max-age=1, public, s-maxage=1 or cache-control: public, must-revalidate, max-age=120

Note that, for select game-centric endpoints, the TTL may adjust when an event is live. This information is available for each endpoint on our developer portal.

What are the valid entry mode values for a game?

Here is a list of the entry mode values:

STOMP
LDE

How do you handle the A's move to Sacramento?

Following the Oakland Athletics’ temporary relocation to Sacramento, the team name has been updated from “Oakland Athletics” to simply “Athletics.” As a result, the market value “Oakland” is no longer associated with the team.

You’ll see the team listed as shown below in the Teams endpoint, as well as in all other endpoints that include team data:

<team name="Athletics" abbr="ATH" id="27a59d3b-ff7c-48ea-b016-4798f560f5e1"

Game Statuses

What are the valid game statuses and their definitions?

Here is a list of the game statuses and their definitions. This information can also be found in our glossary feed:

scheduled - The game is scheduled to occur.
inprogress - The first pitch for the game has been received.
complete - The last pitch for the game has been received and statistics are being reviewed.
closed - The game has passed review and MLB has officially closed the game.
wdelay - The game has been delayed because of weather.
fdelay - The game has been delayed because of facility issues.
odelay - The game has been delayed.
canceled – The game has been canceled. No makeup game will be played as a result.
unnecessary – The series game was scheduled to occur, but will not take place due to one team clinching the series early.
if-necessary – The game will be scheduled if it is required.
postponed - The game has been postponed and will be rescheduled in the future, restarting at the top of the 1st. The current game and ID will remain the same for the makeup game in the future.
suspended - The game has been suspended and will be rescheduled in the future, continuing where they left off. The game ID will remain the same.
maintenance - The game is being reviewed internally and having data adjusted. We do not recommend pulling data for a game while in this status.

Data Workflow

How can I find timings for data entry updates?

Our MLB Data Entry Workflow section covers data availability updates. This includes updates for transactions, lineups, injuries, stat validation, and more.

Player Statuses

What are the valid player statuses and their definitions?

Here is a list of the player statuses and their definitions. This information can also be found in our glossary feed:

A = Activated
BRV = Bereavement List
D7 = 7 Day Injured List
D10 = 10 Day Injured List
D15 = 15 Day Injured List
D60 = 60 Day Injured List
DFA = Designated for assignment
FA = Free Agent
FME = Family Medical Emergency
LV = Paid Leave
MIN = Minors
NRI = Non-roster Invite
PL = Paternity Leave
RST = Restricted
RET = Retired
SUS = Suspended
UDP = Unsigned Draft Pick
WV = Waivers
Null (blank) = Traded or not activated*
Traded players temporarily have no status listed after they are traded to a new team and are either activated by the MLB club or assigned to a minor league affiliate.

What are the valid player injury statuses?

Here is a list of the player injury statuses:

D7
D10
D15
D60
Day-to-Day
Unknown

Lineup Positions

What are the valid lineup positions and their definitions?

Here is a list of the lineup positions and their definitions. Please note, this is the how the information is presented in the following feeds: Daily Summary, Game Summary, and Play-by-Play.

1 = Pitcher
2 = Catcher
3 = First Base
4 = Second Base
5 = Third Base
6 = Shortstop
7 = Left Field
8 = Centerfield
9 = Right Field
10 = Designated Hitter
11 = Pinch Hitter
12 = Pinch Runner

Here is a list of the roster positions and their definitions.

C = Catcher
DH = Designated Hitter
IF = Infield
OF = Outfield
P = Pitcher

Here is a list of the roster primary positions and their definitions.

C = Catcher
1B = First base
2B = Second base
3B = Third Base
SS = Shortstop
LF = Left Field
CF = Centerfield
P = Pitcher
RF = Right Field
RP = Relief Pitcher
SP = Starting Pitcher
DH = Designated Hitter

<roster>
    <player preferred_name="Mookie" first_name="Markus" last_name="Betts" jersey_number="50" id="084d2514-9ffb-414e-ae16-3bc690aaad51" status="A" position="OF" primary_position="RF"/>
    <player preferred_name="Corey" first_name="Corey" last_name="Seager" jersey_number="5" id="ca159e78-05a9-410a-be7b-3ebad5496a88" status="A" position="IF" primary_position="SS"/>
    <player preferred_name="AJ" first_name="Allen" last_name="Pollock" jersey_number="11" id="d5b0fb7b-93d4-4c45-820f-069f622855c8" status="A" position="OF" primary_position="LF"/>
    <player preferred_name="Albert" first_name="Jose" last_name="Pujols" jersey_number="55" id="fb061c77-5253-4181-ad7b-c68ef18aa511" status="A" position="IF" primary_position="1B"/>
</roster>
<lineup>
    <player id="084d2514-9ffb-414e-ae16-3bc690aaad51" inning="0" order="1" position="9" sequence="1"/>
    <player id="ca159e78-05a9-410a-be7b-3ebad5496a88" inning="0" order="2" position="6" sequence="2"/>
    <player id="67dc86a1-cc03-41ae-ba7d-e5b8434c83e8" inning="0" order="3" position="4" sequence="3"/>
    <player id="893e5243-1278-476c-8801-280b9b14aea7" inning="0" order="4" position="5" sequence="4"/>
    <player id="317b24ac-6a9b-4735-a4c5-64d879cd6bf7" inning="0" order="5" position="2" sequence="5"/>
    <player id="d5b0fb7b-93d4-4c45-820f-069f622855c8" inning="0" order="6" position="7" sequence="6"/>
    <player id="4f68ff33-816e-4038-a4fb-8676758f8f0b" inning="0" order="7" position="3" sequence="7"/>
    <player id="bbe79e92-c56f-4e17-b5e4-6427c9fb7dce" inning="0" order="8" position="8" sequence="8"/>
    <player id="2527770b-cf48-42b9-81fa-9323756fb311" inning="0" order="9" position="1" sequence="9"/>

"roster": [
    {
        "preferred_name": "Mookie",
        "first_name": "Markus",
        "last_name": "Betts",
        "jersey_number": "50",
        "id": "084d2514-9ffb-414e-ae16-3bc690aaad51",
        "status": "A",
        "position": "OF",
        "primary_position": "RF"
    },
    {
        "preferred_name": "Corey",
        "first_name": "Corey",
        "last_name": "Seager",
        "jersey_number": "5",
        "id": "ca159e78-05a9-410a-be7b-3ebad5496a88",
        "status": "A",
        "position": "IF",
        "primary_position": "SS"
    },
    {
        "preferred_name": "AJ",
        "first_name": "Allen",
        "last_name": "Pollock",
        "jersey_number": "11",
        "id": "d5b0fb7b-93d4-4c45-820f-069f622855c8",
        "status": "A",
        "position": "OF",
        "primary_position": "LF"
    },
    {
        "preferred_name": "Albert",
        "first_name": "Jose",
        "last_name": "Pujols",
        "jersey_number": "55",
        "id": "fb061c77-5253-4181-ad7b-c68ef18aa511",
        "status": "A",
        "position": "IF",
        "primary_position": "1B"
    }
],
"lineup": [
    {
        "id": "084d2514-9ffb-414e-ae16-3bc690aaad51",
        "inning": 0,
        "order": 1,
        "position": 9,
        "sequence": 1
    },
    {
        "id": "ca159e78-05a9-410a-be7b-3ebad5496a88",
        "inning": 0,
        "order": 2,
        "position": 6,
        "sequence": 2
    },
    {
        "id": "67dc86a1-cc03-41ae-ba7d-e5b8434c83e8",
        "inning": 0,
        "order": 3,
        "position": 4,
        "sequence": 3
    },
    {
        "id": "893e5243-1278-476c-8801-280b9b14aea7",
        "inning": 0,
        "order": 4,
        "position": 5,
        "sequence": 4
    },
    {
        "id": "317b24ac-6a9b-4735-a4c5-64d879cd6bf7",
        "inning": 0,
        "order": 5,
        "position": 2,
        "sequence": 5
    },
    {
        "id": "d5b0fb7b-93d4-4c45-820f-069f622855c8",
        "inning": 0,
        "order": 6,
        "position": 7,
        "sequence": 6
    },
    {
        "id": "4f68ff33-816e-4038-a4fb-8676758f8f0b",
        "inning": 0,
        "order": 7,
        "position": 3,
        "sequence": 7
    },
    {
        "id": "bbe79e92-c56f-4e17-b5e4-6427c9fb7dce",
        "inning": 0,
        "order": 8,
        "position": 8,
        "sequence": 8
    },
    {
        "id": "2527770b-cf48-42b9-81fa-9323756fb311",
        "inning": 0,
        "order": 9,
        "position": 1,
        "sequence": 9
    },
    {
        "id": "5189f789-b0fd-426a-96ef-2e1706f12cfd",
        "inning": 5,
        "order": 9,
        "position": 1,
        "sequence": 10,
        "inning_half": "T"
    },
    {
        "id": "4d98a6ec-d2d4-4b23-8e4d-d44e0e828512",
        "inning": 5,
        "order": 9,
        "position": 11,
        "sequence": 11,
        "inning_half": "B"
    },
    {
        "id": "43862b88-c119-4625-b138-f3c5ea1b8b06",
        "inning": 6,
        "order": 9,
        "position": 1,
        "sequence": 12,
        "inning_half": "T"
    },
    {
        "id": "a6d72a5b-db58-48c4-9bda-7b8eb22ab5d0",
        "inning": 7,
        "order": 9,
        "position": 7,
        "sequence": 13,
        "inning_half": "T"
    },
    {
        "id": "abf9a77c-6b7f-40f8-a0ea-df8353ae7a8b",
        "inning": 7,
        "order": 6,
        "position": 1,
        "sequence": 14,
        "inning_half": "T"
    },
    {
        "id": "227d4963-6493-4bcc-ad19-8c66cf8fa9e0",
        "inning": 8,
        "order": 7,
        "position": 3,
        "sequence": 15,
        "inning_half": "T"
    },
    {
        "id": "b6840f51-9f1c-4f25-b40b-32e360397be9",
        "inning": 8,
        "order": 6,
        "position": 1,
        "sequence": 16,
        "inning_half": "T"
    },
    {
        "id": "9e798b78-22d9-44df-a4c3-fc9db6c0133d",
        "inning": 9,
        "order": 6,
        "position": 1,
        "sequence": 17,
        "inning_half": "T"
    },
    {
        "id": "bee1e3eb-c746-40c1-a129-e487e27312de",
        "inning": 9,
        "order": 6,
        "position": 11,
        "sequence": 18,
        "inning_half": "B"
    },
    {
        "id": "fb061c77-5253-4181-ad7b-c68ef18aa511",
        "inning": 9,
        "order": 6,
        "position": 11,
        "sequence": 19,
        "inning_half": "B"
    },
    {
        "id": "2cfe41eb-a26d-45b0-8b7c-22536e59db28",
        "inning": 9,
        "order": 7,
        "position": 11,
        "sequence": 20,
        "inning_half": "B"
    }
],

Play Outcomes

What are the valid outcome types and their definitions?

Here is a list of the outcome types and their definitions:

pitch - The last event logged was a pitch
steal - The last event logged was a steal
lineup - The last event logged was a lineup change
half_start - The last event logged is the start of an inning half
half_over - The last event logged is half inning is over
event_start - The game has begun
event_over - The game is over
runner_placed - The last event logged was a runner placed on second base to start an extra inning

<outcome type="pitch" current_inning="4" current_inning_half="T">

"outcome": {
    "type": "pitch",
    "current_inning": 4,
    "current_inning_half": "T",
    "count": {
        "balls": 1,
        "strikes": 2,
        "outs": 1,
        "inning": 4,
        "inning_half": "T",
        "half_over": false
    },

What are the valid pitch outcomes and their definitions?

Here is a list of the pitch outcomes and their definitions. This information can also be found in our glossary feed:

aBK = Balk
aCI = Catcher Interference
aD = Double
aDAD3 = Double - Adv 3rd
aDAD4 = Double - Adv Home
aFCAD2 = Fielders Choice - Adv 2nd
aFCAD3 = Fielders Choice - Adv 3rd
aFCAD4 = Fielders Choice - Adv Home
aHBP = Hit By Pitch
aHR = Homerun
aIBB = Intentional Walk
aKLAD1 = Strike Looking - Adv 1st
aKLAD2 = Strike Looking - Adv 2nd
aKLAD3 = Strike Looking - Adv 3rd
aKLAD4 = Strike Looking - Adv Home
aKSAD1 = Strike Swinging - Adv 1st
aKSAD2 = Strike Swinging - Adv 2nd
aKSAD3 = Strike Swinging - Adv 3rd
aKSAD4 = Strike Swinging - Adv Home
aROE = Reached On Error
aROEAD2 = Reached On Error - Adv 2nd
aROEAD3 = Reached On Error - Adv 3rd
aROEAD4 = Reached On Error - Adv Home
aROV = Reached on Violation
aS = Single
aSAD2 = Single - Adv 2nd
aSAD3 = Single - Adv 3rd
aSAD4 = Single - Adv Home
aSBAD1 = Sacrifice Bunt - Adv 1st
aSBAD2 = Sacrifice Bunt - Adv 2nd
aSBAD3 = Sacrifice Bunt - Adv 3rd
aSBAD4 = Sacrifice Bunt - Adv Home
aSFAD1 = Sacrifice Fly - Adv 1st
aSFAD2 = Sacrifice Fly - Adv 2nd
aSFAD3 = Sacrifice Fly - Adv 3rd
aSFAD4 = Sacrifice Fly - Adv Home
aT = Triple
aTAD4 = Triple - Adv Home
bAB = Enforced Ball
bABP = Ball - Automatic (Pitch Timer Violation - Pitcher)
bABC = Ball - Automatic (Pitch Timer Violation - Catcher)
bABS = Ball - Automatic (Shift Violation)
bB = Ball
bDB = Dirt Ball
bIB = Intentional Ball
bPO = Pitchout
kAK = Enforced Strike
kAKP = Strike - Automatic (Pitch Timer Violation)
kAKB = Strike - Automatic (Batter Timeout Violation)
kF = Foul Ball
kFT = Foul Tip
kKL = Strike Looking
kKS = Strike Swinging
oBI = Hitter Interference
oDT2 = Double - Tagged out at 2nd
oDT3 = Double - Out at 3rd
oDT4 = Double - Out at Home
oFC = Fielders Choice
oFCT2 = Fielders Choice - Out at 2nd
oFCT3 = Fielders Choice - Out at 3rd
oFCT4 = Fielders Choice - Out at Home
oFO = Fly Out
oGO = Ground Out
oKLT1 = Strike Looking - Out at 1st
oKLT2 = Strike Looking - Out at 2nd
oKLT3 = Strike Looking - Out at 3rd
oKLT4 = Strike Looking - Out at Home
oKST1 = Strike Swinging - Out at 1st
oKST2 = Strike Swinging - Out at 2nd
oKST3 = Strike Swinging - Out at 3rd
oKST4 = Strike Swinging - Out at Home
oLO = Line Out
oOBB = Out of Batters Box
oOP = Out on Appeal
oPO = Pop Out
oROET2 = Reached On Error - Out at 2nd
oROET3 = Reached On Error - Out at 3rd
oROET4 = Reached On Error - Out at Home
oSB = Sacrifice Bunt
oSBT2 = Sacrifice Bunt - Out at 2nd
oSBT3 = Sacrifice Bunt - Out at 3rd
oSBT4 = Sacrifice Bunt - Out at Home
oSF = Sacrifice Fly
oSFT2 = Sacrifice Fly - Out at 2nd
oSFT3 = Sacrifice Fly - Out at 3rd
oSFT4 = Sacrifice Fly - Out at Home
oST1 = Single - Tagged out at 1st
oST2 = Single - Out at 2nd
oST3 = Single - Out at 3rd
oST4 = Single - Out at Home
oTT3 = Triple - Tagged out at 3rd
oTT4 = Triple - Out at Home
rPABC = Ruling Pending, At Bat Continues
rPABO = Ruling Pending, At Bat Over

<pitch status="official" id="1f3f6dbf-2313-4863-b94a-2053e4e3ee3d" outcome_id="kF" 
       created_at="2023-09-20T19:01:20+00:00" updated_at="2023-09-20T19:01:46+00:00" 
       sequence_number="129" official="true">

"events": [
    {
        "status": "official",
        "id": "69969a8c-5926-4483-a04c-d5e627fe83ce",
        "outcome_id": "kKL",
        "created_at": "2023-09-20T18:12:09+00:00",
        "updated_at": "2023-09-20T18:14:42+00:00",
        "sequence_number": 3,
        "official": true,
        "type": "pitch",
        "wall_clock": {
            "start_time": "2023-09-20T18:11:54+00:00",
            "end_time": "2023-09-20T18:12:11+00:00"
        }

What are the valid runner outcomes and their definitions?

Here is a list of the runner outcomes and their definitions. This information can also be found in our glossary feed:

CK = Checked
ERN = Earned Run/RBI
eRN = Earned Run/No RBI
ERNu = Player earned run, team unearned/RBI
eRNu = Player earned run, team unearned/ no RBI
URN = Unearned Run/RBI
uRN = Unearned Run/No RBI
PO = Pickoff
POCSC = Catcher Pickoff
POCS2 = Pickoff/Caught Stealing 2nd
POCS3 = Pickoff/Caught Stealing 3rd
POCS4 = Pickoff/Caught Stealing Home
AD1 = Advance 1st
AD2 = Advance 2nd
AD3 = Advance 3rd
SB2 = Stole 2^nd
SB2E4E = Stole 2nd, error to home (earned)
SB2O2 = Stole 2nd, out at 2nd
SB2O3 = Stole 2nd, out at 3rd
SB2O4 = Stole 2nd, out at Home
SB3 = Stole 3rd
SB3E4E = Stole 3rd, error to home (earned)
SB3O3 = Stole 3rd, out at 3rd
SB3O4 = Stole 3rd, out at Home
SB4 = Stole Home
TO = Tag out 1st
TO2 = Tag out 2nd
TO3 = Tag out 3rd
TO4 = Tag out Home
FO1 = Force out 1st
FO2 = Force out 2nd
FO3 = Force out 3rd
FO4 = Force out Home
CS2 = Caught Stealing 2nd
CS3 = Caught Stealing 3rd
CS4 = Caught Stealing Home
CS2AD3 = Caught stealing 2nd, advanced 3rd
CS2AD4 = Caught stealing 2nd, advanced Home
CS2AD4u = Caught stealing 2nd, advanced Home, Unearned Run
CS3AD4 = Caught stealing 3rd, advanced Home
CS3AD4u = Caught stealing 3rd, advanced Home, Unearned Run
SB2AD3 = Steal 2nd, advanced 3rd
SB2AD4 = Steal 2nd, advanced Home
SB2AD4u = Steal 2nd, advanced Home, Unearned Run
SB2E2 = Stole 2nd, error to 2nd
SB2E3 = Stole 2nd, error to 3rd
SB2E4 = Stole 2nd, error to Home
SB3AD4 = Steal 3rd, advanced Home
SB3AD4u = Steal 3rd, advanced Home, Unearned Run
SB3E4 = Stole 3rd, error to Home
SB4u = Stole Home, Unearned Run
DI2 = Indifference to 2nd
DI3 = Indifference to 3rd
DO1 = Doubled off 1st
DO2 = Doubled off 2nd
DO3 = Doubled off 3rd
RI = Runner Interference
OOA = Out on Appeal
OBP = Out of Base Path
HBB = Hit by Batted Ball

 <runners>
        <runner starting_base="0" ending_base="4" out="false" outcome_id="ERN" 
        preferred_name="Nelson" first_name="Nelson" last_name="Velázquez" 
        jersey_number="17" id="ea7b7c30-a1e8-4a30-abd6-dd777ab75b35"/>
      <runner outcome_id="URN" starting_base="1" ending_base="4" out="false" 
        preferred_name="Bobby" first_name="Robert" last_name="Witt Jr." 
        jersey_number="7" id="0f20f69e-28c9-4fb4-8b1e-cde154780682">
            <description>Bobby Witt Jr. scores.</description>
      </runner>
      <runner outcome_id="ERN" starting_base="3" ending_base="4" out="false" 
        preferred_name="Maikel" first_name="Maikel" last_name="Garcia" 
        jersey_number="11" id="3c07814a-966e-4358-82f5-f59c32af8c94">
            <description>Maikel Garcia scores.</description>
      </runner>
</runners>

"runners": [
    {
        "starting_base": 0,
        "ending_base": 4,
        "out": false,
        "outcome_id": "ERN",
        "preferred_name": "Nelson",
        "first_name": "Nelson",
        "last_name": "Velázquez",
        "jersey_number": "17",
        "id": "ea7b7c30-a1e8-4a30-abd6-dd777ab75b35"
    },
    {
        "starting_base": 1,
        "ending_base": 4,
        "out": false,
        "outcome_id": "URN",
        "description": "Bobby Witt Jr. scores.",
        "preferred_name": "Bobby",
        "first_name": "Robert",
        "last_name": "Witt Jr.",
        "jersey_number": "7",
        "id": "0f20f69e-28c9-4fb4-8b1e-cde154780682"
    },
    {
        "starting_base": 3,
        "ending_base": 4,
        "out": false,
        "outcome_id": "ERN",
        "description": "Maikel Garcia scores.",
        "preferred_name": "Maikel",
        "first_name": "Maikel",
        "last_name": "Garcia",
        "jersey_number": "11",
        "id": "3c07814a-966e-4358-82f5-f59c32af8c94"
    }
]

Pitch Zone, Speed, Types & Location

You are tracking pitch speed and location. Can I expect this information to show up for all pitches and all games?

Pitch speed and location are expected for all games played in all 30 MLB home venues. However, these data points may not be present for all Spring Training venues or for games played in non-MLB venues (example: Williamsport, PA – ID 2c26f3ab-4d19-4b64-93b0-3279b13d7314).

What do the pitch zone attributes represent, and why are there more than one?

We have two pitch zone attributes available (pitch_zone & zone), and it is important to distinguish between the two.

pitcher - pitch_zone
The pitch_zone attribute is from the pitcher’s point of view and divides the pitch location into 13 zones. The strike zone is represented by zone 1-9. This data is available beginning in the 2013 season.

mlb_pitch_data - zone
The zone attribute within mlb_pitch_data is from the batter’s point of view and divides the pitch location into 14 zones. The strike zone is represented by zone 1-9. This data is available beginning in the 2020 season.

You are tracking pitch x/y location. How can I expect this information to appear?

The pitch x/y values will be a percentage distance from the center of the strike zone, in positive or negative values from approximately -300% to +300% for x, and approximately -200% to +200% for y.

For pitch_x, -100 represents the right edge of the strike zone (zones 3, 6, & 9) and +100 represents the left edge of the strike zone (zones 1, 4, and 7). The middle zones (2, 5, and 8) are -35 to +35.

Which valid pitch types you track and what are their definitions?

Here is a list of the pitch types and their definitions. This information can also be found in our glossary feed:

FA = Fastball
SI = Sinker
CT = Cutter
CU = Curveball
SL = Slider
CH = Changeup
KN = Knuckleball
SP = Splitter
SC = Screwball
FO = Forkball
EP = Eephus
IB = Intentional Ball
PI = Pitchout
Null (empty)

Hit Types & Location

What are the valid hit types I can expect to appear?

The following hit types can be displayed:

GB – Ground ball
FB – Fly ball
LD – Line drive
PU - Popup

<pitch hit_location="16" hit_type="GB" status="official" id="0da18b87-c514-4ac4-b0ca-2a0a0e88131c" 
       outcome_id="aROE" created_at="2023-09-20T18:19:29+00:00" updated_at="2023-09-20T18:19:45+00:00" 
       sequence_number="22" official="true">

You are tracking hit location. Do you have a diagram showing the field and its corresponding zones?

We break the field up into 35 zones. Here is an illustration:

What are the x,y coordinates for on-field hit location?

Here are the coordinates for each MLB base (x,y):

1B – (150,175)
2B – (125,150)
3B – (100,175)
Pitching Rubber – (125,177)
Back tip of Home Plate – (125,200)

Transaction Codes & Types

What are the valid `transaction_code` and `transaction_type` values?

Here is a list of the valid transaction codes and types:

ACT - Activated
MIN - Assigned to Minors
CL - Claimed
CEXP - Contract Expired
CEXT - Contract Extension
DEC - Deceased
FA - Declared Free Agency
DFA - Designated for Assignment
DRA - Drafted
R5 - Drafted Via Rule 5 Draft
SUS - League Suspension
ABS - Leave of Absence
NRI - Non-Roster Invitee
NWT - Not with Team
TRAN - Other Transaction
IL10 - Placed on the 10-Day Injury List
IL60 - Placed on the 60-Day Injury List
IL7 - Placed on the 7-Day Injured List
BRV - Placed on Bereavement List
FME - Placed on Family Medical Emergency Leave
PL - Placed on Paternity Leave
RST - Placed on Restricted List
IL15 - Placed on the 15-Day Injury List
RSGN - Re-Signed
REC - Recalled from Minors
RRST - Reinstated from Restricted List
RSUS - Reinstated from Suspension
REL - Released
RET - Retired
EDRA - Selected in Expansion Draft
SGN - Signed
TSUS - Team Suspension
TRD - Traded
WA - Waived

Pitch / Hit Data Descriptions

What are the valid values for `mlb_pitch_data – code` and what are their descriptions?

Here is a list of the valid pitch codes and their descriptions

FA - Fastball
FF - Four-seam FB
FC - Cutter
SI - Sinker
FS - Splitter
FO - Forkball
CH - Changeup
SC - Screwball
SL - Slider
CU - Curveball
CS - Slow Curve
KC - Knuckle Curve
SV - Slurve
ST - Sweeper
FL - Slutter
GY - Gyroball
KN - Knuckleball
EP - Eephus Pitch
IN - Intentional Ball
PO - Pitchout
AB - Automatic Ball
AS - Automatic Strike
NP - No Pitch
UN - Unknown

<mlb_pitch_data speed="79.2" strike_zone_top="3.5" strike_zone_bottom="1.64" zone="8" 
                code="CH" description="Changeup">

What are the definitions for the data points within `mlb_hit_data`?

Here is a list of the data point descriptions:

launch_speed - Measured speed of the hit ball in miles per hour
launch_angle - Vertical angle relative to the horizon at which the hit was launched
total_distance - Total distance a ball traveled in feet
trajectory - The trajectory description of a hit ball
hardness - Soft, Medium, or Hard description
location - Positional number of ball location
coordinates - Coordinates entered by operator in pressbox of where the ball is fielded. Based on 250x250 field graphic, where 0,0 is in the upper left corner, in very deep left field, and 250,250 is in the lower right corner, in foul territory between 1B and home plate. The fields are centered in that space, the x=125 axis runs through the middle of 2B, the pitcher’s mound and home plate; the 1B and 3B bases are roughly aligned on the y=175 line.
coord_x - X coordinate marked by operator of where the ball was fielded
coord_y - Y coordinate marked by operator of where the ball was fielded

What are the definitions for the data points within `mlb_pitch_data`?

Here is a list of the data point descriptions:

break_angle - Degrees clockwise (batter’s view) that the plane ofthe pitch deviates from the vertical.
break_length - Max distance (in inches) that the pitch separates from the straight line between pitch start and pitch end
break_y - Distance (in feet) from home plate where the break is greatest
code - The pitch type classification code (see above for a list of values).
coordinate a_x - Ball acceleration on the x axis.
coordinate a_y - Ball acceleration on the y axis.
coordinate a_z - Ball acceleration on the z axis.
coordinate pfx_x - Horizontal movement of the ball in inches.
coordinate pfx_z - Vertical movement of the ball in inches.
coordinate p_x - Horizontal position in feet of the ball as it crosses the front axis of home plate.
coordinate p_z - Vertical position in feet above home plate of the ball as it crosses the front axis of home plate.
coordinate v_x0 - Velocity of the ball from the x axis.
coordinate v_y0 - 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.
coordinate v_z0 - Velocity of the ball from the z axis.
coordinate x - X coordinate where pitch crossed front of home plate.
coordinate y - Y coordinate where pitch crossed front of home plate.
coordinate x0 - Coordinate location of the ball at the point it was released from the pitchers hand on the x axis (time = 0).
coordinate y0 - Coordinate location of the ball at the point it was released from the pitchers hand on the y axis (time = 0).
coordinate z0 - Coordinate location of the ball at the point it was released from the pitchers hand on the z axis (time = 0).
description - Text description of the pitch type.
end_speed - Speed in MPH of the ball as it crosses the front edge of home plate (0,0 in the x axis).
extension - 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.
plate_time - Time from pitchers release until the ball is projected to reach the back tip of home plate or struck by the bat.
spin_direction - 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.
spin_rate - Rate of spin on the ball after it was released by pitcher. RPMs.
start_speed - Speed in MPH of the ball at 50 feet in front of homeplate.
strike_zone_bottom - Distance in inches from ground to bottom of batter strike zone.
strike_zone_top - Distance in inches from ground to top of batter strike zone.

What are the valid pitch status values?

Here is a list of the pitch status values:

official
under review
overturned
upheld

Standings & Rankings

What are the valid `clinched` playoff values for a team in the Rankings endpoint?

Here is a list of the clinched values and their definitions:

division = The team has clinched the division title
division_homefield = The team has clinched the division title as well as home field advantage
playoff_berth = The team has clinched a berth into the postseason
wildcard = The team has clinched a wildcard berth
eliminated = The team has been eliminated from playoff contention

<division alias="W" name="West" id="dd76b332-7cfa-45f0-bed0-a6944d924a61">
  <team name="Dodgers" market="Los Angeles" abbr="LAD" id="ef64da7f-cfaf-4300-87b0-9313386b977c">
    <rank division="1" league="1" clinched="division"/>
  </team>
  <team name="Padres" market="San Diego" abbr="SD" id="d52d5339-cbdd-43f3-9dfa-a42fd588b9a3">
    <rank division="2" league="4" clinched="wildcard"/>
  </team>
  <team name="Diamondbacks" market="Arizona" abbr="AZ" id="25507be1-6a68-4267-bd82-e097d94b359b">
    <rank division="3" league="6"/>
  </team>
  <team name="Giants" market="San Francisco" abbr="SF" id="a7723160-10b7-4277-a309-d8dd95a8ae65">
    <rank division="4" league="10" clinched="eliminated"/>
  </team>
  <team name="Rockies" market="Colorado" abbr="COL" id="29dd9a87-5bcc-4774-80c3-7f50d985068b">
    <rank division="5" league="14" clinched="eliminated"/>
  </team>
</division>

{
  "alias": "NL",
  "name": "National League",
  "id": "fbe91704-36df-4e7c-864a-06d236425999",
  "divisions": [
    {
      "alias": "W",
      "name": "West",
      "id": "dd76b332-7cfa-45f0-bed0-a6944d924a61",
      "teams": [
        {
          "name": "Dodgers",
          "market": "Los Angeles",
          "abbr": "LAD",
          "id": "ef64da7f-cfaf-4300-87b0-9313386b977c",
          "rank": {
            "division": 1,
            "league": 1,
            "clinched": "division"
          }
        },
        {
          "name": "Padres",
          "market": "San Diego",
          "abbr": "SD",
          "id": "d52d5339-cbdd-43f3-9dfa-a42fd588b9a3",
          "rank": {
            "division": 2,
            "league": 4,
            "clinched": "wildcard"
          }
        },
        {
          "name": "Diamondbacks",
          "market": "Arizona",
          "abbr": "AZ",
          "id": "25507be1-6a68-4267-bd82-e097d94b359b",
          "rank": {
            "division": 3,
            "league": 6
          }
        },
        {
          "name": "Giants",
          "market": "San Francisco",
          "abbr": "SF",
          "id": "a7723160-10b7-4277-a309-d8dd95a8ae65",
          "rank": {
            "division": 4,
            "league": 10,
            "clinched": "eliminated"
          }
        },
        {
          "name": "Rockies",
          "market": "Colorado",
          "abbr": "COL",
          "id": "29dd9a87-5bcc-4774-80c3-7f50d985068b",
          "rank": {
            "division": 5,
            "league": 14,
            "clinched": "eliminated"
          }
        }
      ]
    },

Roster Updates

How do you handle players who are scheduled to start a future game, but are not currently on the team profile?

There is a case where a team has set a pitcher as a probable starter, but he is not on the profile. When this occurs, we will update the player, denoting that he has not officially joined the squad, but is scheduled to join. The entry will be found in the Team Profile feed. We will include all the information about the player including the date he is expected to join to the team officially. Here is a sample of what this will look like:

<expected_players>
    <player id="29a80d91-946d-4701-af7d034850bdef00" status="A" position="IF" primary_position="2B" first_name="James" last_name="Dozier" preferred_name="Brian" jersey_number="2" full_name="Brian Dozier" mlbam_id="572821" height="71" weight="200" throw_hand="R"
        bat_hand="R" college="Southern Mississippi" high_school="Itawamba Agricultural, Fulton, MS" birthdate="1987-05-15" birthstate="MS" birthcountry="USA" birthcity="Tupelo" pro_debut="2012-05-07" updated="2017-02-14T15:15:47Z" expected_date="2017-02-14"
    />
</expected_players>

Spring Training

What Spring Training games will have full pitch-by-pitch data?

We provide full pitch-by-pitch data for games at MLB venues and the below Spring Training venues. Please note that these games have the possibility of failover to Sportradar data entry. If this is necessary, we provide boxscore coverage until the game is over.

Cactus League (7)	Grapefruit League (11)
Peoria (SDP/SEA)	Clearwater (PHI)
Salt River (COL/ARI)	Fort Myers (MIN)
Surprise (KCR/TEX)	Northport (ATL)
Mesa (CHC)	Tampa (NYY)
Glendale (CHW/LAD)	Bradenton (PIT)
Maryvale (MIL)	Palm Beach (HOU)
Goodyear (CIN/CLE)	St. Lucie (NYM)
	Lakeland (DET)
	Fort Myers (BOS)
	Dunedin (TOR)
	Jupiter (MIA/STL)

Why does player X not appear in the Team Profile endpoint?

The Team Profile endpoint returns players currently on the 40-man roster. Spring Training non-roster invitees will ONLY appear on game-level endpoints and ONLY if they play in a game.

All-Star Game

How do I locate the All-Star game?

The game can be found in the League Schedule or Daily Schedule endpoint. In the League Schedule path use AST in the season parameter to retrieve the All-Star game only. For example:

League Schedule - mlb/trial/v8/en/games/2024/AST/schedule
Daily Schedule - mlb/trial/v8/en/games/2024/07/16/schedule

Every game-centric feed (e.g. Play-by-Play, Game Summary, Push Events, etc) can be accessed during the game.

Click here for for a Game Summary or Game Play-by-Play sample of the 2024 game.

<league xmlns="http://feed.elasticstats.com/schema/baseball/v8/schedule.xsd" alias="MLB" name="Major League Baseball" id="2fa448bc-fc17-4d3d-be03-e60e080fdc26">
    <daily-schedule date="2025-07-15">
        <games>
            <game id="ba541933-6cb4-4580-bd00-cb0e37f82751" status="scheduled" coverage="full" game_number="1" day_night="N" scheduled="2025-07-16T00:00:00+00:00" home_team="3bbb3b39-b5cb-4fc9-bd22-522521f0f329" away_team="dd59d49e-caee-4443-9220-f05d0d9bd1e1" parent_id="34e4cbbe-0086-4fad-bb08-840cbcfcabf0" double_header="false" entry_mode="STOMP" reference="778566">
                <venue name="Truist Park" market="Atlanta" capacity="41149" surface="grass" address="755 Battery Avenue" city="Atlanta" state="GA" zip="30339" country="USA" id="3ca8b577-5844-42ed-81a5-bd5d5cbe350c" field_orientation="S" stadium_type="outdoor" time_zone="US/Eastern">
                    <location lat="33.890672" lng="-84.467641"/>
                </venue>
                <home name="National League" market="NL" abbr="NL" id="3bbb3b39-b5cb-4fc9-bd22-522521f0f329" win="0" loss="0"/>
                <away name="American League" market="AL" abbr="AL" id="dd59d49e-caee-4443-9220-f05d0d9bd1e1" win="0" loss="0"/>
                <broadcasts>
                    <broadcast network="FOX" type="TV" locale="National"/>
                </broadcasts>
            </game>
        </games>
    </daily-schedule>
</league>

{
    "league": {
        "alias": "MLB",
        "name": "Major League Baseball",
        "id": "2fa448bc-fc17-4d3d-be03-e60e080fdc26"
    },
    "date": "2025-07-15",
    "games": [
        {
            "id": "ba541933-6cb4-4580-bd00-cb0e37f82751",
            "status": "scheduled",
            "coverage": "full",
            "game_number": 1,
            "day_night": "N",
            "scheduled": "2025-07-16T00:00:00+00:00",
            "home_team": "3bbb3b39-b5cb-4fc9-bd22-522521f0f329",
            "away_team": "dd59d49e-caee-4443-9220-f05d0d9bd1e1",
            "parent_id": "34e4cbbe-0086-4fad-bb08-840cbcfcabf0",
            "double_header": false,
            "entry_mode": "STOMP",
            "reference": "778566",
            "venue": {
                "name": "Truist Park",
                "market": "Atlanta",
                "capacity": 41149,
                "surface": "grass",
                "address": "755 Battery Avenue",
                "city": "Atlanta",
                "state": "GA",
                "zip": "30339",
                "country": "USA",
                "id": "3ca8b577-5844-42ed-81a5-bd5d5cbe350c",
                "field_orientation": "S",
                "stadium_type": "outdoor",
                "time_zone": "US/Eastern",
                "location": {
                    "lat": "33.890672",
                    "lng": "-84.467641"
                }
            },
            "home": {
                "name": "National League",
                "market": "NL",
                "abbr": "NL",
                "id": "3bbb3b39-b5cb-4fc9-bd22-522521f0f329",
                "win": 0,
                "loss": 0
            },
            "away": {
                "name": "American League",
                "market": "AL",
                "abbr": "AL",
                "id": "dd59d49e-caee-4443-9220-f05d0d9bd1e1",
                "win": 0,
                "loss": 0
            },
            "broadcasts": [
                {
                    "network": "FOX",
                    "type": "TV",
                    "locale": "National"
                }
            ]
        }
    ],
    "_comment": "Generation started @ 2025-01-28 21:22:34 UTC ended @ 2025-01-28 21:22:34 UTC"
}

Is the All-Star game covered in realtime?

Yes. The game is covered in realtime, including the same level of team and player statistics as a regular season game (including Statcast data).

When are the All-Star rosters set?

All-Star rosters will be available within 24 hours after they are announced by MLB. Sportradar updates each roster with any additions from the announcement of the original starters to the replacement players.

Please note that we only provide game rosters (not team rosters) for each game. Request the Game Summary or Daily Summary endpoint prior to the game to receive rosters.

What if the game ends in a tie?

In the case of a tie, the All-Star game will be decided by a Home Run Derby. Should this happen, the data will appear as follows in our MLB API:

The game will be moved from inprogress to odelay during the derby
The game will result in a tie (example: 3-3)
The tiebreaker of the home run derby will not be shown in any feed
There will not be an indication of who won the Home Run Derby portion of the event

Umpire Assignments

What are the valid umpire assignments and their definitions?

Here is a list of the umpire assignments and their definitions:

HP = Home plate umpire
1B = 1st base umpire
2B = 2nd base umpire
3B = 3rd base umpire
LF = Left field umpire
RF = Right field umpire

Seasonal Statistics

When can I expect seasonal data to update in the Player Profile and Seasonal Statistics endpoints?

Most statistics will be available once a game is finalized, but the following seasonal stats are updated each morning during the MLB season.

Position Player WAR (war)
Batting WAR (bwar)
Baserunning WAR (brwar)
Fielding WAR (fwar)
Weighted Grounded into Double Plays (wgdp)
Weighted On-Base Average (woba)
Weighted Runs Above Average (wraa)
ERA- (era_minus)
Pitching WAR (war)
Fielding Independent Pitching (fip)
Expected Fielding Independent Pitching (xfip)

Please note that these statistics are available per team and season only. They are not available as a cumulative total (season.totals) should a player appear for more than one team in a season.

How are statistics handled for players who switch teams mid-season?

The player profile feed divides statistics by team, so there would be a relevant team entry for each team that the player played on. As well, we provide overall total statistics that covers the whole season.

Why are some data points missing for years prior to 2018?

In version 6.5 we added several data points that we previously have not collected data for. Those statistics will appear only for 2018 forward.

Statcast Data

What is Statcast data and how can I gain access?

See our Statcast Data section for info on this package.

What metrics do you track in the Event Tracking endpoint, and how far back does this data go?

Event tracking is available beginning in the 2022 postseason. Click here for a comprehensive list of metrics and their definitions.

Ohtani Rule

How does Sportradar handle the amended 5.11(a) DH rule, aka the Shohei Ohtani rule?

    "lineup": [
      {
        "id": "80de60c9-74e3-4a50-b128-b3dc7456a254",
        "inning": 0,
        "order": 0,
        "position": 1,
        "sequence": 1
      },
      {
        "id": "80de60c9-74e3-4a50-b128-b3dc7456a254",
        "inning": 0,
        "order": 1,
        "position": 10,
        "sequence": 2
      },

In the event the starting pitcher will bat for himself, the player will be considered two separate people on his team’s opening lineup card, in accordance with the amended rule.

In the starting lineup node, the starting pitcher will appear twice, once as position 1 (Pitcher) and once as position 10 (Designated Hitter).

If the starting pitcher is replaced, he can continue as the Designated Hitter, and if the Designated Hitter is replaced, he can continue as the pitcher (but can no longer hit for himself). When he is substituted out as a pitcher and remains as a designated hitter, there will be two substitution events.

ID Handling

Other sports like NBA and NFL have SR_IDs available for entities such as teams and players. How can I access those SR_IDs for MLB?

We do not support SR_IDs at this time within the MLB API. Our current suggestion is to utilize two of our Odds Comparison Prematch v2 feeds to retrieve this data. For players, please use the Player Mappings endpoint. For games, please use the Sport Event Mappings endpoint. Please note that these feeds will have IDs for a variety of sports that Sportradar covers.

Data Failover

What events will be logged during a failover game?

During a failover game, you should expect a minimized data point set.

Event Types

pitch - The last event logged was a pitch
steal - The last event logged was a steal
lineup - The last event logged was a lineup change
half_start - The last event logged is the start of an inning half
half_over - The last event logged is half inning is over
event_start - The game has begun
event_over - The game is over

Event Data Points

Current Batter
Current Pitcher
Batter handedness
Pitcher handedness
Starting Base
Ending Base
Pitch Outcome
Runner Outcome
Putouts
Assists
Errors