# ESPN Sports Scraper (Scores, Standings, Teams, Rosters) (`webdatatools/espn-scraper`) Actor

Scrape ESPN sports data for NBA, NFL, MLB, NHL and soccer leagues: game scores and status, league standings, team lists and player rosters, from ESPN public endpoints.

- **URL**: https://apify.com/webdatatools/espn-scraper.md
- **Developed by:** [Murat Uzun](https://apify.com/webdatatools) (community)
- **Categories:** News, Other, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.20 / 1,000 rows

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## 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

### What is ESPN Sports Scraper?

ESPN Sports Scraper collects sports data from ESPN for NBA, NFL, MLB, NHL and soccer leagues such as the Premier League: game scores and status, league standings, team lists and player rosters. It reads ESPN's public site data, so no ESPN login or API key is needed.

### Why use ESPN Sports Scraper?

- Scores and game status for any date range (up to 31 days per run) across several leagues.
- League standings with wins, losses, points and point differential.
- Team lists with ESPN IDs and abbreviations, for joining with other data.
- Rosters with jersey number, position, height, weight, age and college.
- Pay only for rows saved.

### How to use ESPN Sports Scraper

1. Enter one or more leagues as `sport/league` (for example `basketball/nba` or `soccer/eng.1`).
2. Choose the data: games, standings, teams or players.
3. For games, set the start date and the end date (YYYY-MM-DD).
4. Run it and download the dataset as JSON, CSV, Excel or HTML, or read it through the API.

### Example input

```json
{
    "leagues": ["basketball/nba"],
    "dataType": "games",
    "dateFrom": "2026-10-15",
    "dateTo": "2026-10-22",
    "maxResults": 60
}
```

### Example output

Real rows from runs on 2026-10-23.

Game (NBA, 2026-10-15):

```json
{
    "kind": "game",
    "league": "nba",
    "sport": "basketball",
    "itemId": "401908945",
    "name": "Toronto Raptors at New York Knicks",
    "date": "2026-10-15T23:30Z",
    "statusState": "post",
    "statusDetail": "Final",
    "homeTeam": "New York Knicks",
    "homeScore": 122,
    "awayTeam": "Toronto Raptors",
    "awayScore": 120,
    "winner": "home",
    "venue": "Madison Square Garden",
    "city": "New York",
    "attendance": 19812,
    "broadcast": null,
    "url": "https://www.espn.com/nba/game/_/gameId/401908945/raptors-knicks",
    "position": 1
}
```

Standing (Premier League, `eng.1`):

```json
{
    "kind": "standing",
    "league": "eng.1",
    "sport": "soccer",
    "group": "2026-27 English Premier League",
    "itemId": "382",
    "name": "Manchester City",
    "teamId": "382",
    "teamName": "Manchester City",
    "teamAbbreviation": "MNC",
    "location": "Manchester City",
    "gamesPlayed": 7,
    "wins": 7,
    "losses": 0,
    "ties": 0,
    "points": 21,
    "pointsFor": 19,
    "pointsAgainst": 7,
    "pointDifferential": 12,
    "url": "https://www.espn.com/soccer/club/_/id/382/manchester-city",
    "position": 1
}
```

### Data table

| `dataType` | Rows | Main fields |
|---|---|---|
| `games` | one per game | teams, scores, winner, status, venue, city, attendance, broadcast |
| `standings` | one per team in the table | group, wins, losses, ties, win percent, points, point differential, streak, games behind |
| `teams` | one per team | team ID, name, abbreviation, location, link |
| `players` | one per player on the rosters of the first teams | athlete ID, jersey, player position, height, weight, age, experience, college |

Fields that a league does not publish (for example `points` in basketball) are left empty.

### Input parameters

- **Leagues**: `sport/league` paths. Several leagues per run.
- **Data to collect**: games, standings, teams or players.
- **Games from / to (date)**: YYYY-MM-DD. The end date is inclusive, up to 31 days. Empty start date means today (UTC). One request is made per day.
- **Max results per league**: 1 to 1000.
- **Max teams for players**: how many team rosters to load (players mode only).

### Pricing

Pay per row saved (see the Actor page for the current price). The run stops before it would exceed your max total charge.

### ESPN Sports Scraper vs. the ESPN website

This Actor calls ESPN's public site API and returns one structured row per game, standing, team or player. It does not provide odds, play-by-play, news or video.

### Using ESPN Sports Scraper with AI agents and MCP

Use it from the Apify MCP server or the API with a league and a date range. Pay-per-event pricing is charged per row, so an agent that sets a `maxTotalChargeUsd` never goes over that budget.

### FAQ

**Why is a game missing?**
ESPN lists a game on the day it is scheduled. Check the date range; each date is requested on its own.

**Does it include player statistics (points, rebounds, goals)?**
No. This version returns roster information for players, not season or game statistics.

**Why does the date range have a 31-day limit?**
ESPN's scoreboard does not accept date ranges, so the Actor asks one day at a time. The limit keeps one run from making too many requests.

### Support and feedback

If you find a problem, open an issue in the Actor's Issues tab. A review helps other users find it.

# Actor input Schema

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

League paths as sport/league, e.g. `basketball/nba`, `football/nfl`, `baseball/mlb`, `hockey/nhl`, `soccer/eng.1` (Premier League), `soccer/esp.1` (La Liga).

## `dataType` (type: `string`):

games: scores and schedule. standings: league table. teams: team list. players: team rosters.

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

Games only. Start date as YYYY-MM-DD (e.g. 2026-10-22). Leave empty for today.

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

Games only. End date as YYYY-MM-DD, inclusive (max 31 days; one request per day). Leave empty to use the start date.

## `maxResults` (type: `integer`):

Maximum rows per league. Standings and rosters are capped by what ESPN returns.

## `maxTeams` (type: `integer`):

Players mode only: how many teams to load rosters for.

## Actor input object example

```json
{
  "leagues": [
    "basketball/nba"
  ],
  "dataType": "games",
  "dateFrom": "",
  "dateTo": "",
  "maxResults": 100,
  "maxTeams": 30
}
```

# Actor output Schema

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

All results from this run.

# 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": [
        "basketball/nba"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("webdatatools/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": ["basketball/nba"] }

# Run the Actor and wait for it to finish
run = client.actor("webdatatools/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": [
    "basketball/nba"
  ]
}' |
apify call webdatatools/espn-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,webdatatools/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/dp8beIqol9HAxDdlg/builds/e1UGtUcaLg9DUFnmi/openapi.json