Investigate MLB eventTypes and event-level stats usage #330

Why

The MLB Stats API exposes a reference endpoint for event types:

https://statsapi.mlb.com/api/v1/eventTypes

These values appear throughout play-by-play data and can also be used with event-level stat queries such as playLog through the eventType parameter.

The library currently exposes event_type on play results and accepts arbitrary **params for stats methods, but practical event-level use cases are not documented or tested in a focused way.

This issue should investigate how eventTypes can be used in practice and whether the library should provide better documentation, tests, or helpers around them.

Goals

• Inventory the current values returned by MLB's /eventTypes endpoint
• Understand the metadata MLB provides for each event type, including plate appearance, hit, and baserunning classifications
• Verify how eventType filtering behaves with stat types such as playLog
• Verify how event type codes appear in game play-by-play responses
• Identify useful event-level analysis patterns for users
• Decide whether documentation alone is sufficient or whether library helpers would add value

Practical use cases to investigate

Examples include:

• Retrieve a player's home runs, doubles, walks, strikeouts, or other specific event types from playLog
• Filter stolen base and caught-stealing events
• Group play-by-play results using the stable machine-readable event_type value instead of display strings
• Analyze events by game, inning, opponent, pitcher, score state, or date
• Use MLB's event metadata to classify events as hits, plate appearances, or baserunning events

Example query to validate:

stats = mlb.get_player_stats(
    player_id,
    stats=["playLog"],
    groups=["hitting"],
    season=2026,
    eventType="home_run",
)

The async equivalent should behave the same where supported.

Areas to inspect

Play-by-play

The game feed exposes event information through fields such as:

play.result.event
play.result.event_type

Confirm that the current model mapping accurately preserves MLB's event type identifiers and document the distinction between human-readable event descriptions and machine-readable event codes.

Stats filtering

Determine which stat types actually honor the eventType parameter and what response shape they return.

playLog is the primary candidate, but the investigation should not assume it is the only valid use.

Potential helpers

Do not add public API solely as part of the investigation, but evaluate whether functionality such as the following would be useful:

mlb.get_event_types()
mlb.get_event_types(hit=True)
mlb.get_event_types(plate_appearance=True)
mlb.get_event_types(base_running_event=True)

Any public helper should be proposed separately after the use cases and response contract are understood.

Acceptance criteria

• Current MLB eventTypes response is documented or captured for investigation
• eventType filtering is live-tested with playLog
• At least several representative event types are validated, such as home_run, strikeout, walk, and a baserunning event
• Play-by-play event_type behavior is verified against live game data
• Useful event-level analysis patterns are documented
• Sync and async behavior is compared where applicable
• Documentation gaps are identified
• Any proposed public helper API is split into a separate implementation issue

Scope

This is a standalone investigation and documentation issue. It is not part of the v1.1.0 release milestone unless the investigation uncovers an existing public API regression.