⚾ MLB Stats API

Extract comprehensive baseball data from MLB's official free API. Get teams, standings, game schedules with scores, and detailed player statistics for any season.

Why use this Actor

Use this Actor when you need structured MLB data without wrestling with unofficial scrapers or brittle HTML parsing. It’s useful for research, dashboards, sports monitoring, and quick season comparisons.

🔧 Features

• Teams — List all 30 MLB teams with venue, league, division info
• Standings — Division standings with W/L record, winning percentage, games back, run differential
• Schedule / Scores — Game schedules and final scores for any date or full season
• Player Stats — Detailed hitting and pitching statistics for any team's roster

📊 Modes

Mode	Description	Key Fields
teams	All 30 MLB teams	name, abbreviation, league, division, venue
standings	Division standings	team, wins, losses, pct, games_back, streak
schedule	Game schedule & scores	away_team, home_team, scores, winner, venue
player_stats	Player statistics	name, position, avg/hr/rbi (hitting) or era/wins/k (pitching)

🚀 How to Use

1. Select a Mode from the dropdown
2. Set the Season year (defaults to current year)
3. For schedule mode: optionally enter a Date (YYYY-MM-DD)
4. For player_stats mode: optionally enter a Team ID
5. Click Start to run

Common Team IDs

Team	ID	Team	ID
New York Yankees	147	Los Angeles Dodgers	119
Boston Red Sox	111	Chicago Cubs	112
Houston Astros	117	Atlanta Braves	144
Philadelphia Phillies	143	San Diego Padres	135
New York Mets	121	San Francisco Giants	137

📦 Sample Output (Standings)

{
    "division": "American League East",
    "team": "New York Yankees",
    "wins": 82,
    "losses": 55,
    "pct": ".599",
    "games_back": "-",
    "division_rank": "1",
    "runs_scored": 580,
    "runs_allowed": 478,
    "run_diff": 102,
    "streak": "W3",
    "season": "2025",
    "mode": "standings",
    "index": 1,
    "fetched_at": "2025-07-15T12:00:00+00:00"
}

📦 Sample Output (Player Stats — Hitting)

{
    "player_id": 660271,
    "name": "Shohei Ohtani",
    "number": "17",
    "position": "DH",
    "stat_group": "hitting",
    "team": "Los Angeles Dodgers",
    "games": 120,
    "at_bats": 450,
    "hits": 130,
    "avg": ".289",
    "home_runs": 40,
    "rbi": 95,
    "ops": "1.012",
    "season": "2025",
    "mode": "player_stats",
    "index": 1,
    "fetched_at": "2025-07-15T12:00:00+00:00"
}

🚀 Quick Start

1. Choose a mode: teams, standings, schedule, or player_stats.
2. For schedules, use a date like 2025-07-15.
3. For player stats, optionally provide a team ID (e.g. 147 for the Yankees).
4. Run the Actor and verify that each item includes index, mode, and fetched_at.

🔍 Verification Steps

• Test teams mode first to confirm the API is reachable.
• Run standings mode and check that division rows appear in the dataset.
• For schedule, verify the date filter returns games for the requested day.
• For player_stats, start with a small roster and confirm stats fields are populated.

🧪 Example Inputs

Teams

{ "mode": "teams", "season": "2025" }

Schedule

{ "mode": "schedule", "season": "2025", "date": "2025-07-15" }

Player stats

{ "mode": "player_stats", "season": "2025", "team_id": 147, "stat_type": "hitting" }

📝 Notes

• No API key required — MLB Stats API is completely free and public
• Player stats mode makes individual API calls per player (may take 30-60 seconds for a full roster)
• Schedule without a date returns the full season schedule (can be large)
• All data comes directly from MLB's official statsapi.mlb.com API

💡 Troubleshooting

• Use YYYY-MM-DD for the schedule date field.
• If you get no results, check that the season is valid and the mode is set correctly.
• For roster stats, try a known team ID first (like 147 for the Yankees).
• If player_stats feels slow, start with a single team to confirm the pipeline before larger runs.