Docs
Coverage MatrixDocumentationRelease LogLog InContact Us
Coverage MatrixDocumentationRelease LogLog InContact Us

MLB FAQs

Frequently asked questions for MLB v7.

Click on the categories below or browse questions on the right panel.

Categories

.

Coverage

How is each MLB game covered?

Coverage information for MLB can be found here.


Integration


What format are date fields presented in?

When we present date only values we present these in the ISO 8601 standard format.

ex: 2023-04-03

We use these for attributes that have date and no time (such as birthdate). For more information: https://en.wikipedia.org/wiki/ISO_8601

What format are the date/time fields presented in?

All of our Date/Time attributes are in UTC, presented in the ISO 8601 standard format.

ex: 2023-04-03T18:15:00+00:00

For more information: https://en.wikipedia.org/wiki/ISO_8601


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

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
  • IF = Infield
  • 1B = First base
  • 2B = Second base
  • 3B = Third Base
  • SS = Shortstop
  • OF = Outfield
  • 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
<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
  • 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
  • bB = Ball
  • bDB = Dirt Ball
  • bIB = Intentional Ball
  • bPO = Pitchout
  • kAK = Enforced Strike
  • 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 2nd
  • 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
  • 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 positive 300% for x, and approximately -200% to positive 200% for y.


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
  • Other

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 Updates


What are the valid values for the Playoff Status for a team?

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.

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 coverage for games at MLB venues along with 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.

Florida Grapefruit League
  • Roger Dean Stadium (Miami and St. Louis)
  • Publix Field at Joker Marchant Stadium (Detroit)
  • CenturyLink Sports Complex (Minnesota)
  • Clover Park (New York Mets)
  • George M. Steinbrenner Field (New York Yankees)
  • BayCare Ballpark (Philadelphia)
  • LECOM Park (Pittsburgh)
  • TD Ballpark (Toronto)
Arizona Cactus League
  • Salt River Fields at Talking Stick (Arizona and Colorado)

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/v7/en/games/2023/AST/schedule
  • Daily Schedule - mlb/trial/v7/en/games/2023/07/11/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 Play-by-Play sample of the 2022 game.

<league xmlns="http://feed.elasticstats.com/schema/baseball/v7/schedule.xsd" alias="MLB" name="Major League Baseball" id="2fa448bc-fc17-4d3d-be03-e60e080fdc26">
    <season-schedule id="35ed1eb2-5b9b-4816-8a6c-7e2a3f50488e" year="2022" type="AST">
        <games>
            <game id="7a7a0a1b-3f9b-4773-90af-8875041170f2" status="closed" coverage="full" game_number="1" day_night="D" scheduled="2022-07-20T00:00:00+00:00" home_team="3bbb3b39-b5cb-4fc9-bd22-522521f0f329" away_team="dd59d49e-caee-4443-9220-f05d0d9bd1e1" attendance="52518" duration="3:11" double_header="false" entry_mode="STOMP" reference="663466">
                <venue name="Dodger Stadium" market="Los Angeles" capacity="56000" surface="grass" address="1000 Vin Scully Avenue" city="Los Angeles" state="CA" zip="90012" country="USA" id="66a19c3d-24fe-477d-bee7-c6ef1b98352f" field_orientation="NE" stadium_type="outdoor">
                    <location lat="34.0745409" lng="-118.2408881"/>
                </venue>
                <home name="National League" market="NL" abbr="NL" id="3bbb3b39-b5cb-4fc9-bd22-522521f0f329"/>
                <away name="American League" market="AL" abbr="AL" id="dd59d49e-caee-4443-9220-f05d0d9bd1e1"/>
                <broadcast network="FOX"/>
            </game>
        </games>
    </season-schedule>
</league>

{
    "league": {
        "alias": "MLB",
        "name": "Major League Baseball",
        "id": "2fa448bc-fc17-4d3d-be03-e60e080fdc26"
    },
    "season": {
        "id": "35ed1eb2-5b9b-4816-8a6c-7e2a3f50488e",
        "year": 2022,
        "type": "AST"
    },
    "games": [
        {
            "id": "7a7a0a1b-3f9b-4773-90af-8875041170f2",
            "status": "closed",
            "coverage": "full",
            "game_number": 1,
            "day_night": "D",
            "scheduled": "2022-07-20T00:00:00+00:00",
            "home_team": "3bbb3b39-b5cb-4fc9-bd22-522521f0f329",
            "away_team": "dd59d49e-caee-4443-9220-f05d0d9bd1e1",
            "attendance": 52518,
            "duration": "3:11",
            "double_header": false,
            "entry_mode": "STOMP",
            "reference": "663466",
            "venue": {
                "name": "Dodger Stadium",
                "market": "Los Angeles",
                "capacity": 56000,
                "surface": "grass",
                "address": "1000 Vin Scully Avenue",
                "city": "Los Angeles",
                "state": "CA",
                "zip": "90012",
                "country": "USA",
                "id": "66a19c3d-24fe-477d-bee7-c6ef1b98352f",
                "field_orientation": "NE",
                "stadium_type": "outdoor",
                "location": {
                    "lat": "34.0745409",
                    "lng": "-118.2408881"
                }
            },
            "home": {
                "name": "National League",
                "market": "NL",
                "abbr": "NL",
                "id": "3bbb3b39-b5cb-4fc9-bd22-522521f0f329"
            },
            "away": {
                "name": "American League",
                "market": "AL",
                "abbr": "AL",
                "id": "dd59d49e-caee-4443-9220-f05d0d9bd1e1"
            },
            "broadcast": {
                "network": "FOX"
            }
        }
    ],
    "_comment": "Generation started @ 2023-04-03 14:11:01 UTC ended @ 2023-04-03 14:11:01 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 result in a tie (example: 3-3)
  • The tiebreaker of a 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)

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

Broadcast Availability


How can I receive multiple broadcasts for a game?

To access multiple broadcasts for an MLB game, alter your syntax from v7 to v7.1 for RESTful schedule endpoints. This additional broadcast info is readily available, but version 7.1 is undocumented.

**v7 Snippet:**

broadcast:

{ network: "BSSE" }
,
______________________________________________________________
**v7.1 Snippet:**

broadcasts: [

{ network: "BSSE", type: "TV", locale: "Home", channel: "649" }
,

{ network: "BSWI", type: "TV", locale: "Away", channel: "661" }
],

🙋

More questions?

Reach out to [email protected] for further assistance.








© Sportradar AG, St. Gallen, Switzerland