# ESPN Scraper - Scores, Standings, Rosters & News (`kmscrape/espn-scraper`) Actor

Get ESPN sports data as clean JSON: live and past scores, standings, teams, rosters and news for NFL, NBA, MLB, NHL, college, Premier League, La Liga, Champions League, F1, UFC, ATP/WTA and more. $1 per 1,000 results.

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

## Pricing

from $1.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## ESPN Sports Data Scraper

Collect ESPN sports data as structured dataset rows for research, dashboards, fantasy workflows, and feeds for AI agents / MCP tools.

### What it collects

- **Scoreboards:** game/event ID, scheduled date, status, teams and scores, venue, odds/spread when supplied, broadcasts, and leaders.
- **Standings:** league or conference groups, rank when supplied, team record and available stats.
- **Teams:** team ID, display name, abbreviation, location, logo, and ESPN page.
- **Rosters:** player rows with team, position, jersey, available bio/status fields, and headshot.
- **League news:** headline, description, publication time, author and article URL.

Available league IDs: `nfl`, `nba`, `wnba`, `mlb`, `nhl`, `college-football`, `mens-college-basketball`, `mls`, `premier-league`, `la-liga`, `serie-a`, `bundesliga`, `ligue-1`, `champions-league`, `f1`, `ufc`, `tennis-atp`, and `tennis-wta`. ESPN returns empty datasets for some combinations, such as UFC standings or tennis team rosters; those sources can complete successfully with zero rows.

### Input

```json
{
  "leagues": ["nba", "premier-league"],
  "dataTypes": ["scoreboard"],
  "dateFrom": "2026-10-09",
  "dateTo": "2026-10-09",
  "maxItemsPerSource": 50
}
```

The prefilled run selects NBA and Premier League scoreboards for today. If dates are omitted, the actor uses the current UTC date. `dateTo` can extend the scoreboard query to a date range of up to 63 days. `maxItemsPerSource` defaults to 500 (prefill 50). Unknown league names produce a free error row.

### Output example

Trimmed from a real ESPN scoreboard result:

```json
{
  "type": "game",
  "league": "nba",
  "eventId": "401898395",
  "name": "Houston Rockets at Dallas Mavericks",
  "date": "2026-10-09T12:00Z",
  "status": "Final",
  "homeTeam": { "id": "6", "name": "Dallas Mavericks", "abbreviation": "DAL" },
  "awayTeam": { "id": "10", "name": "Houston Rockets", "abbreviation": "HOU" },
  "homeScore": "117",
  "awayScore": "135",
  "venue": { "name": "Venetian Arena" },
  "broadcasts": [{ "market": "national", "names": ["NBA TV"] }]
}
```

Each data row is charged as the `result` event. Summary and error rows are free.

**Price: $1.00 per 1,000 results**

### Notes and FAQ

**Are live scores guaranteed?** No. ESPN's public JSON endpoints may change, and schedules vary by date. Empty scoreboards are valid when no events are scheduled.

**How are rosters collected?** The actor fetches the selected league's team list, then requests each team's roster. Roster mode can take longer and emits player rows up to the per-source cap.

**Does the actor fetch game summaries?** No. ESPN's event summary endpoint is available for some events, but this actor currently returns scoreboard data only and does not make extra summary requests per game.

**Do all leagues support every data type?** The endpoints respond for the league list above. Some sports do not expose meaningful team rosters or standings through the same ESPN API routes; empty results are possible.

**Can I use these rows with an AI agent or MCP server?** Yes. Dataset rows are JSON and can be consumed as an agent or MCP data source.

# Actor input Schema

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

League IDs: nfl, nba, wnba, mlb, nhl, college-football, mens-college-basketball, mls, premier-league, la-liga, serie-a, bundesliga, ligue-1, champions-league, f1, ufc, tennis-atp, tennis-wta.

## `dataTypes` (type: `array`):

Select scoreboard, standings, teams, rosters, and/or news. Roster retrieval follows the team list and may make one request per team.

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

Scoreboard start date in YYYY-MM-DD. The default run uses today's UTC date.

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

Optional scoreboard end date in YYYY-MM-DD; leave empty for a single date.

## `maxItemsPerSource` (type: `integer`):

Maximum charged rows emitted for each league and selected data type. Rosters are capped after collecting players.

## Actor input object example

```json
{
  "leagues": [
    "nba",
    "premier-league"
  ],
  "dataTypes": [
    "scoreboard"
  ],
  "dateFrom": "2026-10-09",
  "dateTo": "2026-10-09",
  "maxItemsPerSource": 50
}
```

# Actor output Schema

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

No description

# 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": [
        "nba",
        "premier-league"
    ],
    "dataTypes": [
        "scoreboard"
    ],
    "dateFrom": "2026-10-09",
    "dateTo": "2026-10-09",
    "maxItemsPerSource": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("kmscrape/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": [
        "nba",
        "premier-league",
    ],
    "dataTypes": ["scoreboard"],
    "dateFrom": "2026-10-09",
    "dateTo": "2026-10-09",
    "maxItemsPerSource": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("kmscrape/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": [
    "nba",
    "premier-league"
  ],
  "dataTypes": [
    "scoreboard"
  ],
  "dateFrom": "2026-10-09",
  "dateTo": "2026-10-09",
  "maxItemsPerSource": 50
}' |
apify call kmscrape/espn-scraper --silent --output-dataset

```

## MCP server setup

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