# MLB Baseball Stats API
> Major League Baseball as an API, from the official MLB Stats API. Get the 30 clubs, live division standings (wins, losses, win pct, games back, current streak, run differential), the full schedule and final scores for any date, team rosters, player profiles with complete season hitting and pitching stats (HR, AVG, OPS, RBI, ERA, strikeouts, W-L and more), and inning-by-inning line scores for any game. Resolve teams by abbreviation (NYY), id (147) or name (Yankees), and players by name (Aaron Judge) or MLB id. Perfect for building scoreboards and standings widgets, fantasy-baseball tools, stat dashboards, Discord/Slack bots, and sports-data apps. No key for the upstream, no accounts to manage.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/mlb-api/..."
```

## Pricing
- **Free** (Free) — 3,500 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 45,000 calls/Mo, 6 req/s
- **Pro** ($17/Mo) — 220,000 calls/Mo, 16 req/s
- **Mega** ($45/Mo) — 1,100,000 calls/Mo, 40 req/s

## Endpoints

### Teams

#### `GET /v1/teams` — The 30 MLB clubs

**Parameters:**
- `league` (query, optional, string) — AL or NL Example: `AL`
- `division` (query, optional, string) — e.g. AL East Example: `AL East`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mlb-api/v1/teams?league=AL&division=AL+East"
```

**Response:**
```json
{
    "data": {
        "count": 5,
        "teams": [
            {
                "id": 110,
                "abbr": "BAL",
                "club": "Orioles",
                "name": "Baltimore Orioles",
                "league": "AL",
                "division": "AL East",
                "location": "Baltimore"
            },
            {
                "id": 111,
                "abbr": "BOS",
                "club": "Red Sox",
                "name": "Boston Red Sox",
                "league": "AL",
                "division": "AL East",
                "location": "Boston"
            },
            {
                "id": 139,
                "abbr": "TB",
                "club": "Rays",
                "name": "Tampa Bay Rays",
                "league": "AL",
                "division": "AL East",
                "location": "Tampa Bay"
            },
            {
                "id": 141,
                "abbr": "TOR",
                "club": "Blue Jays",
                "name": "Toronto Blue Jays",
                "league": "AL",
                "division": "AL East",
                "location": "Toronto"
            },
            {
                "id": 147,
                "abbr": "NYY",
                "club": "Yankees",
                "name": "New York Yankees",
                "league": "AL",
                "division": "AL East",
                "location": "New York"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:1
…(truncated, see openapi.json for full schema)
```

### Standings

#### `GET /v1/standings` — Division standings for a season

**Parameters:**
- `season` (query, optional, string) — Season year Example: `2025`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mlb-api/v1/standings?season=2025"
```

**Response:**
```json
{
    "data": {
        "season": 2025,
        "divisions": [
            {
                "teams": [
                    {
                        "pct": 0.58,
                        "rank": 1,
                        "team": {
                            "id": 141,
                            "abbr": "TOR",
                            "name": "Toronto Blue Jays"
                        },
                        "wins": 94,
                        "losses": 68,
                        "streak": "W4",
                        "run_diff": 77,
                        "games_back": 0,
                        "runs_scored": 798,
                        "runs_allowed": 721,
                        "wildcard_games_back": 0
                    },
                    {
                        "pct": 0.58,
                        "rank": 2,
                        "team": {
                            "id": 147,
                            "abbr": "NYY",
                            "name": "New York Yankees"
                        },
                        "wins": 94,
                        "losses": 68,
                        "streak": "W8",
                        "run_diff": 164,
                        "games_back": 0,
                        "runs_scored": 849,
                        "runs_allowed": 685,
                        "wildcard_games_back": 7
                    },
                    {
                        "pct": 0.549,
                        "rank": 3,
   
…(truncated, see openapi.json for full schema)
```

### Schedule

#### `GET /v1/schedule` — Games & scores on a date

**Parameters:**
- `date` (query, optional, string) — YYYY-MM-DD (default today) Example: `2025-07-04`
- `team` (query, optional, string) — Team abbr/id/name Example: `NYY`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mlb-api/v1/schedule?date=2025-07-04&team=NYY"
```

**Response:**
```json
{
    "data": {
        "date": "2025-07-04",
        "count": 1,
        "games": [
            {
                "away": {
                    "id": 147,
                    "abbr": "NYY",
                    "name": "New York Yankees",
                    "score": 5,
                    "record": "48-40"
                },
                "home": {
                    "id": 121,
                    "abbr": "NYM",
                    "name": "New York Mets",
                    "score": 6,
                    "record": "51-38"
                },
                "venue": "Citi Field",
                "status": "Final",
                "game_pk": 777250,
                "date_time": "2025-07-04T19:10:00Z"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:11.192Z",
        "request_id": "2d437385-c7e4-4495-8a6d-52a7f5ab483e"
    },
    "status": "ok",
    "message": "Schedule retrieved",
    "success": true
}
```

### Rosters

#### `GET /v1/roster` — A team roster

**Parameters:**
- `team` (query, required, string) — Team abbr/id/name Example: `NYY`
- `season` (query, optional, string) — Season year Example: `2025`
- `type` (query, optional, string) — active|fullSeason|40Man Example: `active`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mlb-api/v1/roster?team=NYY&season=2025&type=active"
```

**Response:**
```json
{
    "data": {
        "team": {
            "id": 147,
            "abbr": "NYY",
            "name": "New York Yankees"
        },
        "type": "active",
        "count": 52,
        "season": 2025,
        "players": [
            {
                "id": 670280,
                "name": "David Bednar",
                "jersey": "53",
                "status": "Active",
                "position": "P"
            },
            {
                "id": 690925,
                "name": "Clayton Beeter",
                "jersey": "29",
                "status": "Traded",
                "position": "P"
            },
            {
                "id": 641355,
                "name": "Cody Bellinger",
                "jersey": "35",
                "status": "Active",
                "position": "LF"
            },
            {
                "id": 656234,
                "name": "Jake Bird",
                "jersey": "59",
                "status": "Active",
                "position": "P"
            },
            {
                "id": 621112,
                "name": "Paul Blackburn",
                "jersey": "58",
                "status": "Active",
                "position": "P"
            },
            {
                "id": 664141,
                "name": "JT Brubaker",
                "jersey": "34",
                "status": "Released",
                "position": "P"
            },
            {
                "id": 676609,
                "name": "José 
…(truncated, see openapi.json for full schema)
```

### Players

#### `GET /v1/player` — Player bio + season stats

**Parameters:**
- `id` (query, optional, string) — MLB player id Example: `592450`
- `name` (query, optional, string) — Player name Example: `Aaron Judge`
- `season` (query, optional, string) — Season year Example: `2024`
- `group` (query, optional, string) — hitting|pitching|fielding Example: `hitting`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mlb-api/v1/player?id=592450&name=Aaron+Judge&season=2024&group=hitting"
```

**Response:**
```json
{
    "data": {
        "stats": {
            "stat": {
                "age": 32,
                "avg": ".322",
                "obp": ".458",
                "ops": "1.159",
                "rbi": 144,
                "slg": ".701",
                "hits": 180,
                "runs": 122,
                "babip": ".367",
                "atBats": 559,
                "airOuts": 128,
                "doubles": 36,
                "triples": 1,
                "homeRuns": 58,
                "sacBunts": 0,
                "sacFlies": 2,
                "groundOuts": 82,
                "hitByPitch": 9,
                "leftOnBase": 238,
                "strikeOuts": 171,
                "totalBases": 392,
                "baseOnBalls": 133,
                "gamesPlayed": 158,
                "stolenBases": 10,
                "caughtStealing": 0,
                "numberOfPitches": 2885,
                "atBatsPerHomeRun": "9.64",
                "intentionalWalks": 20,
                "plateAppearances": 704,
                "groundOutsToAirouts": "0.64",
                "catchersInterference": 1,
                "groundIntoDoublePlay": 22,
                "stolenBasePercentage": "1.000",
                "caughtStealingPercentage": ".000"
            },
            "group": "hitting",
            "season": 2024,
            "has_stats": true
        },
        "player": {
            "id": 592450,
            "age": 34,
            "bats": "R",
            "last": "Judge",
…(truncated, see openapi.json for full schema)
```

### Games

#### `GET /v1/game` — Line score for a game

**Parameters:**
- `id` (query, required, string) — gamePk (from /v1/schedule) Example: `775296`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mlb-api/v1/game?id=775296"
```

**Response:**
```json
{
    "data": {
        "away": {
            "hits": 7,
            "runs": 7,
            "errors": 0,
            "left_on_base": 10
        },
        "home": {
            "hits": 8,
            "runs": 6,
            "errors": 2,
            "left_on_base": 12
        },
        "inning": 9,
        "status": "Bottom 9",
        "game_pk": 775296,
        "innings": [
            {
                "away": 0,
                "home": 3,
                "inning": 1
            },
            {
                "away": 0,
                "home": 1,
                "inning": 2
            },
            {
                "away": 0,
                "home": 1,
                "inning": 3
            },
            {
                "away": 0,
                "home": 0,
                "inning": 4
            },
            {
                "away": 5,
                "home": 0,
                "inning": 5
            },
            {
                "away": 0,
                "home": 1,
                "inning": 6
            },
            {
                "away": 0,
                "home": 0,
                "inning": 7
            },
            {
                "away": 2,
                "home": 0,
                "inning": 8
            },
            {
                "away": 0,
                "home": 0,
                "inning": 9
            }
        ],
        "inning_state": "Bottom",
        "scheduled_innings": 9
    },
    "meta": {
        "timestamp": "2026-0
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Usage notes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mlb-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Major League Baseball data. /v1/teams = the 30 clubs (filter league=AL|NL, division); /v1/standings?season=2025 = division standings (W-L, pct, games back, streak, run diff); /v1/schedule?date=YYYY-MM-DD&team=NYY = games & scores on a date (default today); /v1/roster?team=NYY = a team's roster; /v1/player?name=Aaron Judge or id=592450 (&season=&group=hitting|pitching) = bio + season stats; /v1/game?id=775296 = line score by gamePk. Teams resolve by abbreviation (NYY), id (147) or name. Official data from the MLB Stats API.",
        "source": "MLB Stats API (statsapi.mlb.com)",
        "endpoints": [
            "/v1/teams",
            "/v1/standings",
            "/v1/schedule",
            "/v1/roster",
            "/v1/player",
            "/v1/game",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:11.862Z",
        "request_id": "2b6e2596-a6a8-4d04-9edc-3779c1f425c1"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/mlb-api
OpenAPI spec: https://www.oanor.com/api/mlb-api/openapi.json