# ESPN Sports Scores & Schedules (`deomoreo/espn-sports`) Actor

Live scores, final results and upcoming schedules from ESPN for soccer (Premier League, Serie A, LaLiga, Bundesliga, Ligue 1, Champions League, MLS), NBA, NFL, college football, MLB, NHL and more: teams, scores, status, venue, TV channels and betting line for every game. Pay only per game delivered.

- **URL**: https://apify.com/deomoreo/espn-sports.md
- **Developed by:** [Francesco Marotta](https://apify.com/deomoreo) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 game delivereds

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 Scores & Schedules

Get **live scores, final results and upcoming schedules** from ESPN for the world's main leagues: Premier League, Serie A, LaLiga, Bundesliga, Ligue 1, Champions League, MLS, NBA, NFL, college football, MLB, NHL and many more. One clean item per game with teams, score, winner, status, venue, TV channels and betting line. No API key, no browser. You pay only per game delivered.

### What you get

| Field | Description |
|---|---|
| `gameId` | ESPN's ID of the game (results are deduplicated by it) |
| `sport`, `league`, `leagueName` | For example `soccer`, `eng.1`, `English Premier League` |
| `date` | Start time (ISO, UTC) |
| `status` | `scheduled`, `in_progress`, `final`, `postponed`, `canceled`, `suspended`, `abandoned`, `delayed`, `unknown` (a status ESPN has not documented) |
| `statusDetail` | ESPN's text: `Final`, `FT`, `67'`, `Top 5th`, `Sat, October 10th at 9:00 AM EDT`... |
| `homeTeam`, `awayTeam` | `name`, `abbreviation`, `score` (null until the game starts) and `winner` (true/false once final) |
| `venue`, `city` | Stadium or arena and its city |
| `broadcasts` | TV and streaming channels |
| `odds` | Betting line summary when ESPN has one, for example `NOR -3.5, O/U 47.5` |
| `espnUrl` | The game page on espn.com |

Example item (fictional teams):

```json
{
  "gameId": "401000001",
  "sport": "football",
  "league": "nfl",
  "leagueName": "National Football League",
  "date": "2026-09-27T17:00:00.000Z",
  "status": "final",
  "statusDetail": "Final",
  "homeTeam": { "name": "Northfield Rovers", "abbreviation": "NOR", "score": 24, "winner": true },
  "awayTeam": { "name": "Harbor City Gulls", "abbreviation": "HCG", "score": 17, "winner": false },
  "venue": "Example Park",
  "city": "Northfield",
  "broadcasts": ["NET1"],
  "odds": "NOR -3.5, O/U 47.5",
  "espnUrl": "https://www.espn.com/nfl/game/_/gameId/401000001"
}
```

### How to use

1. In **Leagues**, list ESPN `sport/league` codes (the same ones in ESPN URLs):

   | League | Code |
   |---|---|
   | Premier League, LaLiga, Serie A, Bundesliga, Ligue 1 | `soccer/eng.1`, `soccer/esp.1`, `soccer/ita.1`, `soccer/ger.1`, `soccer/fra.1` |
   | Champions League, Europa League, MLS | `soccer/uefa.champions`, `soccer/uefa.europa`, `soccer/usa.1` |
   | NBA, WNBA | `basketball/nba`, `basketball/wnba` |
   | NFL, college football (FBS) | `football/nfl`, `football/college-football` |
   | MLB, NHL | `baseball/mlb`, `hockey/nhl` |

   Other ESPN leagues work the same way (`soccer/ned.1`, `soccer/por.1`, `soccer/bra.1`...). ESPN filters can be appended: `basketball/mens-college-basketball?groups=50` returns every Division I game instead of the featured ones, `football/college-football?groups=81` returns FCS games.
2. Set **From date** and **To date** as `YYYY-MM-DD`, or relative: `today`, `yesterday`, `tomorrow`, `-7`, `+3`. Both empty means today. Up to 366 days per run. Days follow ESPN's calendar (US Eastern time), so an evening game in the Americas stays on its local day even when it ends after midnight UTC.
3. Optionally set **Max games per league** (default 500).
4. Run, then export as JSON, CSV or Excel, or call the Actor through the API, Make, Zapier, n8n or an AI agent via MCP.

Tip: schedule the Actor every morning with **From date** `yesterday` and **To date** `+7` to keep results and the coming week's fixtures up to date.

### Use cases

- **Sports apps, bots and widgets**: fixtures and results without maintaining your own scraper.
- **Betting and fantasy research**: historical results with closing lines, upcoming games with the current line.
- **Newsletters and media**: weekly schedules with kick-off times and TV channels.
- **Data analysis and AI agents**: full seasons of results in one structured dataset.

### Pricing

**$1 per 1,000 games** ($0.001 each), charged only for games delivered. A game is charged once per run even if it appears on more than one day. Leagues with no games in the period, unknown leagues and failed requests are reported and free. The run stops by itself when your spending limit is reached.

### Errors (not charged)

Each league that cannot be completed produces one item with `input`, `error` and `message`:

- `NO_GAMES`: the league has no games in the chosen period (off-season, international break).
- `LEAGUE_NOT_FOUND`: ESPN does not know this `sport/league` code; check it in the ESPN URL.
- `INVALID_INPUT`: the league is not written as `sport/league`.
- `BLOCKED` / `RATE_LIMITED` / `UPSTREAM_ERROR`: ESPN refused the request after all retries (the Actor retries each day automatically with fresh datacenter and then residential proxies).
- `INTERNAL_ERROR`: an unexpected problem; please report it in the Issues tab.

An invalid date or an empty league list stops the run with a clear message before anything is charged.

### FAQ

**Where does the data come from?** From the public JSON feeds that power ESPN's own scoreboards. The Actor reads only public schedules and results and does not log in. It is not affiliated with or endorsed by ESPN.

**Are scores live?** Yes: a run during a game returns the current score with `status: in_progress` and the clock or period in `statusDetail`. ESPN caches this feed for only a few seconds.

**Why is `odds` often empty?** ESPN shows a line mainly for upcoming US games (NFL, NBA, MLB, NHL) and some soccer totals. Past games usually have none.

**Does it cover individual sports?** Only their team events. Individual events (golf and tennis tournaments, races, fight cards) have no home and away team and are skipped; team events such as golf's Presidents Cup are returned and charged as games.

**Why are player stats not included?** The Actor returns game-level data only, which keeps it fast and cheap and avoids personal data.

### Other Actors by the same developer

- [YouTube Transcript & Subtitles Extractor](https://apify.com/Deomoreo/youtube-transcript): transcripts of any YouTube video as text, timestamps or SRT.
- [Google Ads Transparency Center Scraper](https://apify.com/Deomoreo/google-ads-transparency): every Google ad an advertiser runs, by brand, domain or advertiser ID.
- [Google News Scraper with Real Article URLs](https://apify.com/Deomoreo/google-news): Google News by keyword or topic, with the publisher's real article URLs.

# Actor input Schema

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

ESPN sport/league codes, as in ESPN URLs. Soccer: soccer/eng.1 (Premier League), soccer/esp.1 (LaLiga), soccer/ita.1 (Serie A), soccer/ger.1 (Bundesliga), soccer/fra.1 (Ligue 1), soccer/uefa.champions, soccer/uefa.europa, soccer/usa.1 (MLS). US sports: basketball/nba, basketball/wnba, football/nfl, football/college-football, baseball/mlb, hockey/nhl. ESPN filters can be appended, for example basketball/mens-college-basketball?groups=50 for every Division I game.

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

First day, as YYYY-MM-DD, or relative: today, yesterday, tomorrow, -7 (7 days ago), +3. Empty means today. Days follow ESPN's calendar (US Eastern time).

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

Last day (included), same formats as From date. Empty means today (or From date, if that is in the future). Up to 366 days per run.

## `maxGamesPerLeague` (type: `integer`):

Stop after this many games for each league.

## `proxyConfiguration` (type: `object`):

Apify datacenter proxy is used by default.

## `residentialFallback` (type: `boolean`):

Retry requests that ESPN refuses through a residential proxy.

## Actor input object example

```json
{
  "leagues": [
    "soccer/eng.1",
    "basketball/nba"
  ],
  "maxGamesPerLeague": 500,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "residentialFallback": true
}
```

# Actor output Schema

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

No description

## `overview` (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": [
        "soccer/eng.1",
        "basketball/nba"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("deomoreo/espn-sports").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": [
        "soccer/eng.1",
        "basketball/nba",
    ],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("deomoreo/espn-sports").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": [
    "soccer/eng.1",
    "basketball/nba"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call deomoreo/espn-sports --silent --output-dataset

```

## MCP server setup

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

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/YLgxXZoCfU61yJbdQ/builds/jlCVYgRCUtgUG8j4V/openapi.json