# Live Sports Scores API (`maximedupre/sports-scores-api`) Actor

Get current, upcoming, and completed game scores across supported leagues and sports. Search competitions by date, status, or team, or request details for known event IDs. Receive normalized game data with teams, scores, live context, odds, and source links when available.

- **URL**: https://apify.com/maximedupre/sports-scores-api.md
- **Developed by:** [Maxime Dupré](https://apify.com/maximedupre) (community)
- **Categories:** Sports, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.05 / 1,000 games

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

### 🏟️ Build a live sports scores API

For sports app builders, analysts, and automation teams, Live Sports Scores API returns one normalized game row for each saved game. Search supported leagues and competitions by date, recent date window, status, and team, or request an identified game by source event ID. Read teams, scores, competition context, live context, odds, optional match details, and source links in a dataset built for programmatic access.

- Pull current, upcoming, or completed game rows with **[Live Sports API](https://apify.com/maximedupre/sports-scores-api/examples/live-sports-api)**.
- Search several competitions and save normalized game data with **[Free Sports Data API](https://apify.com/maximedupre/sports-scores-api/examples/free-sports-data-api)**.
- Request score rows from supported leagues with **[ESPN Sports API](https://apify.com/maximedupre/sports-scores-api/examples/espn-sports-api)**.
- Look up a known game through **[ESPN API Endpoints](https://apify.com/maximedupre/sports-scores-api/examples/espn-api-endpoints)**.
- Inspect a source event with **[ESPN Hidden API](https://apify.com/maximedupre/sports-scores-api/examples/espn-hidden-api)**.

#### 📦 Normalized game rows

**What you get**

Each saved row uses one normalized game shape. It can include the event ID, sport, competition and season, home and away teams, start time, status, scores, live context, venue, odds, requested match details, and source data when available. Scores are absent before play begins, and optional values are not filled with guesses.

#### ▶️ Search leagues or inspect known games

1. Set `findBy` to `competition` for a league or competition search, or to `eventId` for identified games.
2. For a competition search, enter one or more supported competition names or IDs. Add a date, status, and optional team names or IDs.
3. For an identified-game request, enter one or more source event IDs. Fields for the other choice are ignored.
4. Add a supported language code when you want localized team names and labels.
5. Leave `maxItems` empty to return all available results until the source is exhausted, or set a positive row limit.
6. Start the Actor and open the default dataset to read or export the normalized rows.

#### ⚙️ Input

**Input fields**

| Field | Type | What it does |
|---|---|---|
| `findBy` | string | Chooses `competition` for a multi-competition search or `eventId` for identified game details. |
| `competitions` | array of strings | Names or IDs of the supported leagues or competitions to search. |
| `date` | string | A calendar date or supported relative date expression for past, future, or recent games. Empty uses the current date. |
| `status` | string | Keeps `all`, `live`, `upcoming`, or `completed` games in a competition search. |
| `teams` | array of strings | Optional team names or IDs that narrow a competition search. |
| `eventIds` | array of strings | Source event IDs for identified games. |
| `language` | string | A supported code for team names and labels: `en`, `es`, `fr`, `de`, `it`, or `pt`. |
| `maxItems` | integer | Optional game-row limit. Leave it empty to return all available results until the source is exhausted. |

**Example input**

This is the public input from a successful current-beta default run.

```json
{
  "findBy": "competition",
  "competitions": [
    "nfl"
  ],
  "date": "last 7 days",
  "status": "all",
  "maxItems": 100
}
```

#### 🧾 Output

The run output provides a `dataset` URL that opens the game rows in the default dataset. The dataset uses one normalized game-row shape. Optional fields appear only when the request and source provide them.

**Game row fields**

| Field | Type | What it does |
|---|---|---|
| `eventId` | string | Source event ID for the game. |
| `sport` | string | Sport for the game. |
| `competition` | object | League or competition context. |
| `competition.name` | string | Name of the league or competition. |
| `competition.id` | string | Source ID for the competition, when available. |
| `competition.code` | string | Source code for the competition, when available. |
| `competition.season` | string | Season containing the game, when available. |
| `competition.round` | string | Round or stage of the competition, when available. |
| `teams` | object | Home and away team data. |
| `teams.home` | object | Home team and its available context. |
| `teams.home.name` | string | Home team name. |
| `teams.home.id` | string | Source ID for the home team, when available. |
| `teams.home.code` | string | Short source code for the home team, when available. |
| `teams.home.ranking` | integer | Home team ranking, when the source provides it. |
| `teams.home.recentForm` | array of strings | Recent home-team result labels in source order, when available. |
| `teams.away` | object | Away team and its available context. |
| `teams.away.name` | string | Away team name. |
| `teams.away.id` | string | Source ID for the away team, when available. |
| `teams.away.code` | string | Short source code for the away team, when available. |
| `teams.away.ranking` | integer | Away team ranking, when the source provides it. |
| `teams.away.recentForm` | array of strings | Recent away-team result labels in source order, when available. |
| `startTime` | string | Scheduled game start in ISO 8601 format. |
| `venue` | object | Game venue, when the source provides it. |
| `venue.name` | string | Venue name. |
| `venue.id` | string | Source ID for the venue, when available. |
| `venue.city` | string | Venue city, when available. |
| `venue.country` | string | Venue country, when available. |
| `status` | string | Normalized game status, such as `scheduled`, `live`, or `completed`. |
| `scores` | object | Home and away scores after play begins, when available. |
| `scores.home` | integer | Current or final home score. |
| `scores.away` | integer | Current or final away score. |
| `liveContext` | object | Sport-specific live information, when available. |
| `liveContext.period` | string | Current period, inning, quarter, set, or similar stage. |
| `liveContext.clock` | string | Game clock or another live time display. |
| `liveContext.progress` | string | Source progress label, such as a set count or scheduled time. |
| `liveContext.phase` | string | Current game phase, such as halftime or overtime. |
| `odds` | array of objects | Available match-outcome odds. |
| `odds[].market` | string | Market for the odds. |
| `odds[].bookmaker` | string | Bookmaker that supplied the odds, when available. |
| `odds[].format` | string | Odds format: `decimal`, `fractional`, or `american`. |
| `odds[].home` | number or string | Odds for the home outcome. |
| `odds[].draw` | number or string | Odds for a draw, when that outcome exists. |
| `odds[].away` | number or string | Odds for the away outcome. |
| `details` | object | Events, lineups, and match statistics when requested and available. |
| `details.events` | array of objects | Recorded events from the game. |
| `details.events[].type` | string | Type of game event. |
| `details.events[].team` | string | Team linked to the event, when available. |
| `details.events[].player` | string | Player linked to the event, when available. |
| `details.events[].minute` | number | Game minute for the event, when available. |
| `details.events[].description` | string | Source description of the event, when available. |
| `details.lineups` | array of objects | Players listed in the game lineups. |
| `details.lineups[].team` | string | Team for the lineup entry. |
| `details.lineups[].playerId` | string | Source ID for the player, when available. |
| `details.lineups[].playerName` | string | Player name. |
| `details.lineups[].position` | string | Player position, when available. |
| `details.lineups[].starter` | boolean | Whether the player started the game, when available. |
| `details.statistics` | array of objects | Named statistics for the home and away teams. |
| `details.statistics[].name` | string | Name of the statistic. |
| `details.statistics[].home` | number or string | Home value for the statistic. |
| `details.statistics[].away` | number or string | Away value for the statistic. |
| `dataSource` | object | Source that provided the game, when the source name is available. |
| `dataSource.name` | string | Name of the data source. |
| `dataSource.url` | string URL | Source page for the game, when available. |

**Genuine completed row**

This complete row came from a successful current-beta competition run.

```json
{
  "eventId": "401872948",
  "sport": "football",
  "competition": {
    "name": "National Football League",
    "id": "28",
    "code": "NFL",
    "season": "2026",
    "round": "3"
  },
  "teams": {
    "home": {
      "name": "Green Bay Packers",
      "id": "9",
      "code": "GB"
    },
    "away": {
      "name": "Atlanta Falcons",
      "id": "1",
      "code": "ATL"
    }
  },
  "startTime": "2026-09-25T00:15:00.000Z",
  "status": "completed",
  "scores": {
    "home": 14,
    "away": 35
  },
  "venue": {
    "name": "Lambeau Field",
    "id": "3798",
    "city": "Green Bay",
    "country": "USA"
  },
  "liveContext": {
    "period": "4",
    "clock": "0:00"
  },
  "dataSource": {
    "name": "ESPN",
    "url": "https://www.espn.com/nfl/game/_/gameId/401872948/falcons-packers"
  }
}
```

**Genuine scheduled detail row**

This complete row came from a successful current-beta identified-event run. It shows that scores may be absent before play and that optional statistics and odds can appear.

```json
{
  "eventId": "401879268",
  "sport": "soccer",
  "competition": {
    "name": "English Premier League",
    "id": "700",
    "code": "Premier League",
    "season": "2026"
  },
  "teams": {
    "home": {
      "name": "Arsenal",
      "id": "359",
      "code": "ARS",
      "recentForm": [
        "L",
        "W",
        "W",
        "W",
        "W"
      ]
    },
    "away": {
      "name": "Leeds United",
      "id": "357",
      "code": "LEE",
      "recentForm": [
        "D",
        "W",
        "L",
        "D",
        "D"
      ]
    }
  },
  "startTime": "2026-10-10T11:30:00.000Z",
  "status": "scheduled",
  "liveContext": {
    "progress": "10/10 - 7:30 AM EDT"
  },
  "dataSource": {
    "name": "ESPN",
    "url": "https://www.espn.com/soccer/match/_/gameId/401879268/leeds-united-arsenal"
  },
  "details": {
    "statistics": [
      {
        "name": "goalDifference",
        "home": "4",
        "away": "4"
      },
      {
        "name": "totalGoals",
        "home": "8",
        "away": "7"
      },
      {
        "name": "goalAssists",
        "home": "6",
        "away": "4"
      },
      {
        "name": "goalsConceded",
        "home": "4",
        "away": "3"
      }
    ]
  },
  "odds": [
    {
      "market": "Moneyline",
      "bookmaker": "DraftKings",
      "format": "american",
      "home": -270,
      "draw": 380,
      "away": 650
    }
  ]
}
```

#### 💳 Pricing

**Charged event**

One saved normalized game is one charged event. The buyer-facing event is `Game`; check the Pricing tab for the current rate.

#### 🔌 Integrations

Use the Apify API or the default dataset URL to read rows from code and pass them to a sports app, report, or data pipeline. Source links stay with the row when they are available.

Watch the Apify workflow video:

https://www.youtube.com/watch?v=bNACk1\_S\_6w\&list=PLObrtcm1Kw6MUrlLNDbK9QRg8VDJg0gOW\&index=4

#### ❓ FAQ

##### Can I search more than one league or competition?

Yes. Set `findBy` to `competition` and enter one or more supported names or IDs. The Actor returns normalized rows for that set in one coherent request.

##### Can I request a known game?

Yes. Set `findBy` to `eventId` and enter one or more source event IDs. The row can include events, lineups, and match statistics when the source provides them.

##### What happens when a game has not started?

The `scores` field is absent before play begins. The row can still include the scheduled status, start time, teams, venue, and other available context.

##### Are odds and match details always present?

No. `odds` and `details` are optional. They appear when the request and source provide them, and some nested values may still be unavailable.

##### Can I use a past date or a recent date window?

Yes. Enter a calendar date for past or future games, or use a supported relative date expression such as `last 7 days`. Leave the field empty for the current date.

##### Does the language setting translate every field?

No. It applies to team names and labels. Other source fields follow the data that the source provides.

##### Does `maxItems` have a fixed upper limit?

No schema-defined upper limit is set. Leave it empty to return all available results until the source is exhausted.

##### What happens when no game matches my filters?

The request may return no game rows when a competition has no game for the date, status, or team you chose. Try a different date or filter when you need another set of games.

### 📝 Changelog

**v0.0** (30-09-2026)

- Initial release.

### 🆘 Support

For issues, questions, or feature requests, [file a ticket](https://console.apify.com/actors/maximedupre~sports-scores-api/issues) and I'll fix or implement it in less than 24h 🫡

### 🔗 Related Actors

- [Sofascore Live Events Scraper](https://apify.com/maximedupre/sofascore-live-events-scraper): Use it for multi-sport live fixtures, teams, and public event pages from Sofascore.
- [ESPN MCP Server](https://apify.com/maximedupre/espn-mcp-server): Use it for broader ESPN research such as standings, news, teams, and AI tool access.
- [Live Sports Scores & Fixtures API (ESPN)](https://apify.com/ichigowa/live-sports-scores): Use it when you want an ESPN scoreboard feed focused on fixtures, scores, and final results.
- [Live Scores API - Sports Scores NBA, NFL, MLB, NHL, NCAAF, EPL](https://apify.com/neverempty/sports-scores-api): Use it for a fixed set of major leagues in one score feed.
- [Bet365 Live Scores API | Real-Time Sports Data, 13 Sports](https://apify.com/zen-studio/bet365-live-scores): Use it when you need broader live sports coverage with match events and lineups.

**Made with ❤️ by Maxime Dupré**

# Actor input Schema

## `findBy` (type: `string`):

Choose a competition search, or look up identified games by their source event IDs.

## `competitions` (type: `array`):

Enter one or more supported league or competition names or IDs. This search can cover multiple sports in one run.

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

Enter a calendar date for past or future games, or a supported relative date expression for a recent date window. Leave it empty to use the current date.

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

For a league or competition search, choose live, upcoming, completed, or all games.

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

Optionally enter one or more team names or IDs to narrow a league or competition search.

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

Enter one or more source event IDs for identified games. The result can include events, lineups, and match statistics when the source provides them.

## `language` (type: `string`):

Choose a supported language code for team names and labels. It applies to either search choice.

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

Optionally stop after this many game rows. Leave it empty to return all available results until the source is exhausted.

## Actor input object example

```json
{
  "findBy": "competition",
  "competitions": [
    "nfl"
  ],
  "date": "last 7 days",
  "status": "all",
  "maxItems": 100
}
```

# Actor output Schema

## `dataset` (type: `string`):

Open the game result rows from 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 = {
    "findBy": "competition",
    "competitions": [
        "nfl"
    ],
    "date": "last 7 days",
    "maxItems": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("maximedupre/sports-scores-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 = {
    "findBy": "competition",
    "competitions": ["nfl"],
    "date": "last 7 days",
    "maxItems": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("maximedupre/sports-scores-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 '{
  "findBy": "competition",
  "competitions": [
    "nfl"
  ],
  "date": "last 7 days",
  "maxItems": 100
}' |
apify call maximedupre/sports-scores-api --silent --output-dataset

```

## MCP server setup

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