MLB Data API

API Endpoint
http://lookup-service-prod.mlb.com

All of the data you get back from these endpoints is property of MLB/MLB Advanced Media, and you should refer to their terms of use before using any of it in projects.

Getting Started

1. Request Structure

  • Host: http://lookup-service-prod.mlb.com

  • Path: /json/named.[endpoint].bam

2. Example Request 

http://lookup-service-prod.mlb.com/json/named.search_player_all.bam

3. Using col_in & col_ex

For many responses from the API, you can determine what data is included and excluded, using the col_in and col_ex parameters respectively. This is useful and almost required for some endpoints that return large amounts of additional data that you likely won’t need.

The format for these params is [endpoint].col_in or [endpoint].col_ex, for example a search request with col_in would look like this:

http://lookup-service-prod.mlb.com/json/named.search_player_all.bam?sport_code='mlb'&active_sw='Y'&name_part='young%'&search_player_all.col_in=player_id

This would perform a search for ‘young’ but any results found would only have the player_id field. Conversely, we could exclude the player_id field by using col_ex

http://lookup-service-prod.mlb.com/json/named.search_player_all.bam?sport_code='mlb'&active_sw='Y'&name_part='young%'&search_player_all.col_ex=player_id

This way we get search results that feature every field except the player’s ID.

Player Data

Endpoints for getting general player data. This data typically includes important dates for the player (birth, pro debut), some basic attributes like throwing/batting arm, height, weight as well as country of birth and college/schools attended.

GET http://lookup-service-prod.mlb.com/json/named.search_player_all.bam?sport_code='mlb'&active_sw='Y'&name_part='cespedes%25'
Responses200
Headers
Content-Type: application/json
Body
{
  "search_player_all": {
    "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
    "queryResults": {
      "created": "2017-12-11T15:11:55",
      "totalSize": "1",
      "row": {
        "position": "LF",
        "birth_country": "Cuba",
        "weight": "220",
        "birth_state": "",
        "name_display_first_last": "Yoenis Cespedes",
        "college": "",
        "height_inches": "10",
        "name_display_roster": "Cespedes, Y",
        "sport_code": "mlb",
        "bats": "R",
        "name_first": "Yoenis",
        "team_code": "nyn",
        "birth_city": "Granma",
        "height_feet": "5",
        "pro_debut_date": "2012-03-28T00:00:00",
        "team_full": "New York Mets",
        "team_abbrev": "NYM",
        "birth_date": "1985-10-18T00:00:00",
        "throws": "R",
        "league": "NL",
        "name_display_last_first": "Cespedes, Yoenis",
        "position_id": "7",
        "high_school": "",
        "name_use": "Yoenis",
        "player_id": "493316",
        "name_last": "Cespedes",
        "team_id": "121",
        "service_years": "",
        "active_sw": "Y"
      }
    }
  }
}

Search For Player(s)
GET/json/named.search_player_all.bam?sport_code='mlb'&active_sw={active_sw}&name_part={name_part}

Search for active and historic/inactive players by name.

The active_sw parameter should be set depending on whether you want to search for active or inactive players. You can omit this parameter, though you will notice a slower response time as the search is done across all (active and inactive) players.

If you’re using a single search term i.e. using ‘cespedes’ instead of ‘yoenis cespedes’, you’ll need to append a ‘%25’ character to your search term. Without it, the request will return 500. See example.

URI Parameters
HideShow
active_sw
string (optional) Example: 'Y'

Set to ‘Y’ to search active players, and ‘N’ to search inactive/historic players.

name_part
string (required) Example: 'cespedes%25'

The player name to search for.

Player Info

GET http://lookup-service-prod.mlb.com/json/named.player_info.bam?sport_code='mlb'&player_id='493316'
Responses200
Headers
Content-Type: application/json
Body
{
  "player_info": {
    "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
    "queryResults": {
      "created": "2017-12-11T17:24:10",
      "totalSize": "1",
      "row": {
        "birth_country": "Cuba",
        "name_prefix": "",
        "name_display_first_last": "Yoenis Cespedes",
        "college": "",
        "height_inches": "10",
        "death_country": "",
        "age": "32",
        "name_display_first_last_html": "Yoenis Céspedes",
        "gender": "M",
        "height_feet": "5",
        "pro_debut_date": "2012-03-28T00:00:00",
        "death_date": "",
        "primary_position": "7",
        "birth_date": "1985-10-18T00:00:00",
        "team_abbrev": "NYM",
        "status": "Active",
        "name_display_last_first_html": "Céspedes, Yoenis",
        "throws": "R",
        "death_city": "",
        "primary_position_txt": "LF",
        "high_school": "",
        "name_display_roster_html": "Céspedes, Y",
        "name_use": "Yoenis",
        "player_id": "493316",
        "status_date": "2017-10-02T00:00:00",
        "primary_stat_type": "hitting",
        "team_id": "121",
        "active_sw": "Y",
        "primary_sport_code": "mlb",
        "birth_state": "",
        "weight": "220",
        "name_middle": "",
        "name_display_roster": "Cespedes, Y",
        "end_date": "",
        "jersey_number": "52",
        "death_state": "",
        "name_first": "Yoenis",
        "bats": "R",
        "team_code": "nyn",
        "birth_city": "Granma",
        "name_nick": "La Potencia",
        "status_code": "A",
        "name_matrilineal": "Milanes",
        "team_name": "New York Mets",
        "name_display_last_first": "Cespedes, Yoenis",
        "twitter_id": "@ynscspds",
        "name_title": "",
        "file_code": "nym",
        "name_last": "Cespedes",
        "start_date": "2016-11-30T00:00:00",
        "name_full": "Cespedes, Yoenis"
      }
    }
  }
}

Get Player Details
GET/json/named.player_info.bam?sport_code='mlb'&player_id={player_id}

Retrieve general information on a player. This includes name variants, education information, country of origin and attributes like height, weight and age.

URI Parameters
HideShow
player_id
string (required) Example: '493316'

Player Teams

GET http://lookup-service-prod.mlb.com/json/named.player_teams.bam?season='2014'&player_id='493316'
Responses200
Headers
Content-Type: application/json
Body
{
  "player_teams": {
    "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
    "queryResults": {
      "created": "2017-12-12T01:43:07",
      "totalSize": "2",
      "row": [
        {
          "season_state": "offseason",
          "hitting_season": "2014",
          "sport_full": "Major League Baseball",
          "org": "Red Sox",
          "sport_code": "mlb",
          "org_short": "Boston",
          "jersey_number": "52",
          "end_date": "2014-12-09T00:00:00",
          "team_brief": "Red Sox",
          "forty_man_sw": "Y",
          "sport_id": "1",
          "league_short": "American",
          "org_full": "Boston Red Sox",
          "status_code": "A",
          "league_full": "American League",
          "primary_position": "LF",
          "team_abbrev": "BOS",
          "status": "Active",
          "org_abbrev": "BOS",
          "league_id": "103",
          "class": "MLB",
          "sport": "MLB",
          "team_short": "Boston",
          "team": "Boston Red Sox",
          "league": "AL",
          "fielding_season": "2014",
          "org_id": "111",
          "class_id": "1",
          "league_season": "2014",
          "pitching_season": "",
          "sport_short": "",
          "status_date": "2014-08-01T00:00:00",
          "player_id": "493316",
          "current_sw": "N",
          "primary_stat_type": "hitting",
          "team_id": "111",
          "start_date": "2014-07-31T00:00:00"
        },
        {
          "season_state": "offseason",
          "hitting_season": "2014",
          "sport_full": "Major League Baseball",
          "org": "Athletics",
          "sport_code": "mlb",
          "org_short": "Oakland",
          "jersey_number": "52",
          "end_date": "2014-07-30T00:00:00",
          "team_brief": "Athletics",
          "forty_man_sw": "N",
          "sport_id": "1",
          "league_short": "American",
          "org_full": "Oakland Athletics",
          "status_code": "TR",
          "league_full": "American League",
          "primary_position": "LF",
          "team_abbrev": "OAK",
          "status": "Traded",
          "org_abbrev": "OAK",
          "league_id": "103",
          "class": "MLB",
          "sport": "MLB",
          "team_short": "Oakland",
          "team": "Oakland Athletics",
          "league": "AL",
          "fielding_season": "2014",
          "org_id": "133",
          "class_id": "1",
          "league_season": "2014",
          "pitching_season": "",
          "sport_short": "",
          "status_date": "2014-07-30T00:00:00",
          "player_id": "493316",
          "current_sw": "N",
          "primary_stat_type": "hitting",
          "team_id": "133",
          "start_date": "2012-03-03T00:00:00"
        }
      ]
    }
  }
}

Get Teams Played For
GET/json/named.player_teams.bam?season={season}&player_id={player_id}

Retrieve the teams a player has played for over the course of a season, or their career.

Omitting the season parameter will retrieve all teams the player has played for since the start of their career.

URI Parameters
HideShow
season
string (optional) Example: '2014'
player_id
string (required) Example: '493316'

Stats Data

Endpoints for getting player stats. This data typically encompasses pitching/batting stats per season, league, game type and also projected stats.

Season Hitting Stats

GET http://lookup-service-prod.mlb.com/json/named.sport_hitting_tm.bam?league_list_id='mlb'&game_type='R'&season='2017'&player_id='493316'
Responses200
Headers
Content-Type: application/json
Body
{
  "sport_hitting_tm": {
    "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
    "queryResults": {
      "created": "2017-12-12T02:51:36",
      "totalSize": "1",
      "row": {
        "gidp": "7",
        "sac": "0",
        "np": "1317",
        "sport_code": "mlb",
        "hgnd": "30",
        "tb": "157",
        "gidp_opp": "57",
        "sport_id": "1",
        "bb": "26",
        "avg": ".292",
        "slg": ".540",
        "team_full": "New York Mets",
        "ops": ".892",
        "hbp": "2",
        "league_full": "National League",
        "team_abbrev": "NYM",
        "so": "61",
        "hfly": "23",
        "wo": "0",
        "league_id": "104",
        "sf": "2",
        "team_seq": "1",
        "league": "NL",
        "hpop": "0",
        "cs": "1",
        "season": "2017",
        "sb": "0",
        "go_ao": "0.60",
        "ppa": "4.10",
        "player_id": "493316",
        "ibb": "5",
        "team_id": "121",
        "roe": "1",
        "go": "58",
        "hr": "17",
        "rbi": "42",
        "babip": ".316",
        "lob": "120",
        "end_date": "2017-12-12T00:00:00",
        "xbh": "36",
        "league_short": "National",
        "g": "81",
        "d": "17",
        "sport": "MLB",
        "team_short": "NY Mets",
        "tpa": "321",
        "h": "85",
        "obp": ".352",
        "hldr": "32",
        "t": "2",
        "ao": "96",
        "r": "46",
        "ab": "291"
      }
    }
  }
}

Season Hitting Stats
GET/json/named.sport_hitting_tm.bam?league_list_id='mlb'&game_type={game_type}&season={season}&player_id={player_id}

Retrieve a players hitting stats for a given season.

URI Parameters
HideShow
game_type
string (required) Example: 'R'

The type of games you want career stats for.

  • 'R' - Regular Season

  • 'S' - Spring Training

  • 'E' - Exhibition

  • 'A' - All Star Game

  • 'D' - Division Series

  • 'F' - First Round (Wild Card)

  • 'L' - League Championship

  • 'W' - World Series

season
string (required) Example: '2017'
player_id
string (required) Example: '493316'

Season Pitching Stats

GET http://lookup-service-prod.mlb.com/json/named.sport_pitching_tm.bam?league_list_id='mlb'&game_type='R'&season='2017'&player_id='592789'
Responses200
Headers
Content-Type: application/json
Body
{
  "sport_pitching_tm": {
    "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
    "queryResults": {
      "created": "2017-12-12T02:52:25",
      "totalSize": "1",
      "row": {
        "gidp": "1",
        "h9": "8.60",
        "np": "459",
        "tr": "1",
        "gf": "0",
        "sport_code": "mlb",
        "bqs": "0",
        "hgnd": "14",
        "sho": "0",
        "bq": "0",
        "gidp_opp": "15",
        "bk": "0",
        "kbb": "11.33",
        "sport_id": "1",
        "hr9": "0.00",
        "sv": "0",
        "slg": ".305",
        "bb": "3",
        "whip": "1.05",
        "avg": ".246",
        "ops": ".573",
        "team_full": "New York Mets",
        "db": "5",
        "league_full": "National League",
        "team_abbrev": "NYM",
        "hfly": "1",
        "so": "34",
        "tbf": "124",
        "bb9": "0.89",
        "league_id": "104",
        "wp": "3",
        "team_seq": "1",
        "hpop": "0",
        "league": "NL",
        "hb": "1",
        "cs": "2",
        "pgs": "65.6",
        "season": "2017",
        "sb": "2",
        "go_ao": "1.85",
        "ppa": "3.70",
        "cg": "0",
        "player_id": "592789",
        "gs": "7",
        "ibb": "1",
        "team_id": "121",
        "pk": "0",
        "go": "37",
        "hr": "0",
        "irs": "0",
        "wpct": ".333",
        "era": "2.97",
        "babip": ".341",
        "end_date": "2017-12-12T00:00:00",
        "rs9": "3.86",
        "qs": "4",
        "league_short": "National",
        "g": "7",
        "ir": "0",
        "hld": "0",
        "k9": "10.09",
        "sport": "MLB",
        "team_short": "NY Mets",
        "l": "2",
        "svo": "0",
        "h": "29",
        "ip": "30.1",
        "obp": ".268",
        "w": "1",
        "hldr": "14",
        "ao": "20",
        "s": "308",
        "r": "14",
        "spct": "67.1",
        "pip": "15.1",
        "ab": "118",
        "er": "10"
      }
    }
  }
}

Season Pitching Stats
GET/json/named.sport_pitching_tm.bam?league_list_id='mlb'&game_type={game_type}&season={season}&player_id={player_id}

Retrieve a players pitching stats for a given season.

URI Parameters
HideShow
game_type
string (required) Example: 'R'

The type of games you want career stats for.

  • 'R' - Regular Season

  • 'S' - Spring Training

  • 'E' - Exhibition

  • 'A' - All Star Game

  • 'D' - Division Series

  • 'F' - First Round (Wild Card)

  • 'L' - League Championship

  • 'W' - World Series

season
string (required) Example: '2017'
player_id
string (required) Example: '592789'

Career Hitting Stats

GET http://lookup-service-prod.mlb.com/json/named.sport_career_hitting.bam?league_list_id='mlb'&game_type='R'&player_id='493316'
Responses200
Headers
Content-Type: application/json
Body
{
  "sport_career_hitting": {
    "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
    "queryResults": {
      "created": "2017-12-12T02:28:43",
      "totalSize": "1",
      "row": {
        "hr": "154",
        "gidp": "65",
        "np": "12792",
        "sac": "0",
        "team_count": "4",
        "sport_code": "mlb",
        "hgnd": "260",
        "rbi": "495",
        "lob": "1256",
        "babip": ".304",
        "gidp_opp": "518",
        "tb": "1504",
        "xbh": "344",
        "sport_id": "1",
        "bb": "225",
        "avg": ".274",
        "slg": ".498",
        "ops": ".826",
        "hbp": "29",
        "g": "788",
        "d": "166",
        "hfly": "158",
        "so": "677",
        "wo": "3",
        "sport": "MLB",
        "sf": "26",
        "hpop": "6",
        "tpa": "3299",
        "h": "828",
        "cs": "20",
        "obp": ".328",
        "hldr": "404",
        "t": "24",
        "ao": "894",
        "r": "452",
        "go_ao": "0.80",
        "sb": "40",
        "ppa": "3.88",
        "player_id": "493316",
        "ab": "3019",
        "ibb": "31",
        "roe": "35",
        "go": "711"
      }
    }
  }
}

Career Hitting Stats
GET/json/named.sport_career_hitting.bam?league_list_id='mlb'&game_type={game_type}&player_id={player_id}

Retrieve a players career hitting stats for a given game type.

URI Parameters
HideShow
game_type
string (required) Example: 'R'

The type of games you want career stats for.

  • 'R' - Regular Season

  • 'S' - Spring Training

  • 'E' - Exhibition

  • 'A' - All Star Game

  • 'D' - Division Series

  • 'F' - First Round (Wild Card)

  • 'L' - League Championship

  • 'W' - World Series

player_id
string (required) Example: '493316'

Career Pitching Stats

GET http://lookup-service-prod.mlb.com/json/named.sport_career_pitching.bam?league_list_id='mlb'&game_type='R'&player_id='592789'
Responses200
Headers
Content-Type: application/json
Body
{
  "sport_career_pitching": {
    "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
    "queryResults": {
      "created": "2017-12-12T02:32:23",
      "totalSize": "1",
      "row": {
        "gidp": "24",
        "h9": "7.99",
        "team_count": "1",
        "np": "5774",
        "tr": "10",
        "gf": "0",
        "sport_code": "mlb",
        "bqs": "5",
        "hgnd": "122",
        "sho": "0",
        "bq": "12",
        "gidp_opp": "146",
        "bk": "1",
        "kbb": "5.43",
        "sport_id": "1",
        "hr9": "0.74",
        "sv": "0",
        "slg": "1.073",
        "bb": "77",
        "whip": "1.10",
        "avg": ".236",
        "ops": "1.351",
        "db": "58",
        "so": "418",
        "hfly": "39",
        "tbf": "1471",
        "bb9": "1.90",
        "wp": "19",
        "hb": "6",
        "hpop": "0",
        "cs": "12",
        "pgs": "94.7",
        "go_ao": "1.35",
        "sb": "65",
        "ppa": "3.93",
        "player_id": "592789",
        "cg": "0",
        "ibb": "5",
        "gs": "61",
        "pk": "1",
        "go": "372",
        "hr": "30",
        "irs": "0",
        "wpct": ".571",
        "era": "2.89",
        "babip": ".315",
        "rs9": "4.75",
        "qs": "38",
        "g": "62",
        "ir": "0",
        "hld": "1",
        "k9": "10.34",
        "sport": "MLB",
        "l": "18",
        "svo": "0",
        "h": "323",
        "ip": "364.0",
        "obp": ".278",
        "w": "24",
        "hldr": "162",
        "ao": "275",
        "s": "3852",
        "r": "135",
        "spct": "66.7",
        "pip": "15.9",
        "ab": "1371",
        "er": "117"
      }
    }
  }
}

Career Pitching Stats
GET/json/named.sport_career_pitching.bam?league_list_id='mlb'&game_type={game_type}&player_id={player_id}

Retrieve a players career hitting stats for a given game type.

URI Parameters
HideShow
game_type
string (required) Example: 'R'

The type of games you want career stats for.

  • 'R' - Regular Season

  • 'S' - Spring Training

  • 'E' - Exhibition

  • 'A' - All Star Game

  • 'D' - Division Series

  • 'F' - First Round (Wild Card)

  • 'L' - League Championship

  • 'W' - World Series

player_id
string (required) Example: '592789'

League Hitting Stats

GET http://lookup-service-prod.mlb.com/json/named.sport_career_hitting_lg.bam?league_list_id='mlb'&game_type='R'&player_id='493316'
Responses200
Headers
Content-Type: application/json
Body
{
  "sport_career_hitting_lg": {
    "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
    "queryResults": {
      "created": "2017-12-12T03:15:43",
      "totalSize": "2",
      "row": [
        {
          "hr": "89",
          "gidp": "39",
          "sac": "0",
          "team_count": "3",
          "sport_code": "mlb",
          "rbi": "323",
          "tb": "954",
          "sport_id": "1",
          "bb": "134",
          "avg": ".269",
          "slg": ".473",
          "league_short": "American",
          "ops": ".790",
          "hbp": "16",
          "g": "518",
          "league_full": "American League",
          "d": "110",
          "so": "454",
          "league_id": "103",
          "sport": "MLB",
          "sf": "17",
          "league": "AL",
          "h": "543",
          "cs": "17",
          "obp": ".317",
          "t": "17",
          "ao": "603",
          "r": "295",
          "go_ao": "0.79",
          "sb": "33",
          "player_id": "493316",
          "ab": "2019",
          "ibb": "15",
          "go": "475"
        },
        {
          "hr": "65",
          "gidp": "26",
          "sac": "0",
          "team_count": "1",
          "sport_code": "mlb",
          "rbi": "172",
          "tb": "550",
          "sport_id": "1",
          "bb": "91",
          "avg": ".285",
          "slg": ".550",
          "league_short": "National",
          "ops": ".900",
          "hbp": "13",
          "g": "270",
          "league_full": "National League",
          "d": "56",
          "so": "223",
          "league_id": "104",
          "sport": "MLB",
          "sf": "9",
          "league": "NL",
          "h": "285",
          "cs": "3",
          "obp": ".350",
          "t": "7",
          "ao": "291",
          "r": "157",
          "go_ao": "0.81",
          "sb": "7",
          "player_id": "493316",
          "ab": "1000",
          "ibb": "16",
          "go": "236"
        }
      ]
    }
  }
}

League Hitting Stats
GET/json/named.sport_career_hitting_lg.bam?league_list_id='mlb'&game_type={game_type}&player_id={player_id}

Retrieve a players career hitting stats for a given game type split by the league.

URI Parameters
HideShow
game_type
string (required) Example: 'R'

The type of games you want career stats for.

  • 'R' - Regular Season

  • 'S' - Spring Training

  • 'E' - Exhibition

  • 'A' - All Star Game

  • 'D' - Division Series

  • 'F' - First Round (Wild Card)

  • 'L' - League Championship

  • 'W' - World Series

player_id
string (required) Example: '493316'

League Pitching Stats

GET http://lookup-service-prod.mlb.com/json/named.sport_career_pitching_lg.bam?league_list_id='mlb'&game_type='R'&player_id='592789'
Responses200
Headers
Content-Type: application/json
Body
{
  "sport_career_pitching_lg": {
    "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
    "queryResults": {
      "created": "2017-12-12T03:18:05",
      "totalSize": "1",
      "row": {
        "hr": "30",
        "gidp": "24",
        "irs": "0",
        "np": "5774",
        "team_count": "1",
        "era": "2.89",
        "sport_code": "mlb",
        "sho": "0",
        "bk": "1",
        "sport_id": "1",
        "sv": "0",
        "avg": ".236",
        "whip": "1.10",
        "bb": "77",
        "league_short": "National",
        "ir": "0",
        "g": "62",
        "league_full": "National League",
        "so": "418",
        "tbf": "1471",
        "wp": "19",
        "league_id": "104",
        "sport": "MLB",
        "l": "18",
        "league": "NL",
        "svo": "0",
        "hb": "6",
        "h": "323",
        "ip": "364.0",
        "w": "24",
        "s": "3852",
        "ao": "275",
        "r": "135",
        "go_ao": "1.35",
        "cg": "0",
        "player_id": "592789",
        "ab": "1371",
        "gs": "61",
        "ibb": "5",
        "er": "117",
        "go": "372"
      }
    }
  }
}

League Pitching Stats
GET/json/named.sport_career_pitching_lg.bam?league_list_id='mlb'&game_type={game_type}&player_id={player_id}

Retrieve a players career hitting stats for a given game type, split by league.

The response example is for a player who’s only ever played in one league.

URI Parameters
HideShow
game_type
string (required) Example: 'R'

The type of games you want career stats for.

  • 'R' - Regular Season

  • 'S' - Spring Training

  • 'E' - Exhibition

  • 'A' - All Star Game

  • 'D' - Division Series

  • 'F' - First Round (Wild Card)

  • 'L' - League Championship

  • 'W' - World Series

player_id
string (required) Example: '592789'

Projected Pitching Stats

GET http://lookup-service-prod.mlb.com/json/named.proj_pecota_pitching.bam?season='2017'&player_id='592789'
Responses200
Headers
Content-Type: application/json
Body
{
  "proj_pecota_pitching": {
    "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
    "queryResults": {
      "created": "2017-12-12T02:57:24",
      "totalSize": "1",
      "row": {
        "hr": "3",
        "player": "Syndergaard, Noah",
        "wpct": ".429",
        "era": "3.02",
        "bsv": "0",
        "outs": "179",
        "sho": "0",
        "sv": "0",
        "whip": "1.06",
        "qs": "7",
        "bb": "10",
        "g": "12",
        "hld": "0",
        "so": "69",
        "l": "4",
        "hb": "2",
        "svo": "0",
        "h": "53",
        "ip": "59.2",
        "w": "3",
        "r": "25",
        "pa": "243",
        "player_id": "592789",
        "cg": "0",
        "gs": "12",
        "ibb": "1",
        "er": "20"
      }
    }
  }
}

Projected Pitching Stats
GET/json/named.proj_pecota_pitching.bam?season={season}&player_id={player_id}

Retrieve a players projected pitching stats for a given season.

Omitting the season parameter will return the actual stats for the players earliest major league season.

URI Parameters
HideShow
season
string (optional) Example: '2017'
player_id
string (required) Example: '592789'

Projected Hitting Stats

GET http://lookup-service-prod.mlb.com/json/named.proj_pecota_batting.bam?season='2017'&player_id='493316'
Responses200
Headers
Content-Type: application/json
Body
{
  "proj_pecota_batting": {
    "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
    "queryResults": {
      "created": "2017-12-12T03:09:35",
      "totalSize": "1",
      "row": {
        "hr": "17",
        "gidp": "7",
        "player": "Cespedes, Yoenis",
        "sac": "0",
        "rbi": "42",
        "tb": "157",
        "slg": ".538",
        "avg": ".291",
        "bb": "26",
        "ops": ".889",
        "hbp": "2",
        "g": "81",
        "d": "17",
        "e": "12",
        "so": "61",
        "sf": "2",
        "tpa": "322",
        "h": "85",
        "cs": "1",
        "obp": ".351",
        "t": "2",
        "s": "49",
        "r": "46",
        "sb": "0",
        "sbpct": ".000",
        "player_id": "493316",
        "ab": "292",
        "ibb": "5"
      }
    }
  }
}

Projected Hitting Stats
GET/json/named.proj_pecota_batting.bam?season={season}&player_id={player_id}

Retrieve a players projected hitting stats for a given season.

Omitting the season parameter will return the actual stats for the players earliest major league season.

URI Parameters
HideShow
season
string (optional) Example: '2017'
player_id
string (required) Example: '493316'

Team Data

Endpoints for getting team data. This data typically encompasses stadium information, contact details, and other team specific information.

List Teams

GET http://lookup-service-prod.mlb.com/json/named.team_all_season.bam?sport_code='mlb'&all_star_sw='N'&sort_order=name_asc&season='2017'
Responses200
Headers
Content-Type: application/json
Body
{
    "team_all_season": {
        "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
        "queryResults": {
            "created": "2017-12-14T23:34:39",
            "totalSize": "30",
            "row": [
                {
                    "phone_number": "(602) 462-6500",
                    "venue_name": "Chase Field",
                    "franchise_code": "ARI",
                    "all_star_sw": "N",
                    "sport_code": "mlb",
                    "address_city": "Phoenix",
                    "city": "Phoenix",
                    "name_display_full": "Arizona Diamondbacks",
                    "spring_league_abbrev": "CL",
                    "time_zone_alt": "America/Phoenix",
                    "sport_id": "1",
                    "venue_id": "15",
                    "mlb_org_id": "109",
                    ...
                },
                ...
            ]
        }
    }
}

Get Teams By Season
GET/json/named.team_all_season.bam?sport_code='mlb'&all_star_sw={all_star_sw}&sort_order={sort_order}&season={season}

Retrieve a list of major league teams that were active during a given season.

If all_star_sw is set to 'Y', you will instead receive data on the all star teams for that season.

You can sort using the sort_order paramater. Ex: Sort in ascending order by the name field using sort_by='name_asc'

URI Parameters
HideShow
all_star_sw
string (optional) Example: 'N'

Set to ‘Y’ for all star data, and ‘N’ for regular season.

sort_order
string (optional) Example: name_asc

Field to sort results by.

season
string (required) Example: '2017'

40-Man Roster

GET http://lookup-service-prod.mlb.com/json/named.roster_40.bam?team_id='121'
Responses200
Headers
Content-Type: application/json
Body
{
    "roster_40": {
        "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
        "queryResults": {
            "created": "2017-12-15T02:09:22",
            "totalSize": "39",
            "row": [
                {
                    "position_txt": "P",
                    "weight": "197",
                    "name_display_first_last": "Tyler Bashlor",
                    "college": "South Georgia State",
                    "height_inches": "0",
                    "starter_sw": "N",
                    "jersey_number": "",
                    "end_date": "",
                    "name_first": "Tyler",
                    "bats": "R",
                    "team_code": "nyn",
                    "height_feet": "6",
                    "pro_debut_date": "",
                    "status_code": "A",
                    "primary_position": "1",
                    "birth_date": "1993-04-16T00:00:00",
                    "team_abbrev": "NYM",
                    "throws": "R",
                    "team_name": "New York Mets",
                    "name_display_last_first": "Bashlor, Tyler",
                    "name_use": "Tyler",
                    "player_id": "641341",
                    "name_last": "Bashlor",
                    "team_id": "121",
                    "start_date": "2017-11-20T00:00:00",
                    "name_full": "Bashlor, Tyler"
                },
                ...
            ]
        }
    }
}

Get 40-Man Roster
GET/json/named.roster_40.bam?team_id={team_id}

Retrieve a team’s 40 man roster.

This endpoint is best used alongside col_in/col_ex to prune response data. Without, it returns entire player objects.

See: Using col_in & col_ex

URI Parameters
HideShow
team_id
string (required) Example: '121'

All Time Roster

GET http://lookup-service-prod.mlb.com/json/named.roster_team_alltime.bam?start_season='2016'&end_season='2017'&team_id='121'
Responses200
Headers
Content-Type: application/json
Body
{
    "roster_team_alltime": {
        "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
        "queryResults": {
            "created": "2017-12-15T02:18:23",
            "totalSize": "64",
            "row": [
                {
                    "name_first_last": "Norichika Aoki",
                    "weight": "180",
                    "primary_position": "OF",
                    "birth_date": "1982-01-05T00:00:00",
                    "throws": "R",
                    "stat_years": "2017",
                    "height_inches": "9",
                    "name_sort": "AOKI, NORICHIKA",
                    "status_short": "Active",
                    "jersey_number": "11",
                    "player_first_last_html": "Norichika Aoki",
                    "bats": "L",
                    "position_desig": "OUTFIELDER",
                    "forty_man_sw": "Y",
                    "player_html": "Aoki, Norichika",
                    "height_feet": "5",
                    "player_id": "493114",
                    "name_last_first": "Aoki, Norichika",
                    "current_sw": "N",
                    "team_id": "121",
                    "roster_years": "2017",
                    "active_sw": "Y"
                },
                ...
            ]
        }
    }
}

Get Roster By Seasons
GET/json/named.roster_team_alltime.bam?start_season={start_season}&end_season={end_season}&team_id={team_id}

Retrieve a teams roster between a given start and end season.

Enter the same season for start_season and end_season to get the roster for that single season.

This endpoint is best used alongside col_in/col_ex to prune response data. Without, it returns entire player objects.

See: Using col_in & col_ex

URI Parameters
HideShow
start_season
string (required) Example: '2016'
end_season
string (required) Example: '2017'
team_id
string (required) Example: '121'

Game Data

Endpoints for getting game data. This data typically encompasses the dates between which a particular type of game was played.

Game Type Info

GET http://lookup-service-prod.mlb.com/json/named.org_game_type_date_info.bam?current_sw='Y'&sport_code='mlb'game_type='L'&season='2017'
Responses200
Headers
Content-Type: application/json
Body
{
  "org_game_type_date_info": {
    "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
    "queryResults": {
      "created": "2017-12-15T00:41:19",
      "totalSize": "3",
      "row": [
        {
          "league_code": "",
          "game_type": "R",
          "round_robin_sw": "N",
          "season": "2017",
          "playoffs_sw": "N",
          "last_game_date": "2017-10-01T00:00:00",
          "name_short": "Season",
          "league_id": "",
          "sport_code": "mlb",
          "first_game_date": "2017-04-02T00:00:00",
          "name_full": "Regular Season",
          "playoff_round": ""
        },
        {
          "league_code": "AL",
          "game_type": "R",
          "round_robin_sw": "N",
          "season": "2017",
          "playoffs_sw": "N",
          "last_game_date": "2017-10-01T00:00:00",
          "name_short": "Season",
          "league_id": "103",
          "sport_code": "mlb",
          "first_game_date": "2017-04-02T00:00:00",
          "name_full": "Regular Season",
          "playoff_round": ""
        },
        {
          "league_code": "NL",
          "game_type": "R",
          "round_robin_sw": "N",
          "season": "2017",
          "playoffs_sw": "N",
          "last_game_date": "2017-10-01T00:00:00",
          "name_short": "Season",
          "league_id": "104",
          "sport_code": "mlb",
          "first_game_date": "2017-04-02T00:00:00",
          "name_full": "Regular Season",
          "playoff_round": ""
        }
      ]
    }
  }
}

Get Info Per Game Type
GET/json/named.org_game_type_date_info.bam?current_sw='Y'&sport_code='mlb'game_type={game_type}&season={season}

Retrieve a list of one or numerous game types.

For example, if you wanted to know when the National League Championship Series was played, this endpoint could tell you that.

URI Parameters
HideShow
game_type
string (required) Example: 'L'

  • 'R' - Regular Season

  • 'S' - Spring Training

  • 'E' - Exhibition

  • 'A' - All Star Game

  • 'D' - Division Series

  • 'F' - First Round (Wild Card)

  • 'L' - League Championship

  • 'W' - World Series

season
string (required) Example: '2017'

Reports

Endpoints for getting injury, transaction, and status data.

Transactions

GET http://lookup-service-prod.mlb.com/json/named.transaction_all.bam?sport_code='mlb'&start_date='20171201'&end_date='20171231'
Responses200
Headers
Content-Type: application/json
Body
{
    "transaction_all": {
        "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
        "queryResults": {
            "created": "2017-12-13T16:55:03",
            "totalSize": "103",
            "row": [
                {
                    "trans_date_cd": "D",
                    "from_team_id": "138",
                    "orig_asset": "Player",
                    "final_asset_type": "",
                    "player": "Aledmys Diaz",
                    "resolution_cd": "",
                    "final_asset": "",
                    "name_display_first_last": "Aledmys Diaz",
                    "type_cd": "TR",
                    "name_sort": "DIAZ, ALEDMYS",
                    "resolution_date": "",
                    "conditional_sw": "N",
                    "team": "Toronto Blue Jays",
                    "type": "Trade",
                    "name_display_last_first": "Diaz, Aledmys",
                    "transaction_id": "338110",
                    "trans_date": "2017-12-01T00:00:00",
                    "effective_date": "2017-12-01T00:00:00",
                    "player_id": "649557",
                    "orig_asset_type": "PL",
                    "from_team": "St. Louis Cardinals",
                    "team_id": "141",
                    "note": "St. Louis Cardinals traded SS Aledmys Diaz to Toronto Blue Jays for CF J.B. Woodman."
                },
                ...
            ]
        }
    }
}

Get Transactions Over Period
GET/json/named.transaction_all.bam?sport_code='mlb'&start_date={start_date}&end_date={end_date}

Retrieve all transactions between a given period.

start_date and end_date parameters should be in the YYYYMMDD format.

URI Parameters
HideShow
start_date
string (required) Example: '20171201'

Start date of time period.

end_date
string (required) Example: '20171231'

End date of time period.

Broadcast Info

GET http://lookup-service-prod.mlb.com/json/named.mlb_broadcast_info.bam?src_type='TV'&src_comment='National'&tcid=mm_mlb_schedule&sort_by='game_time_et_asc'&home_away='H'&start_date='20170415'&end_date='20170417'&season='2017'
Responses200
Headers
Content-Type: application/json
Body
{
    "mlb_broadcast_info": {
        "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
        "queryResults": {
            "created": "2017-12-15T01:50:44",
            "totalSize": "11",
            "row": [
                {
                    "away_team_id": "138",
                    "home_team_short": "NY Yankees",
                    "game_time_local": "2017-04-15T13:05:00",
                    "game_time_home": "2017-04-15T13:05:00",
                    "source_id": "2661",
                    "home_team_full": "New York Yankees",
                    "game_date": "2017-04-15T00:00:00",
                    "source_type": "TV",
                    "foreign_language": "",
                    "game_pk": "490267",
                    "game_time_away": "2017-04-15T12:05:00",
                    "game_day": "Saturday",
                    "source_comment": "National",
                    "source_desc": "MLBN",
                    "away_team_abbrev": "STL",
                    "away_team_full": "St. Louis Cardinals",
                    "game_id": "2017/04/15/slnmlb-nyamlb-1",
                    "home_team_abbrev": "NYY",
                    "home_team_id": "147",
                    "sort_order": "3",
                    "game_time_et": "2017-04-15T13:05:00",
                    "away_team_short": "St. Louis",
                    "home_away": "H"
                },
                ...
            ]
        }
    }
}

Get Broadcasts Over Period
GET/json/named.mlb_broadcast_info.bam?src_type='TV'&src_comment='National'&tcid=mm_mlb_schedule&sort_by={sort_by}&home_away={home_away}&start_date={start_date}&end_date={end_date}&season={season}

Retrieve information on broadcasts over a given period.

start_date and end_date parameters should be in the YYYYMMDD format.

Although you can omit the home_away parameter to retrieve both home and away game data, one will include the other. For example, a New York Mets home game result will include data for the visiting team.

URI Parameters
HideShow
sort_by
string (optional) Example: 'game_time_et_asc'

Field to sort results by.

home_away
string (optional) Example: 'H'

‘H’ for home games, ‘A’ for away games. Omit for both.

start_date
string (optional) Example: '20170415'
end_date
string (optional) Example: '20170417'
season
string (required) Example: '2017'

Injuries

GET http://lookup-service-prod.mlb.com/fantasylookup/json/json/named.wsfb_news_injury.bam
Responses200
Headers
Content-Type: application/json
Body
{
    "wsfb_news_injury": {
        "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
        "queryResults": {
            "created": "2017-12-13T17:59:39",
            "totalSize": "28",
            "row": [
                {
                    "insert_ts": "11/19",
                    "injury_desc": "Recovering from Sept. 2017 right shoulder surgery",
                    "position": "P",
                    "name_first": "Alex",
                    "display_ts": "November 19, 2017 at 2:23 AM ET",
                    "due_back": "2019",
                    "team_name": "Angels",
                    "injury_update": "Underwent right shoulder surgery Sept. 12.",
                    "league_id": "103",
                    "player_id": "543542",
                    "injury_status": "Offseason",
                    "name_last": "Meyer",
                    "team_id": "108"
                },
                ...
            ]
        }
    }
}

Get Current Injuries
GET/fantasylookup/json/json/named.wsfb_news_injury.bam

Retrieve all players which are currently injured.

Hitting Leaders

GET http://lookup-service-prod.mlb.com/json/named.leader_hitting_repeater.bam?sport_code='mlb'&results=5&game_type='R'&season='2017'&sort_column='ab'&leader_hitting_repeater.col_in=ab
Responses200
Headers
Content-Type: application/json
Body
{
  "leader_hitting_repeater": {
    "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
    "leader_hitting_mux": {
      "sort_column": "'ab'",
      "queryResults": {
        "created": "2017-12-13T18:25:07",
        "totalSize": "5",
        "row": [
          {
            "name_display_first_last": "Ender Inciarte",
            "ab": "662"
          },
          {
            "name_display_first_last": "Dee Gordon",
            "ab": "653"
          },
          {
            "name_display_first_last": "Francisco Lindor",
            "ab": "651"
          },
          {
            "name_display_first_last": "Charlie Blackmon",
            "ab": "644"
          },
          {
            "name_display_first_last": "Elvis Andrus",
            "ab": "643"
          }
        ]
      }
    }
  }
}

Get Hitting Leaders
GET/json/named.leader_hitting_repeater.bam?sport_code='mlb'&results={results}&game_type={game_type}&season={season}&sort_column={sort_column}&leader_hitting_repeater.col_in={leader_hitting_repeater.col_in}

Retrieve n leaders for a given hitting statistic.

This endpoint is best used alongside col_in/col_ex to prune response data. Without, it returns entire player objects.

For best results, include the player’s name, id, and the stat as a starting point.

See: Using col_in & col_ex

URI Parameters
HideShow
results
string | number (required) Example: 5

The number of results to return.

game_type
string (required) Example: 'R'

The type of games you want career stats for.

  • 'R' - Regular Season

  • 'S' - Spring Training

  • 'E' - Exhibition

  • 'A' - All Star Game

  • 'D' - Division Series

  • 'F' - First Round (Wild Card)

  • 'L' - League Championship

  • 'W' - World Series

season
string (required) Example: '2017'
sort_column
string (required) Example: 'ab'

The statistic you want leaders for.

leader_hitting_repeater.col_in
string (optional) Example: ab

Pitching Leaders

GET http://lookup-service-prod.mlb.com/json/named.leader_pitching_repeater.bam?sport_code='mlb'&results=5&game_type='R'&season='2017'&sort_column='era'&leader_pitching_repeater.col_in=era
Responses200
Headers
Content-Type: application/json
Body
{
  "leader_pitching_repeater": {
    "copyRight": " Copyright 2017 MLB Advanced Media, L.P.  Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt  ",
    "leader_pitching_mux": {
      "sort_column": "'era'",
      "queryResults": {
        "created": "2017-12-14T01:13:30",
        "totalSize": "5",
        "row": [
          {
            "name_display_first_last": "Corey Kluber",
            "era": "2.25"
          },
          {
            "name_display_first_last": "Clayton Kershaw",
            "era": "2.31"
          },
          {
            "name_display_first_last": "Max Scherzer",
            "era": "2.51"
          },
          {
            "name_display_first_last": "Stephen Strasburg",
            "era": "2.52"
          },
          {
            "name_display_first_last": "Robbie Ray",
            "era": "2.89"
          }
        ]
      }
    }
  }
}

Get Pitching Leaders
GET/json/named.leader_pitching_repeater.bam?sport_code='mlb'&results={results}&game_type={game_type}&season={season}&sort_column={sort_column}&leader_pitching_repeater.col_in={leader_pitching_repeater.col_in}

Retrieve n leaders for a given hitting statistic.

This endpoint is best used alongside col_in/col_ex to prune response data. Without, it returns entire player objects.

For best results, include the player’s name, id, and the stat as a starting point.

See: Using col_in & col_ex

URI Parameters
HideShow
results
string | number (required) Example: 5

The number of results to return.

game_type
string (required) Example: 'R'

The type of games you want career stats for.

  • 'R' - Regular Season

  • 'S' - Spring Training

  • 'E' - Exhibition

  • 'A' - All Star Game

  • 'D' - Division Series

  • 'F' - First Round (Wild Card)

  • 'L' - League Championship

  • 'W' - World Series

season
string (required) Example: '2017'
sort_column
string (required) Example: 'era'

The statistic you want leaders for.

leader_pitching_repeater.col_in
string (optional) Example: era

Generated by aglio on 13 Mar 2018