Skip to main content

MLB — MLB Stats API — Draft

mlb_draft​

GET /api/v1/draft/{year} — draft results for a year (optionally one round).

Endpoint URL: GET https://statsapi.mlb.com/api/v1/draft/{year}

Valid URL: https://statsapi.mlb.com/api/v1/draft/2024?limit=100

API ParameterPythonPatternRequiredNullableDescription
yearyearYyear path parameter.
roundround_Yround query parameter.
teamIdteam_idYteamId query parameter.
playerIdplayer_idYplayerId query parameter.
limitlimitYMaximum number of items to return.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_draft(year=2024)

mlb_draft_latest​

View latest player drafted, endpoint best used when draft is currently open.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/draft/{year}/latest

Valid URL: https://statsapi.mlb.com/api/v1/draft/2023/latest

API ParameterPythonPatternRequiredNullableDescription
yearyearYyear path parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
numberInt64Jersey number.
next_upStringIndicates whether this draft slot is the next pick to be made in the current draft.
pick_pick_roundStringDraft round in which this pick was made (e.g., '1', '2', 'CB-A' for competitive balance).
pick_pick_numberInt64Overall pick number of this selection counting sequentially across all rounds of the draft.
pick_display_pick_numberInt64The formatted overall pick number displayed publicly for this draft selection.
pick_round_pick_numberInt64Pick number within the specific draft round (i.e., the Nth pick in that round).
pick_signing_bonusStringReported or slotted signing bonus amount associated with this draft pick.
pick_home_cityStringCity of the draftee's listed home address at the time of the draft.
pick_home_stateStringState or province of the draftee's listed home address at the time of the draft.
pick_home_countryStringCountry of the draftee's listed home address at the time of the draft.
pick_school_nameStringName of the high school or college the draftee attended before being drafted.
pick_school_school_classStringAcademic class or level of the draftee at their school (e.g., High School, Junior, Senior).
pick_school_cityStringCity of the high school or college the draftee attended before being drafted.
pick_school_countryStringCountry of the school the draftee attended.
pick_school_stateStringState of the school the draftee attended.
pick_headshot_linkStringURL to the headshot image of the drafted player on the MLB Stats API CDN.
pick_person_idInt64Unique MLB Stats API (MLBAM) identifier for the drafted player.
pick_person_full_nameStringPlayer's complete display name as used throughout the MLB Stats API.
pick_person_linkStringRelative URL path to the player's resource in the MLB Stats API.
pick_person_first_nameStringThe player's legal or preferred first name.
pick_person_last_nameStringThe player's legal or preferred last name.
pick_person_birth_dateStringDate of birth of the drafted player in ISO 8601 format.
pick_person_current_ageInt64Age of the drafted player in years at the time of the data retrieval.
pick_person_birth_cityStringCity where the drafted player was born.
pick_person_birth_state_provinceStringState or province where the drafted player was born.
pick_person_birth_countryStringCountry where the drafted player was born.
pick_person_heightStringPlayer's height in feet-and-inches notation (e.g., 6' 2").
pick_person_weightInt64Player's weight in pounds as recorded by the MLB Stats API.
pick_person_activeBooleanBoolean flag indicating whether the drafted player is currently on an active MLB roster.
pick_person_primary_position_codeStringNumeric or short code identifying the player's primary fielding position.
pick_person_primary_position_nameStringFull name of the player's primary fielding position (e.g., Shortstop, Center Field).
pick_person_primary_position_typeStringBroad classification of the player's position role (e.g., Pitcher, Infielder, Outfielder).
pick_person_primary_position_abbreviationStringShort abbreviation for the player's primary fielding position (e.g., SS, CF, SP).
pick_person_use_nameStringThe first name or nickname the player prefers to use publicly.
pick_person_use_last_nameStringThe last name the player prefers to use publicly, which may differ from the legal last name.
pick_person_middle_nameStringThe player's middle name as recorded by the MLB Stats API.
pick_person_boxscore_nameStringAbbreviated name format used for the player on official MLB box scores.
pick_person_genderStringRecorded gender of the drafted player.
pick_person_is_playerBooleanBoolean flag indicating whether this person is classified as an active player in the MLB Stats API.
pick_person_is_verifiedBooleanBoolean flag indicating whether the player's profile has been verified by MLB.
pick_person_draft_yearInt64The MLB draft year in which this player was originally selected.
pick_person_bat_side_codeStringSingle-letter code for the player's batting handedness (e.g., R, L, S for switch).
pick_person_bat_side_descriptionStringFull description of the player's batting side (e.g., Right, Left, Switch).
pick_person_pitch_hand_codeStringSingle-letter code for the player's pitching handedness (e.g., R, L, S).
pick_person_pitch_hand_descriptionStringFull description of the player's pitching hand (e.g., Right, Left, Switch).
pick_person_name_first_lastStringPlayer's display name in first-last format, typically matching the broadcast name.
pick_person_name_slugStringURL-safe slug derived from the player's name for use in web links.
pick_person_first_last_nameStringPlayer's name formatted as first name followed by last name.
pick_person_last_first_nameStringPlayer's name formatted as last name followed by first name.
pick_person_last_init_nameStringPlayer's name formatted as last name followed by first initial.
pick_person_init_last_nameStringPlayer's name formatted as first initial followed by last name (e.g., J. Smith).
pick_person_full_fml_nameStringPlayer's full name in first-middle-last order as recorded by the MLB Stats API.
pick_person_full_lfm_nameStringPlayer's full name in last-first-middle order as recorded by the MLB Stats API.
pick_person_strike_zone_topFloat64Upper boundary of the player's personalized strike zone in feet from the ground.
pick_person_strike_zone_bottomFloat64Lower boundary of the player's personalized strike zone in feet from the ground.
pick_person_xref_idsStringSerialized cross-reference identifiers linking the player to external data systems.
pick_team_spring_league_idInt64MLB Stats API identifier for the team's spring training league.
pick_team_spring_league_nameStringFull name of the spring training league the team belongs to.
pick_team_spring_league_linkStringRelative URL path to the spring training league resource in the MLB Stats API.
pick_team_spring_league_abbreviationStringAbbreviation for the spring training league the team participates in (e.g., Cactus, Grapefruit).
pick_team_all_star_statusStringAll-Star game affiliation status of the team (e.g., American League, National League).
pick_team_idInt64Unique MLB Stats API identifier for the team that made this draft pick.
pick_team_nameStringFull official name of the MLB team that made this pick (e.g., New York Yankees).
pick_team_linkStringRelative URL path to the team resource in the MLB Stats API.
pick_team_seasonInt64MLB season year for which this team's metadata snapshot applies.
pick_team_venue_idInt64MLB Stats API identifier for the team's regular-season home ballpark.
pick_team_venue_nameStringName of the team's regular-season home ballpark (e.g., Yankee Stadium).
pick_team_venue_linkStringRelative URL path to the team's regular-season home venue in the MLB Stats API.
pick_team_spring_venue_idInt64MLB Stats API identifier for the team's spring training ballpark.
pick_team_spring_venue_linkStringRelative URL path to the spring training venue resource in the MLB Stats API.
pick_team_team_codeStringShort internal code used by MLB to identify the team in system contexts.
pick_team_file_codeStringLowercase file-system-safe code used internally by MLB to identify the team.
pick_team_abbreviationStringStandard two- or three-letter abbreviation for the MLB team that made this pick.
pick_team_team_nameStringThe nickname portion of the team's full name (e.g., Yankees, Dodgers).
pick_team_location_nameStringGeographic location name (city/metro) associated with the team (e.g., New York).
pick_team_first_year_of_playStringYear in which the selecting franchise first played as an MLB team.
pick_team_league_idInt64MLB Stats API identifier for the league (American or National) of the selecting team.
pick_team_league_nameStringFull name of the league the selecting team belongs to (e.g., American League).
pick_team_league_linkStringRelative URL path to the league resource in the MLB Stats API.
pick_team_division_idInt64MLB Stats API identifier for the division the selecting team belongs to.
pick_team_division_nameStringFull name of the division the selecting team belongs to (e.g., AL East).
pick_team_division_linkStringRelative URL path to the division resource in the MLB Stats API.
pick_team_sport_idInt64MLB Stats API identifier for the sport classification (MLB = 1).
pick_team_sport_linkStringRelative URL path to the sport resource in the MLB Stats API.
pick_team_sport_nameStringFull name of the sport classification for the team (e.g., Major League Baseball).
pick_team_short_nameStringShortened version of the team name used in space-constrained display contexts.
pick_team_franchise_nameStringHistorical franchise name that persists across any team relocations or renames.
pick_team_club_nameStringInformal club or nickname portion of the team's full name (e.g., Yankees, Red Sox).
pick_team_activeBooleanBoolean flag indicating whether the selecting MLB franchise is currently active.
pick_draft_type_codeStringShort code identifying the type of draft (e.g., amateur, Rule 5) for this pick.
pick_draft_type_descriptionStringHuman-readable description of the draft type associated with this pick.
pick_is_draftedBooleanBoolean flag indicating whether this draft slot has been filled with an actual selection.
pick_is_passBooleanBoolean flag indicating whether the selecting team passed on this pick rather than making a selection.
pick_yearStringMLB draft year for which this pick record applies.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_draft_latest(year=2023)