# ESPN API Scraper (`rl1987/espn-api-scraper`) Actor

Scrapes ESPN's unofficial public API for scores, schedules, box scores, and search.

- **URL**: https://apify.com/rl1987/espn-api-scraper.md
- **Developed by:** [R.L.](https://apify.com/rl1987) (community)
- **Categories:** 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 output rows

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### What does ESPN API Scraper do?

**ESPN API Scraper** extracts live scores, schedules, box scores, play-by-play, and search results straight from ESPN's own mobile-app data feed at [espn.com](https://www.espn.com), no HTML parsing involved. It covers any sport/league ESPN tracks — NFL, NBA, college sports, soccer leagues worldwide, and more. Run it on the Apify platform to get scheduled, proxy-backed, monitored data pulls without maintaining scraping infrastructure yourself.

### Why use ESPN API Scraper?

- **Sports betting & fantasy tools** — pull live scores and schedules to power odds trackers or fantasy lineup apps.
- **Media & content** — feed box scores and play-by-play into recap articles or highlight generators.
- **Analytics** — build historical game datasets for stats models.
- **Search** — resolve team/player/article names to ESPN IDs for downstream lookups.

### How to use ESPN API Scraper?

1. Click **Try for free** or set up the Actor in Apify Console.
2. Pick a **Mode** (scoreboard, team schedule, game summary, or search) and fill in the matching fields.
3. Click **Start** and wait for the run to finish.
4. Download results from the **Dataset** tab, or pull them via the Apify API.

### Input

| Field | Type | Used by | Description |
|---|---|---|---|
| `mode` | string | all | `scoreboard`, `teamSchedule`, `gameSummary`, or `search` |
| `league` | select | scoreboard, teamSchedule, gameSummary | Pick a league from the dropdown (NFL, NBA, Premier League, etc.) |
| `dateFrom` / `dateTo` | date | scoreboard | Pick a day, or a from/to range, from the date picker; omit for today |
| `teamAbbr` | string | teamSchedule | Team abbreviation, e.g. `dal` |
| `eventIds` | array | gameSummary | One or more ESPN event IDs (get them from a scoreboard run's output) |
| `query` | string | search | Free-text search query |
| `searchLimit` | integer | search | Max search results (default 10) |

See the **Input** tab for the full schema.

#### Finding a team abbreviation

`teamSchedule` mode needs ESPN's short team code (e.g. `dal` for the Dallas Cowboys, `lal` for the LA Lakers), not the full team name. Two ways to find it:

1. Open the team's page on [espn.com](https://www.espn.com) — the code sits right after the team ID in the URL, e.g. `espn.com/nfl/team/_/name/dal/dallas-cowboys` → `dal`.
2. Run this Actor in `search` mode with the team name as the query; the result includes the team's `abbreviation` field.

### Output

Output rows are flat — no digging through nested `competitions[0].competitors[]` objects. Example scoreboard item:

```json
{
    "eventId": "401873272",
    "date": "2026-08-13T23:00Z",
    "name": "Detroit Lions at Cincinnati Bengals",
    "statusDetail": "Final",
    "completed": true,
    "venueName": "Paycor Stadium",
    "venueCity": "Cincinnati",
    "venueState": "OH",
    "homeTeam": "Cincinnati Bengals",
    "homeAbbr": "CIN",
    "homeScore": "16",
    "homeWinner": true,
    "awayTeam": "Detroit Lions",
    "awayAbbr": "DET",
    "awayScore": "14",
    "awayWinner": false
}
```

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel from the **Dataset** tab or via the API.

### Data table

**`scoreboard` / `teamSchedule`** — one row per game:

| Field | Description |
|---|---|
| `eventId` | ESPN event ID |
| `date` | Game start time |
| `name` / `shortName` | Matchup name |
| `statusDetail` / `completed` | Game state (scheduled, in-progress, final) |
| `venueName` / `venueCity` / `venueState` | Venue |
| `homeTeam` / `homeAbbr` / `homeScore` / `homeWinner` | Home team |
| `awayTeam` / `awayAbbr` / `awayScore` / `awayWinner` | Away team |
| `broadcasts` | TV/streaming networks |

**`gameSummary`** — several row types per event, distinguished by `recordType`: one `game` row (score/venue), one `teamStats` row per team (box score line), one `leader` row per stat category leader, and one `scoringPlay` row per score in the game.

**`search`** — one row per match, distinguished by `resultType` (`team`, `article`, `film`, etc.), with `displayName`, `subtitle`, and `url`.

### Pricing / Cost estimation

This Actor makes lightweight JSON API calls (no browser rendering), so runs are cheap and fast — typically a few seconds and well under 0.01 CU per run. Works on the Apify Free plan.

### Tips or advanced options

- For `gameSummary`, pass multiple `eventIds` to batch-fetch several games in one run.
- Set both `dateFrom` and `dateTo` to cover a whole week or season slate in one scoreboard run.
- Not seeing a league you need in the dropdown? Open an issue — more can be added on request.

### FAQ, disclaimers, and support

This Actor talks to ESPN's unofficial, public, unauthenticated data API — the same one ESPN's own mobile app uses. It does not use the fantasy/personalization endpoints (which require login). ESPN can change or restrict this API at any time without notice; if a run starts failing, check the Issues tab. Use responsibly and in line with ESPN's Terms of Service. For custom scraping solutions, reach out via the Issues tab.

# Actor input Schema

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

Which ESPN API endpoint to call.

## `league` (type: `string`):

League to fetch data for. Required for scoreboard, teamSchedule, gameSummary.

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

For scoreboard mode. Leave empty for today. Set only this field for a single day.

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

For scoreboard mode. Optional, only used together with 'Date from' to cover a date range.

## `teamAbbr` (type: `string`):

For teamSchedule mode. ESPN's short team code, e.g. 'dal' for the Dallas Cowboys. See README for how to find it.

## `eventIds` (type: `array`):

For gameSummary mode. ESPN event IDs to fetch full game detail for (get them from a scoreboard run's output).

## `query` (type: `string`):

For search mode. Free-text query (team, player, article, etc).

## `searchLimit` (type: `integer`):

For search mode. Max results to return.

## Actor input object example

```json
{
  "mode": "scoreboard",
  "league": "football/nfl",
  "teamAbbr": "dal",
  "eventIds": [],
  "searchLimit": 10
}
```

# Actor output Schema

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

Dataset rows produced by the 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("rl1987/espn-api-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("rl1987/espn-api-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 '{}' |
apify call rl1987/espn-api-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,rl1987/espn-api-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/edkaAnCiVQGknv8z3/builds/0JXH9zeU3sbQmu0U0/openapi.json