# Sports Scores Scraper — Football, NBA, NFL, Standings (`chorelet/sports-scores-scraper`) Actor

Live scores, fixtures, results, standings and teams for football leagues worldwide and the major US leagues — NBA, NFL, MLB, NHL, F1, tennis — in one schema. Any date or date range, no API key.

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

## Pricing

from $0.70 / 1,000 matches

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

## Sports Scores Scraper — Football, NBA, NFL, Standings

Live scores, fixtures, results, league tables and team lists for **football leagues worldwide and every major US league** — in one schema, from one Actor. Premier League, LaLiga, Bundesliga, Serie A, Ligue 1, Champions League, MLS, NBA, NFL, MLB, NHL, college football and basketball, F1, tennis, UFC. No API key, no account, no scraping of HTML.

Ask for a league by the name you actually use — `Premier League`, `NBA`, `NFL`, `Champions League` — or by code (`eng.1`, `esp.1`), or paste the ESPN URL. Leave the date empty and you get the matchday that is running right now: live scores with the clock, today's finished games, or the next round if nothing is on.

### Why this Actor

- **Every sport in one schema.** A Premier League match and an NBA game come back with the same column names, so one spreadsheet covers a whole portfolio of leagues instead of one per sport.
- **Live, with the clock.** Runs during a game return state `in`, the score as it stands, the period and the display clock — not a stale final score from yesterday.
- **Standings that survive the sport change.** Football tables have points and a rank; American leagues have a playoff seed and a win percentage. Both are mapped onto the same columns, and games played is added up when ESPN omits it.
- **Reference rows cost half.** Standings and team lists are charged at half the price of a match row, so building a lookup table is cheap and only the live data carries the full price.

### Sample output

One item of the dataset (long values shortened):

```json
{
  "leagueName": "English Premier League",
  "startsAt": "2026-09-20T13:00Z",
  "state": "post",
  "statusDetail": "FT",
  "homeTeam": "AFC Bournemouth",
  "homeScore": 0,
  "awayScore": 1,
  "awayTeam": "Liverpool",
  "venue": "Vitality Stadium",
  "url": "https://www.espn.com/soccer/match/_/gameId/401879276/liverpool-afc-bournemouth"
}
```

### What you get

- **One row per match**, identical for a football match and an NBA game: kick-off in UTC, state (`pre`/`in`/`post`), the status as ESPN words it ("FT", "7:35 - 4th Quarter"), period and clock, both sides with score, abbreviation, badge and season record, the winner, venue, city, attendance, broadcaster and the ESPN match page
- **Live scores that are actually live** — a run during an NFL Sunday returns `in` rows with the score and the game clock as it stands
- **Standings** for any league that publishes them, with conferences and groups kept as a column: position, played, wins, draws, losses, points, goals or points for and against, difference, streak, games behind, and the qualification note ("UEFA Champions League") where there is one. Football tables and US standings land in the same columns — win percentage fills in where a league has no table points
- **Team lists** with id, abbreviation, location, nickname, primary colour, logo and clubhouse link — the lookup table you need to join scores to anything else
- **Any date you want**: today, yesterday, a window like `last 7 days`, a single date, or a range up to 60 days
- Filter to `pre`, `in` or `post`, and to the teams you follow
- JSON, CSV, Excel or the API, and an MCP server so an agent can ask for scores directly

### Input example

```json
{
  "leagues": [
    "Premier League",
    "NBA",
    "NFL"
  ],
  "mode": "scoreboard",
  "maxResults": 200
}
```

### How much does it cost?

Pay per match — no subscription, no minimum, no charge for platform usage.

| Volume | Price |
|---|---|
| 1,000 matches | $1.00 (+ $0.50 with `record`) |
| 10,000 matches | $10.00 (+ $5.00 with `record`) |
| 100,000 matches | $100.00 (+ $50.00 with `record`) |

The Apify **free plan includes $5 of usage every month** — about 5,000 matches with this Actor, no card needed. Nothing else is charged: platform usage is included in the price, and Apify Bronze, Silver and Gold subscribers get 10%, 20% and 30% off these prices.

### Use it from code, n8n, Make, Zapier or an AI agent

Run the Actor and download the dataset in one call (JSON by default; add `&format=csv` or `xlsx`):

```bash
curl -X POST "https://api.apify.com/v2/acts/chorelet~sports-scores-scraper/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"leagues": ["Premier League", "NBA", "NFL"], "mode": "scoreboard", "maxResults": 200}'
```

Python:

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("chorelet/sports-scores-scraper").call(run_input={"leagues": ["Premier League", "NBA", "NFL"], "mode": "scoreboard", "maxResults": 200})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

- **n8n, Make, Zapier** — use the Apify node/module: run the Actor, then "get dataset items".
- **Google Sheets, Slack, webhooks** — add an integration on the run's *Integrations* tab.
- **AI agents** — the Actor is available as a tool through the Apify MCP server; the dataset schema describes every field for the model.
- **Schedules** — run it hourly, daily or weekly from the *Schedules* tab.

### FAQ

**Which leagues are covered?**

Anything ESPN publishes: the top divisions of England, Spain, Germany, Italy and France plus dozens of smaller ones, UEFA Champions and Europa League, the World Cup, MLS, NBA, WNBA, NFL, MLB, NHL, college football and basketball, F1, ATP and WTA tennis and UFC. Give a name, a code such as `eng.1`, a path such as `basketball/nba`, or the ESPN league URL.

**What does an empty date give me?**

The matchday ESPN itself is showing: live games with the clock while they are on, the finished games of the day afterwards, and the next round when nothing is running. That is the right answer for a dashboard that refreshes on a schedule.

**Why did a date return no matches?**

There were no fixtures that day — an international break, a bye week or the off-season. The run says so in the log and charges nothing for the empty league.

**How often can I refresh live scores?**

As often as you like; a scoreboard request is one API call per league per day requested and takes under a second. A schedule every minute during a match is perfectly normal usage.

**Does it need an ESPN account or key?**

No. It reads ESPN's own public JSON endpoints — the ones their website calls — with no login, no key and no proxy.

**Can an AI agent call it?**

Yes. Every Apify Actor is exposed as an MCP server and a REST endpoint, so an agent can ask for today's scores or a league table and get JSON back.

### Support

Questions, missing fields or a source that changed? Open an issue on the *Issues* tab or write to support@chorelet.app — problems are usually fixed within a day, and the Actor is checked every morning by an automated test run. If the Actor saved you time, a short review on its Store page helps other people find it.

# Actor input Schema

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

Names (`Premier League`, `NBA`, `NFL`, `Champions League`), bare football codes (`eng.1`, `esp.1`, `ger.1`) or full paths (`basketball/nba`, `soccer/ita.1`, `hockey/nhl`, `racing/f1`, `tennis/atp`).

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

Matches with scores, the league table, or the list of teams.

## `dates` (type: `string`):

Leave empty for the matchday ESPN is showing right now — live games, today's results or the next round. Otherwise `today`, `yesterday`, `tomorrow`, a window like `7 days` or `last 3 days`, a date `2026-09-27`, or a range `2026-09-01..2026-09-07`. Each day is one request; a range is capped at 60 days.

## `states` (type: `array`):

Keep only `pre` (not started), `in` (live) or `post` (finished). Empty = all three.

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

Keep only matches involving these teams, by full or short name, e.g. `Arsenal`, `LAL`.

## `maxResults` (type: `integer`):

Across all requested days.

## Actor input object example

```json
{
  "leagues": [
    "Premier League",
    "NBA",
    "NFL"
  ],
  "mode": "scoreboard",
  "dates": "",
  "states": [],
  "teams": [],
  "maxResults": 200
}
```

# Actor output Schema

## `rows` (type: `string`):

Everything scraped — items of the default dataset. Use ?format=csv or xlsx on this URL for spreadsheets.

## `summary` (type: `string`):

Rows per league, days requested, API calls and errors.

# 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": [
        "Premier League",
        "NBA",
        "NFL"
    ],
    "mode": "scoreboard",
    "dates": "",
    "states": [],
    "teams": [],
    "maxResults": 200
};

// Run the Actor and wait for it to finish
const run = await client.actor("chorelet/sports-scores-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": [
        "Premier League",
        "NBA",
        "NFL",
    ],
    "mode": "scoreboard",
    "dates": "",
    "states": [],
    "teams": [],
    "maxResults": 200,
}

# Run the Actor and wait for it to finish
run = client.actor("chorelet/sports-scores-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": [
    "Premier League",
    "NBA",
    "NFL"
  ],
  "mode": "scoreboard",
  "dates": "",
  "states": [],
  "teams": [],
  "maxResults": 200
}' |
apify call chorelet/sports-scores-scraper --silent --output-dataset

```

## MCP server setup

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