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
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.
Why
The MLB Stats API exposes a reference endpoint for event types:
https://statsapi.mlb.com/api/v1/eventTypesThese values appear throughout play-by-play data and can also be used with event-level stat queries such as
playLogthrough theeventTypeparameter.The library currently exposes
event_typeon play results and accepts arbitrary**paramsfor stats methods, but practical event-level use cases are not documented or tested in a focused way.This issue should investigate how
eventTypescan be used in practice and whether the library should provide better documentation, tests, or helpers around them.Goals
/eventTypesendpointeventTypefiltering behaves with stat types such asplayLogPractical use cases to investigate
Examples include:
playLogevent_typevalue instead of display stringsExample query to validate:
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:
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
eventTypeparameter and what response shape they return.playLogis 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:
Any public helper should be proposed separately after the use cases and response contract are understood.
Acceptance criteria
eventTypesresponse is documented or captured for investigationeventTypefiltering is live-tested withplayLoghome_run,strikeout,walk, and a baserunning eventevent_typebehavior is verified against live game dataScope
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.