python-mlb-statsapi provides Python access to the MLB Stats API for teams, players, schedules, games, stats, and more.

Returned objects are built with Pydantic, and model fields use Python snake_case names.

Version 1.1 adds first-class async support through AsyncMlb while keeping the existing synchronous Mlb API available without code changes for sync users.

Copyright Notice

This package and its authors are not affiliated with MLB or any MLB team. This API wrapper interfaces with MLB's Stats API. Use of MLB data is subject to the notice posted at http://gdx.mlb.com/components/copyright.txt.

This is an educational project - Not for commercial use.

Installation

Synchronous client

python3 -m pip install python-mlb-statsapi

Async support

Install the optional async extra to use AsyncMlb and AsyncMlbDataAdapter:

python3 -m pip install "python-mlb-statsapi[async]"

The async extra installs HTTPX. Python 3.10 or newer is required.

See Python support for the complete policy.

Quick Start

Sync

from mlbstatsapi import Mlb

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

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

Async

import asyncio

from mlbstatsapi import AsyncMlb


async def main():
    async with AsyncMlb() as mlb:
        player = await mlb.get_person(664034)
        team = await mlb.get_team(136)

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


asyncio.run(main())

Without a context manager

Context managers are recommended, but both clients can also be created directly. When doing that, close library-owned HTTP resources explicitly.

Sync

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

Async

import asyncio

from mlbstatsapi import AsyncMlb


async def main():
    mlb = AsyncMlb()
    try:
        player = await mlb.get_person(664034)
        team = await mlb.get_team(136)

        print(player.full_name)
        print(team.name)
    finally:
        await mlb.aclose()


asyncio.run(main())

See Async usage for lifecycle, concurrency, custom HTTPX clients, and the current async endpoint list.

Sync or Async?

AsyncMlb mirrors the full endpoint surface of Mlb. Both clients return the same Pydantic models and follow the same public HTTP/error behavior.

See the public API contract for the authoritative method list and signatures.

Concurrent Async Requests

AsyncMlb supports concurrent requests on the same event loop. Concurrency is controlled by the caller.

import asyncio

from mlbstatsapi import AsyncMlb


async def main():
    async with AsyncMlb() as mlb:
        player, team = await asyncio.gather(
            mlb.get_person(664034),
            mlb.get_team(136),
        )

        return player, team


player, team = asyncio.run(main())

AsyncMlb does not create hidden background tasks or automatic request fanout.

Common Methods

The examples below assume an initialized Mlb client named mlb, as shown in Quick Start.

Players

player = mlb.get_person(664034)
players = mlb.get_people()
player_ids = mlb.get_people_id("Ty France")

Teams

team = mlb.get_team(136)
teams = mlb.get_teams()
team_ids = mlb.get_team_id("Seattle Mariners")

Stats

The stats API has several entry points and returns a nested stats[group][type] structure. See the dedicated Stats Guide for get_player_stats(), get_team_stats(), get_stats(), and get_players_stats_for_game() examples using both Mlb and AsyncMlb.

Schedule

schedule = mlb.get_schedule(date="2022-10-13")

See the method reference for the full method documentation that previously lived in the README. Longer runnable examples live in docs/examples.md.

HTTP and Error Behavior

Both clients use explicit timeouts, structured exceptions, and pooled HTTP connections. strict_http=True is the default. Final non-404 4xx responses raise MlbHttpError, while existing endpoint-specific 404 behavior is preserved.

Library-created clients send a versioned User-Agent. The current package version sends python-mlb-statsapi/1.1.0. See the HTTP transport documentation for the full transport contract.

The main transport exceptions are:

• MlbHttpError
• MlbTimeoutError
• MlbTransportError
• MlbDecodeError

from mlbstatsapi import Mlb, MlbHttpError, MlbTimeoutError

try:
    with Mlb() as mlb:
        player = mlb.get_person(664034)
except MlbTimeoutError:
    print("The MLB API timed out")
except MlbHttpError as exc:
    print(exc.status_code, exc.reason)

For timeouts, retries, compatibility mode, ownership rules, and transport details, see docs/http-transport.md.

Working with Models

Every returned model object uses Pydantic and Python-style snake_case fields:

from mlbstatsapi import Mlb

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

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

Documentation

Contributing

Contributions, bug fixes, tests, and documentation improvements are welcome.

git clone https://github.com/YOUR_USERNAME/python-mlb-statsapi.git
cd python-mlb-statsapi
poetry install -E async

Run the deterministic offline suite before a pull request:

poetry run pytest tests/ --ignore=tests/external_tests

External tests contact the live MLB API and are separate from normal offline CI:

poetry run pytest tests/external_tests/

See CONTRIBUTING.md for the full development and pull request workflow.

License

Released under the MIT License.