# ESPN Live Scores, Schedules & Game Odds Scraper (`nimbryxo-studio/espn-live-scores-schedules-and-game-odds-scraper`) Actor

Get live scores, final results and upcoming fixtures for 16 leagues across basketball, football, baseball, hockey and soccer, with optional per-game leaders, odds, attendance and headlines.

- **URL**: https://apify.com/nimbryxo-studio/espn-live-scores-schedules-and-game-odds-scraper.md
- **Developed by:** [Nimbryxo-studio](https://apify.com/nimbryxo-studio) (community)
- **Categories:** Automation, Developer tools, News
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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

## ESPN Game Center Scraper: Scores, Schedules, Teams & Odds

Read ESPN game centers without an account, API key, or proxy setup. Pick a competition and a day, month, season, or week to get live scoreboards, final results, upcoming fixtures, team directories, sportsbook lines, and full game details in one dataset.

The actor covers more than 60 team competitions across basketball, football, baseball, hockey, and soccer, including the NBA, WNBA, NFL, MLB, NHL, MLS, NWSL, the Premier League, La Liga, Bundesliga, Serie A, Ligue 1, Liga MX, the Champions League, and many more. Every field ESPN publishes for the selected record type is mapped, and fields ESPN does not provide for a particular game are left out instead of being sent empty.

### What this actor does

- **Five modes:** `scoreboard`, `schedule`, `teams`, `odds`, and `gameDetail`
- **Date and season control:** a single day, a month, a year, a custom range up to 366 days, a season, or a football-style season week
- **Team filtering:** match a team by ESPN ID, abbreviation, or name, with an optional league prefix
- **Full odds records:** one row per sportsbook line with spread, total, moneylines, and open, close, and current values when ESPN publishes them
- **Deep game detail:** leaders, officials, venue, broadcasts, attendance, article text, team stats, player stats, and injuries
- **Empty fields are omitted:** empty values are omitted at every depth, and every record carries `recordType`, `sourceUrl` where available, and `scrapedAt`

### Output per game (`mode = scoreboard` or `schedule`)

- `gameId`, `competitionId` - ESPN event and competition IDs
- `league`, `sport` - league code and sport
- `status` - `scheduled`, `in_progress`, `final`, `postponed`, or `cancelled`
- `statusState`, `statusDescription`, `statusShortDetail`, `completed`, `period`, `clock`, `displayClock` - live state details
- `date` - kickoff in ISO 8601 UTC
- `dateLocal` - kickoff in the requested timezone
- `name`, `shortName` - full and abbreviated matchup
- `seasonYear`, `seasonType`, `week` - season context when ESPN provides it
- `homeTeam`, `awayTeam` - team objects with `id`, `name`, `abbreviation`, `logo`, `score`, `winner`, `record`, `lineScores`, colors, and location when published
- `venue` - `name`, `city`, `state`, `country`, `indoor`, `grass`, and `imageUrl`
- `broadcasts` - TV and streaming network names
- `attendance`, `neutralSite`, `conferenceCompetition`, `competitionType`
- `headlines`, `gameNotes` - game-specific notes
- `odds` - the line shown on the scoreboard, when present
- `sourceUrl`, `recordType`, `scrapedAt`

### Output per team (`mode = teams`)

- `teamId`, `league`, `sport`
- `name`, `abbreviation`, `location`, `nickname`, `shortDisplayName`, `slug`
- `logo`, `color`, `alternateColor`, `isActive`, `isAllStar`
- `venue` - `name`, `city`, `state`, `country`, `indoor`, `grass`, and `imageUrl`
- `groupId`, `groupName`, `conferenceId`, `standingSummary`
- `recordStats` - ESPN overall-record statistics as a name/value object
- `sourceUrl`, `recordType`, `scrapedAt`

### Output per odds line (`mode = odds`)

- `gameId`, `league`, `sport`, `gameName`, `gameDate`
- `homeTeamId`, `homeTeamName`, `homeTeamAbbreviation`
- `awayTeamId`, `awayTeamName`, `awayTeamAbbreviation`
- `provider`, `providerId` - sportsbook name and ESPN provider ID
- `details`, `spread`, `overUnder`, `overOdds`, `underOdds`
- `homeMoneyline`, `awayMoneyline`, `drawMoneyline` - when the sport supports them
- `homeSpreadOdds`, `awaySpreadOdds`
- `homeTeamOdds`, `awayTeamOdds`, `drawOdds` - full side detail with favorite/underdog flags
- `open`, `close`, `current` - period values when ESPN keeps them
- `sourceUrl`, `recordType`, `scrapedAt`

### Output per game detail (`mode = gameDetail`)

A game-detail record includes every game field above, plus:

- `leaders` - top performers grouped as `home` and `away`, each with `name`, `position`, `stat`, and `value`
- `officials` - referee names and positions
- `articleDescription`, `articleStory`, `articlePublished`, `articleUrl`, `articleImage`
- `teamStats` - team totals with stat name, label, abbreviation, and display value
- `playerStats` - player stat categories, labels, and per-player values
- `injuries` - team injury entries with athlete, status, date, and detail
- `headline`, `gameNotes`, `attendance`, `venue`, `broadcasts`, `odds`
- `recordType: "gameDetail"`, `sourceUrl`, `scrapedAt`

If ESPN fails to answer for a league, the actor writes a diagnostic record with `type`, `reason`, `message`, `inputLeague`, `inputDate`, `error`, `recordType`, and `scrapedAt`. Game, team, odds, and detail records are never replaced by placeholders.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `scoreboard` | `scoreboard`, `schedule`, `teams`, `odds`, or `gameDetail` |
| `sport` | string | `any` | Sport filter; use with League = All supported leagues |
| `league` | string | - | Competition code or All supported leagues; the daily prefill uses `nba` |
| `date` | string | - | Day, month, or year; empty means today; the daily prefill uses `20240115` |
| `startDate` | string | - | First day of a custom window; requires `endDate` |
| `endDate` | string | - | Last day of a custom window; up to 366 days |
| `season` | integer | - | ESPN season year, e.g. `2024` |
| `seasonType` | string | `2` | `1` preseason, `2` regular, `3` postseason, `4` offseason, `5` play-in |
| `week` | integer | - | Week number; requires `season` |
| `team` | string | - | ESPN team ID, abbreviation, or name; prefix with a league code if needed |
| `eventIds` | array | `[]` | Event IDs for `odds` or `gameDetail`; requires one specific league, not All supported leagues |
| `status` | string | `any` | `any`, `scheduled`, `in_progress`, `final`, `postponed`, or `cancelled` |
| `includeDetails` | boolean | `false` | Add leaders, stats, officials, article text, and injuries to each game |
| `maxItems` | integer | `100` | Hard cap from 1 to 10,000 records |
| `timezone` | string | `UTC` | IANA timezone for relative dates and `dateLocal` |

#### Example: today's NBA and NHL scoreboard

```json
{
  "mode": "scoreboard",
  "league": "nba",
  "date": "2026-11-02",
  "maxItems": 50
}
```

#### Example: NFL Week 1

```json
{
  "mode": "schedule",
  "league": "nfl",
  "season": 2023,
  "seasonType": "2",
  "week": 1,
  "maxItems": 50
}
```

#### Example: every Arsenal fixture in a season

```json
{
  "mode": "schedule",
  "league": "epl",
  "season": 2024,
  "team": "Arsenal",
  "maxItems": 100
}
```

For current and future soccer seasons, the actor falls back to scoreboard windows when ESPN's team-schedule feed returns only completed matches, so upcoming fixtures are included.

#### Example: sportsbook lines for a day

```json
{
  "mode": "odds",
  "league": "nba",
  "date": "2024-01-15",
  "maxItems": 100
}
```

#### Example: full detail for two games

```json
{
  "mode": "gameDetail",
  "league": "nba",
  "eventIds": ["401585183", "401585184"],
  "maxItems": 2
}
```

### Use cases

- **Live scoreboards** - refresh a dashboard with every game in one or more leagues
- **Fixture calendars** - export a team's or league's upcoming schedule for a season or date range
- **Results archives** - collect final scores, venues, and broadcasts across a historical window
- **Betting analysis** - capture spread, total, moneyline, and line movement snapshots
- **Fantasy and media tools** - pull leaders, team stats, player stats, and recaps for recaps and previews
- **Research and data pipelines** - join stable ESPN IDs to internal models, spreadsheets, or warehouses

### FAQ

**Do I need an ESPN account, API key, cookie, or proxy?**

No. The actor reads ESPN's public game data directly. You only choose the mode and the competition or date.

**Which competitions are supported?**

More than 60 team competitions across basketball, football, baseball, hockey, and soccer. The League dropdown lists every supported code, from the NBA and NFL to the Premier League, La Liga, Bundesliga, Serie A, Ligue 1, Liga MX, the Champions League, and many national leagues.

**Why does a date return no games?**

Not every league plays every day. Use a season or a date range for fixtures, or pick a day when the league is active. The terminal run status message explains the mode, league, and record count, including zero-record runs.

**What is the largest date range?**

A custom range can cover up to 366 days. Long windows are read month by month, and a month that hits ESPN's per-request event cap is re-read day by day so games are not skipped.

**Why are some odds fields missing?**

ESPN publishes one line per sportsbook provider per game and often removes lines after the game ends, so provider coverage varies by event. Soccer lines can use moneyline and draw prices instead of a spread and total, and some providers publish fractional moneyline strings such as `20/1` or `1/28`; the actor returns the value ESPN publishes. The actor includes only the values ESPN actually returns.

**Why do some games have no stats or leaders?**

ESPN does not publish every section for every sport, game state, or competition. Missing sections are omitted from the record rather than filled with placeholders.

**Can I get games for a team by name?**

Yes. Set `team` to the ESPN ID, abbreviation, or a name such as `Lakers` or `Arsenal`. If the same abbreviation exists in multiple leagues, prefix it with the league code, for example `nba:LAL`.

**How fresh is the data?**

Every run reads ESPN's live game data at run time. Schedule the actor every few minutes during game windows for live scores, or daily for schedules and results.

**Does this actor cover golf, tennis, MMA, or racing?**

No. It focuses on team-game records. Individual sports use different event and leaderboard shapes and are not part of this actor.

**Does it include news, standings, or rosters?**

No. This actor focuses on scoreboards, schedules, teams, odds, and game detail. News, standings, and roster data are separate jobs.

**Does it include play-by-play or win-probability timelines?**

No. Game detail covers box-score data: leaders, team and player stats, officials, injuries, venue, broadcasts, attendance, and recaps. Play-by-play feeds are much larger and are outside this actor's record contract.

**Why can a game in a date window show the next UTC day?**

ESPN assigns games to its own local event date. The `date` field is UTC, so a late local game can fall on the next UTC day. This affects single days, months, years, and custom ranges. Use `dateLocal` for the requested timezone, or widen the window by one day when joining on UTC dates.

**What happens if I use event IDs with All supported leagues?**

Event IDs need one specific league because ESPN's summary path includes the sport and league. With All supported leagues the actor returns a diagnostic record asking you to choose a league; it does not guess across 60+ competitions.

**Is `seasonType` the same across sports?**

For US sports it is a canonical label such as `Regular season`, `Preseason`, `Postseason`, or `Play-in`. For soccer ESPN often publishes a season slug such as `2024-25 English Premier League`, so treat `seasonType` as source text rather than a stable cross-sport enum.

**What are the hard limits?**

ESPN removes some odds and stat sections after a game, so those fields are omitted when the source no longer has them. One scoreboard response is capped at 1,000 events; month and year requests are split automatically, but a single day above 1,000 events is not subdivided. Date windows follow ESPN's local event date, so the UTC `date` can fall on the next day. Individual sports (golf, tennis, MMA, racing), news, standings, and rosters are outside this actor.

**Is this affiliated with ESPN?**

No. This is an independent, third-party actor that reads ESPN's public game data. It is not affiliated with or endorsed by ESPN.

# Actor input Schema

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

What to return: games for a scoreboard, a schedule, the league team directory, one record per sportsbook odds line, or a full game detail record.

## `sport` (type: `string`):

Optional sport filter. Use it with League = All supported leagues to cover every supported competition in one sport.

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

Competition to read. Choose All supported leagues only with a specific sport when you need broad coverage. Defaults to NBA when omitted.

## `date` (type: `string`):

A day (YYYY-MM-DD or YYYYMMDD), a month (YYYY-MM), or a year (YYYY). Leave empty to use today, or use Season / Week instead. (mode=scoreboard, schedule, odds, gameDetail)

## `startDate` (type: `string`):

First day of a custom window (YYYY-MM-DD or YYYYMMDD). Requires End date. (mode=scoreboard, schedule, odds, gameDetail)

## `endDate` (type: `string`):

Last day of a custom window (YYYY-MM-DD or YYYYMMDD). Maximum 366 days. (mode=scoreboard, schedule, odds, gameDetail)

## `season` (type: `integer`):

ESPN season year, for example 2024. Use it with Week for a single football week, or alone for the whole season. (mode=scoreboard, schedule, odds, gameDetail)

## `seasonType` (type: `string`):

Which part of the season to read when Season is set. (mode=scoreboard, schedule, odds, gameDetail)

## `week` (type: `integer`):

Week number for football and other week-based competitions. Requires Season. (mode=scoreboard, schedule, odds, gameDetail)

## `team` (type: `string`):

Keep only games or teams matching this ESPN team ID, abbreviation, or name, for example 13, LAL, or Lakers. Prefix with a league code to disambiguate: nba:LAL. (mode=scoreboard, schedule, teams, odds, gameDetail)

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

ESPN event IDs for game detail or odds, for example 401585183. Leave empty to discover games from the date or season. (mode=odds, gameDetail)

## `status` (type: `string`):

Keep only games in this state. Postponed and cancelled games are reported as their own values.

## `includeDetails` (type: `boolean`):

Add leaders, odds, attendance, officials, article text, team stats, player stats and injuries to each game. (mode=scoreboard, schedule)

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

Hard cap on records returned across all selected leagues.

## `timezone` (type: `string`):

IANA timezone used for today/yesterday/tomorrow and for dateLocal, for example America/New_York.

## Actor input object example

```json
{
  "mode": "scoreboard",
  "sport": "any",
  "league": "nba",
  "date": "20240115",
  "seasonType": "2",
  "eventIds": [],
  "status": "any",
  "includeDetails": false,
  "maxItems": 3,
  "timezone": "UTC"
}
```

# Actor output Schema

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

All game, team, odds, and game-detail records in the default dataset.

# 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 = {
    "mode": "scoreboard",
    "sport": "any",
    "league": "nba",
    "date": "20240115",
    "seasonType": "2",
    "eventIds": [],
    "status": "any",
    "includeDetails": false,
    "maxItems": 3,
    "timezone": "UTC"
};

// Run the Actor and wait for it to finish
const run = await client.actor("nimbryxo-studio/espn-live-scores-schedules-and-game-odds-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 = {
    "mode": "scoreboard",
    "sport": "any",
    "league": "nba",
    "date": "20240115",
    "seasonType": "2",
    "eventIds": [],
    "status": "any",
    "includeDetails": False,
    "maxItems": 3,
    "timezone": "UTC",
}

# Run the Actor and wait for it to finish
run = client.actor("nimbryxo-studio/espn-live-scores-schedules-and-game-odds-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 '{
  "mode": "scoreboard",
  "sport": "any",
  "league": "nba",
  "date": "20240115",
  "seasonType": "2",
  "eventIds": [],
  "status": "any",
  "includeDetails": false,
  "maxItems": 3,
  "timezone": "UTC"
}' |
apify call nimbryxo-studio/espn-live-scores-schedules-and-game-odds-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nimbryxo-studio/espn-live-scores-schedules-and-game-odds-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/gfEsNaZg6cUWKfAcj/builds/nXre0KcQ0wFMsE4p4/openapi.json