examples.md

Usage Examples

This document collects the longer usage examples that previously lived in the README. The README keeps a short quick start; this guide is the extended tour.

Every example in this file uses the synchronous Mlb client. Async usage is documented separately in async.md. Stats have their own detailed stats guide with both sync and async examples.

For return-object structure and endpoint details see the Wiki. For the supported method list, parameters, and return shapes see the public API contract. For transport behavior see the HTTP transport documentation.

Without a context manager

A context manager is recommended, but Mlb can also be created directly. Call mlb.close() when finished so library-owned HTTP resources are released.

from mlbstatsapi import Mlb

mlb = Mlb()
try:
    player = mlb.get_person(664034)
    team = mlb.get_team(136)

    print(player.full_name)
    print(team.name)
finally:
    mlb.close()

Working with Pydantic Models

All returned objects are Pydantic models, giving you access to serialization and validation helpers.

from mlbstatsapi import Mlb

with Mlb() as mlb:
    player = mlb.get_person(664034)

print(player.full_name)
print(player.model_dump(exclude_none=True))
print(player.model_dump_json(indent=2))

Players and teams

from mlbstatsapi import Mlb

with Mlb() as mlb:
    player_id = mlb.get_people_id("Ty France")[0]
    team_id = mlb.get_team_id("Seattle Mariners")[0]

    player = mlb.get_person(player_id)
    team = mlb.get_team(team_id)

print(player.full_name)
print(team.name)

Stats

Player, team, general, and per-game stat examples live in the dedicated Stats Guide. It also explains the nested stats[group][type] return structure and includes matching Mlb and AsyncMlb examples.

Schedule

from mlbstatsapi import Mlb

with Mlb() as mlb:
    schedule = mlb.get_schedule(date="2022-10-13")

for date in schedule.dates:
    for game in date.games:
        print(game.game_pk, game.status.detailed_state)

Game data

from mlbstatsapi import Mlb

with Mlb() as mlb:
    game = mlb.get_game(662242)
    play_by_play = mlb.get_game_play_by_play(662242)
    line_score = mlb.get_game_line_score(662242)
    box_score = mlb.get_game_box_score(662242)

Rosters

from mlbstatsapi import Mlb

with Mlb() as mlb:
    players = mlb.get_team_roster(136)
    coaches = mlb.get_team_coaches(136)

for player in players:
    print(f"#{player.jersey_number} {player.person.full_name}")

for coach in coaches:
    print(f"{coach.person.full_name}: {coach.title}")

Draft

from mlbstatsapi import Mlb

with Mlb() as mlb:
    draft = mlb.get_draft("2019")

for pick in draft[0].picks:
    print(f"Round {pick.pick_round}, Pick {pick.pick_number}: {pick.person.full_name}")

Awards

from mlbstatsapi import Mlb

with Mlb() as mlb:
    retired_numbers = mlb.get_awards(award_id="RETIREDUNI_108")

for recipient in retired_numbers.awards:
    print(f"{recipient.player.full_name}: {recipient.name} ({recipient.date})")

Venue, division, league, and season

from mlbstatsapi import Mlb

with Mlb() as mlb:
    venue_id = mlb.get_venue_id("PNC Park")[0]
    venue = mlb.get_venue(venue_id)
    division = mlb.get_division(200)
    league = mlb.get_league(103)
    season = mlb.get_season(2018)

print(venue.name)
print(division.name)
print(league.name)
print(season.season_id)

Standings

from mlbstatsapi import Mlb

with Mlb() as mlb:
    standings = mlb.get_standings(103, 2018)

for record in standings:
    print(f"Division: {record.division.name}")
    for team in record.team_records:
        print(f"  {team.team.name}: {team.wins}-{team.losses}")