Skip to content

stats.md

Latest commit

 

History

History
272 lines (194 loc) · 6.21 KB

stats.md

File metadata and controls

272 lines (194 loc) · 6.21 KB
Raw

Stats Guide

The stats methods return MLB statistics grouped by stat group and then by stat type. Both Mlb and AsyncMlb return the same structure.

Stats methods

Method Use
get_player_stats() Stats for one player
get_team_stats() Stats for one team
get_stats() General stats query across the Stats API
get_players_stats_for_game() Stats for one player in one game

The synchronous and asynchronous signatures match. With AsyncMlb, await the method call.

Understanding the return value

The four stats methods return a nested dictionary:

stats[group][type] -> Stat

For example:

stats = mlb.get_player_stats(
    664034,
    stats=["season"],
    groups=["hitting"],
    season=2022,
)

season_hitting = stats["hitting"]["season"]

season_hitting is a Stat model. Its splits field contains the returned stat splits.

for split in season_hitting.splits:
    print(split.stat.model_dump(exclude_none=True))

A query can request multiple groups and stat types at once:

stats = mlb.get_player_stats(
    664034,
    stats=["season", "career"],
    groups=["hitting", "fielding"],
    season=2022,
)

for group_name, group_stats in stats.items():
    for stat_type, stat in group_stats.items():
        print(group_name, stat_type, stat.total_splits)

If the API response contains no usable stats, these methods return {}.

Player stats

Use get_player_stats() when you know the MLB person ID and want one or more stat types for that player.

Sync

from mlbstatsapi import Mlb

with Mlb() as mlb:
    stats = mlb.get_player_stats(
        664034,
        stats=["season", "career"],
        groups=["hitting"],
        season=2022,
    )

season = stats["hitting"]["season"]
for split in season.splits:
    print(split.stat.model_dump(exclude_none=True))

Async

import asyncio

from mlbstatsapi import AsyncMlb


async def main():
    async with AsyncMlb() as mlb:
        stats = await mlb.get_player_stats(
            664034,
            stats=["season", "career"],
            groups=["hitting"],
            season=2022,
        )

    season = stats["hitting"]["season"]
    for split in season.splits:
        print(split.stat.model_dump(exclude_none=True))


asyncio.run(main())

Team stats

Use get_team_stats() for stat data scoped to one team.

Sync

from mlbstatsapi import Mlb

with Mlb() as mlb:
    stats = mlb.get_team_stats(
        136,
        stats=["season", "seasonAdvanced"],
        groups=["hitting"],
        season=2022,
    )

for stat_type, stat in stats["hitting"].items():
    print(stat_type)
    for split in stat.splits:
        print(split.stat.model_dump(exclude_none=True))

Async

import asyncio

from mlbstatsapi import AsyncMlb


async def main():
    async with AsyncMlb() as mlb:
        stats = await mlb.get_team_stats(
            136,
            stats=["season", "seasonAdvanced"],
            groups=["hitting"],
            season=2022,
        )

    for stat_type, stat in stats["hitting"].items():
        print(stat_type)
        for split in stat.splits:
            print(split.stat.model_dump(exclude_none=True))


asyncio.run(main())

General stats queries

get_stats() queries the general /stats endpoint. Additional keyword arguments can narrow the request by season, team, league, game type, sport, and other Stats API parameters.

Sync

from mlbstatsapi import Mlb

with Mlb() as mlb:
    stats = mlb.get_stats(
        stats=["season"],
        groups=["hitting"],
        season=2022,
        sportIds=1,
    )

for group_name, group_stats in stats.items():
    for stat_type, stat in group_stats.items():
        print(group_name, stat_type)
        for split in stat.splits:
            print(split.stat.model_dump(exclude_none=True))

Async

import asyncio

from mlbstatsapi import AsyncMlb


async def main():
    async with AsyncMlb() as mlb:
        stats = await mlb.get_stats(
            stats=["season"],
            groups=["hitting"],
            season=2022,
            sportIds=1,
        )

    for group_name, group_stats in stats.items():
        for stat_type, stat in group_stats.items():
            print(group_name, stat_type)
            for split in stat.splits:
                print(split.stat.model_dump(exclude_none=True))


asyncio.run(main())

Player stats for a game

Use get_players_stats_for_game() when you have both the player's MLB person ID and the game's gamePk.

Sync

from mlbstatsapi import Mlb

with Mlb() as mlb:
    stats = mlb.get_players_stats_for_game(
        person_id=663728,
        game_id=715757,
    )

for group_name, group_stats in stats.items():
    for stat_type, stat in group_stats.items():
        print(group_name, stat_type)
        for split in stat.splits:
            print(split.stat.model_dump(exclude_none=True))

Async

import asyncio

from mlbstatsapi import AsyncMlb


async def main():
    async with AsyncMlb() as mlb:
        stats = await mlb.get_players_stats_for_game(
            person_id=663728,
            game_id=715757,
        )

    for group_name, group_stats in stats.items():
        for stat_type, stat in group_stats.items():
            print(group_name, stat_type)
            for split in stat.splits:
                print(split.stat.model_dump(exclude_none=True))


asyncio.run(main())

Finding valid stat types and groups

The MLB Stats API publishes the available values directly:

Common stat groups include hitting, pitching, and fielding. Available stat types depend on the group and endpoint. Examples include season, career, seasonAdvanced, gameLog, and playLog.

Related documentation