# ESPN Sports Data API: Scores, Odds, Standings, Rosters (`transparent_meteorite/espn-sports-data-api`) Actor

ESPN scores API and sports data scraper: live and final scores, schedules with betting odds, standings, rosters, injuries and news for NFL, NBA, MLB, NHL, NCAA and soccer. Flat rows, one per game or player, no API key.

- **URL**: https://apify.com/transparent_meteorite/espn-sports-data-api.md
- **Developed by:** [Detroit Web Agent - Open Data](https://apify.com/transparent_meteorite) (community)
- **Categories:** News, Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.36 / 1,000 row returneds

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

## ESPN Sports Data API: Scores, Odds, Standings, Rosters, Injuries & News

ESPN API scraper that turns the public ESPN JSON feeds into flat, typed rows. Pull live and final scores, upcoming schedules with spread and over/under, standings, team rosters, injury reports and news for the NFL, NBA, WNBA, MLB, NHL, NCAA football and basketball, MLS and the big European soccer leagues, in one run, with one output format, and no API key.

Every row is one game, one team, one player, one injury, one standing or one article. Rows carry the league code, so you can mix leagues in a single run and filter later in a sheet, a database or an n8n workflow.

### Run in 30 seconds

1. Open the **Input** tab. The prefilled input reads the last 7 days of scores for the NFL, NBA and NHL and stops at 25 rows.
2. Click **Start**. The default run finishes in a few seconds.
3. Open the **Output** tab and look at the **Games and scores** table, or export JSON, CSV or Excel.
4. Switch **What to get** to schedule, standings, rosters, injuries or news, change the leagues, and run again.

### What does this Actor do?

It reads the same public data feeds that power the ESPN website and app, and flattens them. You choose a data type, a list of leagues and, for games, a date window. The Actor fetches one request per league and day for games, and one request per league for standings, teams, injuries and news. Rosters take one extra request per team.

| Mode | One row is | Main fields |
|---|---|---|
| `scores` | a game, final or live | teams, scores, records, status, period, clock, winner, venue, broadcast, leaders, line scores |
| `schedule` | an upcoming game | kickoff time, teams, records, venue, broadcast, spread, over/under, moneylines |
| `standings` | a team in a table | group, placement, wins, losses, ties, win percentage, points for and against, streak, soccer points |
| `teams` | a team | id, name, abbreviation, colors, logo, links |
| `rosters` | a player | name, jersey, position, age, birth date, height, weight, experience, college, status |
| `injuries` | a reported injury | player, team, status, injury type and detail, return date, short and long comment |
| `news` | an article | headline, description, published time, byline, link, image, categories |

#### Leagues covered

NFL (`nfl`), college football (`ncaaf`), CFL (`cfl`), NBA (`nba`), WNBA (`wnba`), men's and women's college basketball (`ncaam`, `ncaaw`), MLB (`mlb`), college baseball (`ncaabaseball`), NHL (`nhl`), college hockey (`ncaahockey`), MLS (`mls`), NWSL (`nwsl`), English Premier League (`epl`), Championship (`championship`), La Liga (`laliga`), Bundesliga (`bundesliga`), Serie A (`seriea`), Ligue 1 (`ligue1`), Eredivisie (`eredivisie`), Liga MX (`ligamx`), Champions League (`ucl`) and Europa League (`uel`). Write `all` to read every league at once. Common names such as "premier league" or "college football" are understood too.

### Game fields

Games share one shape, so scores and schedules load into the same table.

| Group | Fields |
|---|---|
| Identity | `eventId`, `league`, `sport`, `season`, `seasonType`, `week`, `name`, `shortName`, `date` |
| State | `status` (pre, in, post), `statusName`, `statusDetail`, `completed`, `period`, `clock` |
| Home team | `homeTeam`, `homeTeamId`, `homeAbbr`, `homeScore`, `homeRecord`, `homeRank`, `homeWinner`, `homeLogo`, `homeLinescores` |
| Away team | `awayTeam`, `awayTeamId`, `awayAbbr`, `awayScore`, `awayRecord`, `awayRank`, `awayWinner`, `awayLogo`, `awayLinescores` |
| Result | `winner` |
| Place | `venue`, `venueCity`, `venueState`, `venueCountry`, `indoor`, `neutralSite`, `attendance`, `broadcast` |
| Odds | `oddsProvider`, `oddsDetails`, `spread`, `overUnder`, `homeMoneyline`, `awayMoneyline`, `homeFavorite` |
| Context | `headline`, `note`, `leaders` (top performer per category), `eventUrl`, `boxscoreUrl` |
| Run | `recordType`, `scrapedAt` |

Odds appear on upcoming games once a sportsbook has posted a line. Finished games usually have no odds, so those fields are `null` on final scores.

### Input

| Field | What it does |
|---|---|
| `mode` | `scores`, `schedule`, `standings`, `teams`, `rosters`, `injuries` or `news`. |
| `leagues` | League codes, one per line. Default nfl, nba, nhl. |
| `dateFrom`, `dateTo` | Date window for scores and schedule, for example 2026-11-09 and 2026-11-15. Up to 120 days per run. |
| `daysBack` | Scores without dates cover this many days up to today. Default 7. |
| `daysAhead` | Schedule without dates covers today plus this many days. Default 7. |
| `gameStatus` | Keep only `scheduled`, `live` or `final` games. |
| `teams` | Team names or abbreviations to keep, for example Lions, DET, Manchester City. |
| `season` | Standings for a past season, for example 2025. |
| `newsPerLeague` | Headlines per league in news mode. Default 25. |
| `includeOdds` | Spread, over/under and moneylines. On by default. |
| `includeLeaders` | Top performers per game. On by default. |
| `maxItems` | Hard cap on rows for the whole run. |

If a window has no games, for example in an off-season, and you gave no explicit dates, the Actor widens the search backwards (scores) or forwards (schedule) in steps of 30 and 90 days until it finds games. Your scheduled runs do not come back empty by accident, and the run says so in its status message.

### Example inputs

Last week of NBA scores for one team:

```json
{
  "mode": "scores",
  "leagues": ["nba"],
  "dateFrom": "2026-11-09",
  "dateTo": "2026-11-15",
  "teams": ["Pistons"],
  "gameStatus": "final"
}
```

Next two weeks of Premier League and MLS fixtures:

```json
{
  "mode": "schedule",
  "leagues": ["epl", "mls"],
  "daysAhead": 14
}
```

Every NBA roster:

```json
{
  "mode": "rosters",
  "leagues": ["nba"],
  "maxItems": 1000
}
```

### Output sample

```json
{
  "recordType": "score",
  "eventId": "401873053",
  "league": "nfl",
  "sport": "football",
  "season": 2026,
  "week": 10,
  "date": "2026-11-15T14:30Z",
  "name": "New England Patriots at Detroit Lions",
  "status": "post",
  "statusDetail": "Final",
  "completed": true,
  "homeTeam": "Detroit Lions",
  "homeAbbr": "DET",
  "homeScore": 35,
  "homeRecord": "7-2",
  "homeWinner": true,
  "awayTeam": "New England Patriots",
  "awayAbbr": "NE",
  "awayScore": 10,
  "awayRecord": "5-5",
  "winner": "Detroit Lions",
  "homeLinescores": [7, 14, 7, 7],
  "awayLinescores": [3, 0, 0, 7],
  "venue": "FC Bayern Munich Stadium",
  "venueCity": "Munich",
  "broadcast": "Fox",
  "spread": null,
  "overUnder": null,
  "leaders": [
    { "team": "DET", "category": "Passing Leader", "stat": "20/31, 303 YDS, 3 TD, 2 INT", "athlete": "Jared Goff", "position": "QB" }
  ],
  "eventUrl": "https://www.espn.com/nfl/game/_/gameId/401873053/patriots-lions",
  "scrapedAt": "2026-11-16T09:00:00.000Z"
}
```

The values above are an illustration. Your own run returns the live data.

### Use cases

- **Sports apps and dashboards:** feed a scoreboard, a fixtures page or a Discord and Slack bot with fresh scores and schedules on a schedule.
- **Betting research and models:** collect spreads, over/under lines and moneylines for upcoming games, then join them with final scores to test models.
- **Fantasy and injury tracking:** pull every NFL, NBA, MLB and NHL injury report each morning and alert on status changes.
- **Content and newsletters:** build a weekly recap from final scores, standings and team news without copying anything by hand.
- **Analytics and data science:** load seasons of results and standings into a warehouse for historical analysis, with one consistent column set across sports.
- **AI agents:** give an agent through the Apify MCP server a single tool that answers "who plays tonight" or "who is injured on the Lions".

### Pricing and cost control

Pay per row: **$0.0022 per row on the free plan, $0.00136 on the Gold plan** (Bronze $0.00205, Silver $0.00175), plus a $0.00005 start fee per run. That is $2.20 per 1,000 rows on the free plan. One row is one game, standing, team, player, injury or article. Nothing is charged for rows that are not returned, and a run with no results costs only the start fee.

Use **Max rows** in the input and **Maximum cost per run** in the run options to cap spend. The prefilled run returns 25 rows, which is under a cent.

| Plan | Price per row | Price per 1,000 rows |
|---|---|---|
| Free | $0.0022 | $2.20 |
| Bronze | $0.00205 | $2.05 |
| Silver | $0.00175 | $1.75 |
| Gold | $0.00136 | $1.36 |

### Integrations and scheduling

Run it on a schedule, for example every morning for yesterday's finals and today's lines, then send the rows to Google Sheets, Slack, email, Make, Zapier or n8n with the Apify integrations. Use a webhook to start your own pipeline when a run finishes, or call the Actor through the REST API.

### Use with the API, n8n, Make, Zapier or AI agents

**API** (one call, returns the rows as JSON):

```bash
curl -X POST "https://api.apify.com/v2/acts/transparent_meteorite~espn-sports-data-api/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" -H "Content-Type: application/json" -d '{"mode":"scores","leagues":["nba","nhl"],"daysBack":3}'
```

**Python**

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("transparent_meteorite/espn-sports-data-api").call(run_input={"mode": "schedule", "leagues": ["nfl"], "daysAhead": 7})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row["name"], row["spread"], row["overUnder"])
```

- **n8n, Make, Zapier:** use the Apify app's "Run Actor" step with actor `transparent_meteorite/espn-sports-data-api`, paste the input JSON, then map the dataset items to your sheet or database.
- **AI agents (MCP):** connect the Apify MCP server at `https://mcp.apify.com?tools=transparent_meteorite/espn-sports-data-api` to Claude, Cursor or any MCP client, and your agent can run this Actor as a tool.

### Limits

- The Actor reads public ESPN feeds. It does not read paywalled ESPN+ content, play-by-play, or full box scores. `boxscoreUrl` and `eventUrl` point at the ESPN pages for those.
- Odds are whatever ESPN shows for a game. Not every game has a line, and lines are usually removed after a game ends.
- Injury feeds exist for the NFL, NBA, MLB, NHL and some college leagues. Soccer leagues have no injury feed on ESPN, and the run reports that in `OUTPUT` instead of failing.
- Dates are grouped by US Eastern calendar day, the way ESPN groups them. A late West Coast game belongs to the day it started in the Eastern time zone.
- Rosters in the off-season show the current offseason roster. Injury lists are as fresh as ESPN's own.
- If a run reaches its time limit it stops cleanly and lists unread leagues in `notChecked`.

### Fair use and legal

The Actor reads only information that ESPN already shows publicly on the web. It does not log in or bypass any access control. Respect ESPN's terms and any rights on logos, photographs and written articles; headlines and links are returned so you can send readers back to the source. This is an independent tool, not affiliated with ESPN or any league.

### FAQ

**Do I need an ESPN account or API key?** No.

**Can I get live scores?** Yes. Games in progress have `status` set to `in`, with `period` and `clock`. Run the Actor on a short schedule for a near-live feed.

**How do I get one team's games?** Put the team name or abbreviation in **Only these teams**, set a date window, and run `scores` or `schedule`.

**Why are `spread` and `overUnder` empty?** Final games have no line. Use `schedule` mode for upcoming games.

**Can I mix sports in one run?** Yes. Use `all` or list several leagues. The column set is the same, and `league` and `sport` tell the rows apart.

**Why did I get fewer rows than my limit?** The window had fewer games, or your filters narrowed it. Widen the dates or remove the team filter.

**How far back can scores go?** As far as ESPN keeps scoreboards, which is many seasons. Each run covers up to 120 days, so split long histories into several runs.

### Support

Found a league or field that reads badly? Open an issue on the Issues tab with the run URL and the league code.

### Related actors

### Related actors

More tools from the same publisher that fit this workflow:

- [Company News Monitor](https://apify.com/transparent_meteorite/company-news-monitor): brand and keyword news alerts for teams, leagues and sponsors.
- [Google Trends Scraper](https://apify.com/transparent_meteorite/google-trends-scraper): search interest by city, to see where a team or event is trending.
- [YouTube Channel Scraper](https://apify.com/transparent_meteorite/youtube-channel-scraper): subscribers and videos for team and league channels.

Use from AI agents: every actor here is callable through the Apify MCP server (mcp.apify.com).

### Changelog

- **0.1**: First private build. Scores, schedule with odds, standings, teams, rosters, injuries and news for 23 leagues.

# Actor input Schema

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

One row per game, team, player, injury or article.

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

League codes, one per line: nfl, nba, wnba, mlb, nhl, ncaaf, ncaam, ncaaw, mls, nwsl, epl, championship, laliga, bundesliga, seriea, ligue1, eredivisie, ligamx, ucl, uel, cfl, ncaabaseball, ncaahockey. Write all for every league.

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

Scores and schedule: first day, for example 2026-11-09. Leave empty to use Days back / Days ahead.

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

Last day, for example 2026-11-15. Ranges up to 120 days per run.

## `daysBack` (type: `integer`):

When no dates are set, scores cover this many days up to today. If there were no games, the search widens on its own.

## `daysAhead` (type: `integer`):

When no dates are set, the schedule covers today plus this many days.

## `gameStatus` (type: `string`):

Keep only games in this state.

## `teams` (type: `array`):

Team names or abbreviations, for example Lions, DET, Manchester City. Works for games, standings, teams, rosters and injuries. Leave empty for all teams.

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

Standings for a past season, for example 2025. Empty means the current season.

## `newsPerLeague` (type: `integer`):

Headlines per league in news mode.

## `includeOdds` (type: `boolean`):

Spread, over/under and moneylines when a sportsbook has posted them (upcoming games).

## `includeLeaders` (type: `boolean`):

Top passer, scorer and similar leaders per game.

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

Stops after this many rows in total. Each row is one billed result.

## Actor input object example

```json
{
  "mode": "scores",
  "leagues": [
    "nfl",
    "nba",
    "nhl"
  ],
  "daysBack": 7,
  "daysAhead": 7,
  "gameStatus": "all",
  "newsPerLeague": 25,
  "includeOdds": true,
  "includeLeaders": true,
  "maxItems": 25
}
```

# Actor output Schema

## `rows` (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 = {
    "mode": "scores",
    "leagues": [
        "nfl",
        "nba",
        "nhl"
    ],
    "maxItems": 25
};

// Run the Actor and wait for it to finish
const run = await client.actor("transparent_meteorite/espn-sports-data-api").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": "scores",
    "leagues": [
        "nfl",
        "nba",
        "nhl",
    ],
    "maxItems": 25,
}

# Run the Actor and wait for it to finish
run = client.actor("transparent_meteorite/espn-sports-data-api").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": "scores",
  "leagues": [
    "nfl",
    "nba",
    "nhl"
  ],
  "maxItems": 25
}' |
apify call transparent_meteorite/espn-sports-data-api --silent --output-dataset

```

## MCP server setup

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

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/eFjJBiX1XbQHZvJzN/builds/qhLvMJItHIzkgHOt4/openapi.json
