# ESPN Scraper: Box Scores & Player Stats (NFL, NBA, MLB, NHL) (`sports-odds-lab/espn-scraper`) Actor

Sports data from ESPN: scores, schedules and full player box scores for NFL, NBA, MLB, NHL, WNBA, college football and basketball, MLS and Europe's top soccer leagues. Recent days, any date range or whole seasons. One clean row per game or per player per game.

- **URL**: https://apify.com/sports-odds-lab/espn-scraper.md
- **Developed by:** [Min Maxxxer](https://apify.com/sports-odds-lab) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## ESPN Scraper: Box Scores & Player Stats (NFL, NBA, MLB, NHL)

> 🎁 **Free until 12 October 2026.** Press **Start** — the prefilled input returns yesterday's games of five leagues in seconds.

![Sample output: NBA Finals 2025 Game 7, one row per player with minutes, points, rebounds, assists and shooting](https://api.apify.com/v2/key-value-stores/CEtWcytR8Vm5hiMr1/records/preview-espn.png?signature=1gwzP88Z4n8xpToeRURRi)

Get **scores, schedules and full player box scores from ESPN** for the **NFL, NBA, MLB, NHL, WNBA**, college football and basketball, **MLS** and Europe's top soccer leagues. Pick recent days, any date range or **whole seasons**, and get one clean row per game — or **one row per player per game** with every box-score number ESPN shows.

**Two outputs:**

- **Games** — score, periods, status, teams, records, venue, attendance, broadcasts and the pre-game line for upcoming games
- **Player stats** — points, rebounds, assists and shooting splits; passing, rushing, receiving and defense; batting and pitching; time on ice, shots and faceoffs; soccer goals, shots and saves

No API key, no browser, no login — the Actor reads the same public JSON the ESPN website and app use.

### What you get

#### Player stats — one row per player per game

| Sport | Stats in each row |
|---|---|
| **NBA, WNBA, college basketball** | minutes, points, field goals made/attempted, 3-pointers, free throws, rebounds (offensive/defensive), assists, steals, blocks, turnovers, fouls, plus-minus |
| **NFL, college football** | completions, attempts, passing yards/TDs, interceptions thrown, sacks taken, QBR, passer rating; rushing attempts/yards/TDs; receptions, targets, receiving yards/TDs; tackles, sacks, passes defended, interceptions; kicking and punting; returns |
| **MLB** | batting: at-bats, runs, hits, RBIs, home runs, walks, strikeouts, AVG/OBP/SLG — pitching: innings (also as outs), hits, runs, earned runs, walks, strikeouts, home runs, pitches, strikes, ERA |
| **NHL** | goals, assists, shots, time on ice (total, power play, short-handed, even strength), shifts, hits, blocks, faceoffs won/lost, plus-minus, penalty minutes — goalies: saves, shots against, save % |
| **Soccer** | starter / sub, goals, assists, shots, shots on target, fouls, cards, offsides, saves, goals conceded |

Every row also carries the game (ID, date, season, regular season or playoffs), the player's team, opponent, home or away, the final score and **W/L**, position, jersey and whether he started. Made–attempted pairs such as `6-16` are split into two numeric fields, minutes like `20:40` become `20.67`, and baseball innings like `5.2` become `5.667` innings and `17` outs — ready for a spreadsheet or a model without cleaning.

#### Games — one row per game

League, season and season part, week (football), start time (UTC), status (finished, live, scheduled, postponed, cancelled), home and away team with ESPN IDs and abbreviations, score, **period-by-period scores**, winner, overtime flag, team records, venue, city, attendance, neutral site, conference game, TV broadcasts, the pre-game line (spread, total, moneylines) for upcoming games, and the ESPN link.

### Leagues

| US | Soccer |
|---|---|
| NFL · NBA · MLB · NHL · WNBA | MLS · NWSL · Liga MX |
| NCAA Football (all FBS games) | Premier League · EFL Championship |
| NCAA Men's Basketball (all Division I games) | LaLiga · Bundesliga · Serie A · Ligue 1 · Eredivisie |
| NCAA Women's Basketball (all Division I games) | UEFA Champions League · Europa League |

### Use cases

- **Player props and fantasy models** — every player's line in every game of a season, with minutes and starts, for NBA, NFL, MLB and NHL props or DFS projections
- **Sports analytics and research** — full seasons of box scores in minutes instead of scraping game pages one by one
- **Apps, bots and dashboards** — schedule a run with *Recent days* for yesterday's results and today's games
- **Soccer line-ups** — starters, substitutes, goals, shots and cards of every Premier League, LaLiga or MLS match

### How to use it

1. Pick the **leagues** and **what to save** (games or player stats).
2. Choose **which days**: recent days (up to 30 back and 14 ahead), a date range, or full seasons.
3. Optionally filter **teams** (`Lakers`, `LAL`, `Arsenal`) or statuses, and set **max rows**.
4. Click **Start**, then download JSON, CSV or Excel, or read the dataset through the Apify API.

A full NBA regular season of player stats (about 1,230 games, 30,000 rows) takes a couple of minutes; a season of game results takes seconds. The run page shows the progress and the time left.

#### Input example — every player's box score from yesterday's NFL and MLB games

```json
{
  "leagues": ["nfl", "mlb"],
  "output": "playerStats",
  "mode": "recent",
  "daysBack": 1
}
```

#### Input example — the whole 2024-25 NBA season, regular season and playoffs

```json
{
  "leagues": ["nba"],
  "output": "playerStats",
  "mode": "seasons",
  "seasons": ["2024-25"],
  "seasonTypes": ["regular", "postseason"]
}
```

#### Input example — Premier League results of one team in a date range

```json
{
  "leagues": ["epl"],
  "output": "games",
  "mode": "dates",
  "dateFrom": "2025-08-01",
  "dateTo": "2025-12-31",
  "teams": ["Arsenal"]
}
```

#### Output example — player stats (a real row)

```json
{
  "league": "nba",
  "gameId": "401704627",
  "startTime": "2024-10-22T23:30:00Z",
  "season": 2025,
  "seasonType": "regular",
  "team": "Boston Celtics",
  "homeAway": "home",
  "opponent": "New York Knicks",
  "teamScore": 132,
  "opponentScore": 109,
  "result": "W",
  "athleteId": "4065648",
  "player": "Jayson Tatum",
  "position": "F",
  "starter": true,
  "didNotPlay": false,
  "stats": {
    "minutes": 30, "points": 37,
    "fieldGoalsMade": 14, "fieldGoalsAttempted": 18,
    "threePointFieldGoalsMade": 8, "threePointFieldGoalsAttempted": 11,
    "freeThrowsMade": 1, "freeThrowsAttempted": 2,
    "rebounds": 4, "assists": 10, "turnovers": 1, "steals": 1, "blocks": 1, "plusMinus": 26
  },
  "url": "https://www.espn.com/nba/game/_/gameId/401704627/knicks-celtics"
}
```

#### Output example — a game (a real row, shortened)

```json
{
  "league": "nfl",
  "gameId": "401872953",
  "season": 2026,
  "seasonType": "regular",
  "week": 3,
  "startTime": "2026-09-27T17:00:00Z",
  "status": "finished",
  "homeTeam": "Buffalo Bills",
  "awayTeam": "Los Angeles Chargers",
  "homeScore": 24,
  "awayScore": 16,
  "winner": "home",
  "periods": [[0, 10], [10, 0], [0, 3], [14, 3]],
  "homeRecord": "3-0",
  "awayRecord": "0-3",
  "venue": "Highmark Stadium",
  "city": "Orchard Park"
}
```

### Pricing

⏱️ **Free until 12 October 2026** — during the launch period you only pay Apify's platform usage, typically well under $0.01 per run.

**From 13 October 2026 you pay per row saved — platform usage included**, nothing else:

| Apify plan | Player stats, per 1,000 rows | Games, per 1,000 rows |
|---|---|---|
| Free | $0.50 | $2.00 |
| Starter | $0.45 | $1.80 |
| Scale | $0.40 | $1.60 |
| Business and higher | $0.35 | $1.40 |

💡 A whole NBA regular season of player stats (about 30,000 rows) costs about $15 on the Free plan, and the monthly $5 credit covers about 10,000 player rows. Nothing is charged for games or players you filter out. Set a spending limit on the run for a hard cap — the Actor stops as soon as it is reached.

### FAQ

**Which season is "2025"?** The label ESPN uses: the year the season **ends** for the NBA, NHL and college basketball (2025 = 2024-25), the year it **starts** for the NFL, college football and European soccer (2025 = 2025-26), and the calendar year for MLB, WNBA and MLS. Writing `2024-25` always works.

**Are college games complete?** Yes — the Actor asks ESPN for all FBS football and all Division I basketball games, not only the featured ones.

**Do player rows include players who did not play?** Not by default. Turn on *Include players who did not play* to get them with ESPN's reason (for example "COACH'S DECISION").

**Is there play-by-play or historical betting odds?** Not yet. ESPN only shows the pre-game line for upcoming games. For opening and closing odds from 40+ bookmakers see the [NBA, NFL, MLB & NHL Odds](https://apify.com/sports-odds-lab/nba-nfl-mlb-nhl-odds) Actor below.

**How fresh is the data?** As fresh as ESPN at the moment of the run — live games show the current score.

**Which time zone?** All timestamps are UTC.

**Where does the data come from?** From publicly available ESPN scoreboards and box scores. This Actor is not affiliated with ESPN.

### More from Min Maxxxer

- 🏀 [NBA, NFL, MLB & NHL Odds](https://apify.com/sports-odds-lab/nba-nfl-mlb-nhl-odds) — moneyline, spread and total history back to 2009, DraftKings, FanDuel, BetMGM
- ⏱️ [Flashscore Scraper](https://apify.com/sports-odds-lab/flashscore-scraper) — live scores, results and odds of 24 sports
- ⚽ [Football Odds Scraper](https://apify.com/sports-odds-lab/football-odds-results) — 1,000+ competitions, closing odds, xG, seasons back to 2005
- 🎾 [Tennis Scraper](https://apify.com/sports-odds-lab/tennis-odds-results) — every ATP, WTA, Challenger and ITF match with odds and point-by-point
- 📊 [Polymarket & Kalshi Scraper](https://apify.com/sports-odds-lab/polymarket-kalshi-odds) — prediction market odds, price history and results

⭐ **Did this Actor save you time?** A short review on this page helps others find it — and tells us what to build next.

### Changelog

- **0.1** — first release: games and player box scores for NFL, NBA, MLB, NHL, WNBA, college football and basketball and 12 soccer competitions; recent days, date ranges and full seasons; team filter; progress with time left on the run page.

# Actor input Schema

## `leagues` (type: `array`):

Leagues to scrape. US: NFL, NBA, MLB, NHL, WNBA and college sports (all Division I / FBS games, not only the featured ones). Soccer: MLS, NWSL, Premier League, Championship, LaLiga, Bundesliga, Serie A, Ligue 1, Eredivisie, Liga MX, Champions League, Europa League.

## `output` (type: `string`):

Games: one row per game with score, periods, status, venue, attendance, broadcasts and the pre-game line. Player stats: one row per player per game from the box score (points, rebounds, passing yards, strikeouts, time on ice, shots…) — one request per game, so slower.

## `mode` (type: `string`):

Recent: a window around today. Date range: any dates you choose. Full seasons: whole seasons from ESPN's own calendar (preseason, regular season, postseason).

## `daysBack` (type: `integer`):

How many days before today to include (0 = today only). Up to 30.

## `daysAhead` (type: `integer`):

How many days after today to include — upcoming games with the pre-game line. Up to 14.

## `dateFrom` (type: `string`):

First day, YYYY-MM-DD.

## `dateTo` (type: `string`):

Last day, YYYY-MM-DD. Empty = today. Up to 400 days after 'From'.

## `seasons` (type: `array`):

e.g. '2024-2025' or '2024-25'. A single year follows ESPN's label: the year the season ends for NBA, NHL and college basketball, the year it starts for NFL, college football and European soccer, the calendar year for MLB, WNBA and MLS. Empty = the latest season(s).

## `lastSeasons` (type: `integer`):

Used when 'Seasons' is empty: how many of the latest started seasons to scrape.

## `seasonTypes` (type: `array`):

Which parts of each season. Soccer seasons are always taken whole.

## `statuses` (type: `array`):

Which games to keep. Player stats exist only for finished and live games.

## `teams` (type: `array`):

Keep only games of these teams — name or ESPN abbreviation (e.g. 'Lakers', 'LAL', 'Arsenal'). Empty = all teams.

## `includeDidNotPlay` (type: `boolean`):

Player stats: also save rows for listed players who did not play (with the reason, e.g. 'COACH'S DECISION' or an injury).

## `maxItems` (type: `integer`):

Stop after this many saved rows. 0 = no limit.

## `concurrency` (type: `integer`):

How many ESPN requests run at once.

## Actor input object example

```json
{
  "leagues": [
    "nfl",
    "nba",
    "mlb",
    "nhl",
    "epl"
  ],
  "output": "games",
  "mode": "recent",
  "daysBack": 1,
  "daysAhead": 0,
  "lastSeasons": 1,
  "seasonTypes": [
    "regular",
    "postseason"
  ],
  "statuses": [
    "finished",
    "live",
    "scheduled"
  ],
  "includeDidNotPlay": false,
  "maxItems": 100,
  "concurrency": 8
}
```

# Actor output Schema

## `games` (type: `string`):

One row per game: league, date, teams, score, status, venue.

## `players` (type: `string`):

One row per player per game with the main box-score numbers.

## `results` (type: `string`):

Full records, including every box-score stat.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "leagues": [
        "nfl",
        "nba",
        "mlb",
        "nhl",
        "epl"
    ],
    "daysBack": 1,
    "maxItems": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("sports-odds-lab/espn-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "leagues": [
        "nfl",
        "nba",
        "mlb",
        "nhl",
        "epl",
    ],
    "daysBack": 1,
    "maxItems": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("sports-odds-lab/espn-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "leagues": [
    "nfl",
    "nba",
    "mlb",
    "nhl",
    "epl"
  ],
  "daysBack": 1,
  "maxItems": 100
}' |
apify call sports-odds-lab/espn-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,sports-odds-lab/espn-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/eTXdVwqukFoF8G9Pd/builds/BLToHhxCOkfhiZwTF/openapi.json