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 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.

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

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.

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)

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

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

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

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"
    }
]

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

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.

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.

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

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

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)

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

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"
          }
        }
      ]
    },

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>

Do you cover the MLB All Star Game?

We cover the MLB All Star game. The game will appear in the regular season schedule. Team rosters will not be available from the Team Profile feed. All roster information can be found in the Daily Summary or Game Summary feeds for the All Star Game.

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

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.

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.