index.md

Python MLB Stats API

python-mlb-statsapi is a Python client for MLB's Stats API with synchronous and asynchronous interfaces.

View usage examples{ .md-button .md-button--primary } Browse the method reference{ .md-button }

• Broad API coverage

  Query teams, players, schedules, games, statistics, and more.

• Pythonic models

  Work with Pydantic objects whose fields use snake_case names.

• Sync and async

  Choose the synchronous Mlb client or the asynchronous AsyncMlb client. Existing sync users can upgrade without changing their code.

Installation

Install the synchronous client:

python3 -m pip install python-mlb-statsapi

Install the optional async extra to use AsyncMlb and AsyncMlbDataAdapter:

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

Python 3.10 or newer is required.

Quick start

Synchronous client

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)

Asynchronous client

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

Explore the documentation

• Usage examples cover common synchronous workflows.
• Stats guide explains player, team, general, and per-game statistics.
• Async usage covers lifecycle, concurrency, custom HTTPX clients, and endpoint support.
• Method reference lists the available endpoint methods.
• HTTP transport documents timeouts, retries, errors, proxies, and ownership.
• Public API contract defines supported symbols and compatibility guarantees.
• Release notes summarize each published version.

Unofficial project. This package and its authors are not affiliated with or endorsed by Major League Baseball or any MLB team. Use of MLB data is subject to MLB's copyright notice. This is an educational project—not for commercial use.