# Football Live Scores API - Fixtures, Standings, Odds, Stats (`nabeelbaghoor/football-livescores-fixtures-standings-api`) Actor

Football livescores, fixtures and results, league standings, topscorers, teams, players, squads, transfers, pre-match odds and predictions from the Sportmonks Football API 3.0 for 2,200+ leagues. Filter by date, league, team or state. Bring your own key.

- **URL**: https://apify.com/nabeelbaghoor/football-livescores-fixtures-standings-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (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

from $6.00 / 1,000 match returneds

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

## Football Live Scores API - Fixtures, Standings, Odds, Stats

Get football livescores, fixtures and results, league standings, topscorers, teams, players, squads, transfers, pre-match odds and prediction probabilities from the Sportmonks Football API 3.0 with your own API token, as one clean dataset row per record.

Sportmonks covers 2,200+ football leagues, from the Premier League, LaLiga, Serie A, Bundesliga and Champions League to lower divisions worldwide. This actor wraps the read only endpoints of the Football API on api.sportmonks.com: give a date, a date range, a league, two teams or a name, and get deduplicated rows with team names, scores and match state already joined in, which you can download as JSON, CSV or Excel, schedule, or feed into betting models, fantasy football tools, sports apps, newsletters, Google Sheets and AI agents. Bring your own key.

BYOK, not live-tested: every path, parameter and filter comes from the Sportmonks documentation at docs.sportmonks.com/v3, and every route was confirmed to exist (an invalid token gets 401 on each real route and 404 on an invented one), but the actor has not been run against a live Sportmonks token.

### What it does

- **Livescores**: every match in play right now, or the whole livescores window from 15 minutes before kick off to 15 minutes after full time, with teams, current score and state.
- **Fixtures and results**: matches by date, by date range (up to 100 days, optionally per team), by fixture ID (50 per request), head to head between two teams, or by name. Filter by league and by match state (not started, in play, finished, postponed), newest or oldest first, in your timezone.
- **Leagues and seasons**: all leagues on your plan, by name or by country, with the current season ID; seasons by name, such as 2025/2026, for the IDs the table modes take.
- **Standings and live standings**: league tables per season with position, points and team name, and live tables per league while matches are played.
- **Topscorers**: goal and other scorer charts per season with player, team, position and total.
- **Teams, players and squads**: team profiles (country, venue, founded, short code), player profiles (date of birth, nationality, position, height, weight) by name or ID, and extended squads per team.
- **Transfers**: the latest transfers, transfers in a date range, or a team's transfers, with player, from team, to team, date, amount and type.
- **Pre-match odds and predictions**: odds per fixture by market and bookmaker in decimal, fractional and American formats, and Sportmonks prediction probabilities per fixture (both are Sportmonks add-ons).
- **Your own includes**: replace the default includes with any documented Sportmonks include, such as events, statistics, lineups or periods, and get them under record.
- **Pay only for results**: refused and empty lookups are recorded as a free row that says why, never charged.

Nothing is written to your Sportmonks account: only GET endpoints are called.

### How to get an API key

Create an account at my.sportmonks.com, open API, Tokens, give the token a name and click Create. Sportmonks has a free plan (Danish Superliga and Scottish Premiership) and a 14 day trial of the paid plans. Paste the token into the API key field. It is sent only to api.sportmonks.com in the Authorization header and never logged.

### Input

| Field | Used by | Example |
|---|---|---|
| What to get | all | Fixtures by date |
| Match dates | Fixtures by date | 2026-10-25 |
| Start date, End date | Fixtures by date range, Transfers | 2026-08-01 to 2026-10-31 |
| Livescores scope | Livescores | Matches in play now |
| Search names | Fixture, league, season, team and player search | Celtic, Premier League, 2025/2026 |
| League IDs | Fixture modes, livescores, season search, live standings | 501 |
| Season IDs | Standings, topscorers, teams by season | 23690 |
| Team IDs | Head to head, date range per team, teams, squads, transfers | 53, 62 |
| Player IDs | Players by ID | 758 |
| Fixture IDs | Fixtures by ID, pre-match odds, predictions | 19146700 |
| Country IDs | Leagues, team search, teams by season | 462 |
| Match state | Fixture modes, livescores | Finished |
| Order | Fixtures by date, date range, search | Latest kick off first |
| Odds market IDs, Bookmaker IDs | Pre-match odds | 1, 2 |
| Transfer type IDs | Transfers | 219 |
| Timezone | all | Europe/London |
| Includes, Plain records | all | participants;scores;events |
| Max results | all | 100 |
| API key | all | your Sportmonks token |

Example input for finished Scottish Premiership matches over two months:

```json
{
    "mode": "fixturesBetween",
    "startDate": "2026-08-01",
    "endDate": "2026-09-30",
    "leagueIds": ["501"],
    "fixtureState": "finished",
    "order": "desc",
    "maxResults": 200,
    "apiKey": "YOUR_SPORTMONKS_TOKEN"
}
```

### Example output

An illustrative fixture row; the fixture fields follow the example answer in the Sportmonks documentation.

```json
{
    "mode": "fixturesByDate",
    "modeLabel": "Fixtures by date",
    "recordType": "fixture",
    "query": "date 2024-08-04",
    "id": 19146701,
    "name": "Celtic vs Kilmarnock",
    "leagueId": 501,
    "leagueName": "Premiership",
    "seasonId": 23690,
    "teamId": null,
    "teamName": null,
    "playerId": null,
    "playerName": null,
    "stageId": 77471570,
    "roundId": 340573,
    "venueId": 8909,
    "startingAt": "2024-08-04 15:30:00",
    "startingAtTimestamp": 1722785400,
    "stateId": 5,
    "state": "FT",
    "stateName": "Full Time",
    "homeTeamId": 53,
    "homeTeam": "Celtic",
    "awayTeamId": 85,
    "awayTeam": "Kilmarnock",
    "homeScore": 4,
    "awayScore": 0,
    "winner": "Celtic",
    "resultInfo": "Celtic won after full-time.",
    "leg": "1/1",
    "hasOdds": true,
    "found": true,
    "retrievedAt": "2026-10-21T09:00:00.000Z",
    "note": null,
    "record": { "id": 19146701, "participants": ["..."], "scores": ["..."], "state": {"...": "..."}, "league": {"...": "..."} }
}
```

Standings rows carry teamId, teamName, position and points; topscorer rows playerName, teamName, position and total; transfer rows date, playerName, fromTeam, toTeam and amount; odds rows marketName, bookmakerName, label, oddsDecimal, oddsFractional, oddsAmerican and probability.

### FAQ

#### What is the Sportmonks Football API?

Sportmonks is a Dutch sports data provider, founded in 2016 in Deventer, whose Football API 3.0 serves livescores, fixtures, results, standings, statistics, players, transfers, odds and predictions for 2,200+ leagues to more than 30,000 registered customers. It is a REST API with JSON answers, includes for related data, filters and cursor pagination.

#### Do I need my own Sportmonks API token?

Yes. This actor is bring your own key: it calls Sportmonks with your token and your plan decides which leagues and add-ons you can read. Create a token in MySportmonks under API, Tokens. A run without a token ends cleanly with a message saying what to add.

#### How do I get today's football results?

Choose Fixtures by date, enter today's date, set Match state to Finished and, optionally, League IDs to keep only the competitions you follow. Each row has the home and away team, current score, state and winner.

#### How do I get live scores for matches in play?

Choose Livescores with the scope Matches in play now. Schedule the actor every minute or two for a live feed, or add League IDs to follow only some competitions.

#### How do I find league, season and team IDs?

Run Leagues with a name such as Premier League to get the league ID and current season ID, Season search with 2025/2026 for past seasons, and Team search with a club name for team IDs. Those IDs feed standings, topscorers, squads, head to head and transfers.

#### Can I get league tables and topscorers?

Yes. Standings by season returns one row per team with position and points; Live standings by league updates during matches; Topscorers by season returns the scorer chart with player and team names.

#### Does it return betting odds and predictions?

Pre-match odds by fixture returns every market and bookmaker on your plan, filterable by market and bookmaker ID, in decimal, fractional and American formats. Prediction probabilities returns Sportmonks model probabilities per fixture. Both are Sportmonks add-ons; without them the run ends cleanly with a not on your plan message.

#### How many API requests does a run use?

One per page of up to 50 rows, plus one per ID or date looked up. Sportmonks counts calls per entity (fixtures, teams, players and so on) per hour: 2,000 on Starter up to 5,000 on Enterprise. When an entity's hourly allowance is used up the run ends cleanly and tells you when it resets.

#### What do I pay?

Pay per result: you pay this actor only for rows that carry Sportmonks data, plus your own Sportmonks plan. Empty searches and refused lookups are free rows.

### Pricing

| Event | Price |
|---|---|
| Match returned (fixture or livescore) | 0.006 USD |
| Table, stat or reference record (standing, topscorer, squad member, transfer, odd, prediction, league, season) | 0.005 USD |
| Team or player profile | 0.008 USD |

Platform usage is included. Your Sportmonks plan is billed separately by Sportmonks.

### Keyword map

Football API, soccer API, football livescores API, live scores API, football fixtures API, football results API, league standings API, league table API, topscorers API, football player data, football team data, squad data, transfer data API, football odds API, pre-match odds, football predictions API, Sportmonks API, Sportmonks Football API 3.0, Premier League API, Champions League data, fantasy football data, betting data feed, sports data API.

### Terms and data use

The Sportmonks Terms of Service allow storing and distributing the data their services provide and building apps, websites and games on it, but say that reselling Sportmonks data without approval is not allowed, that an account is personal and may not be shared, that data licences are tied to individual domains, and that logos and player images belong to their owners. They set no cache or retention time limit. Run this actor with your own token, use the results for the uses your Sportmonks plan allows, and do not resell the data without Sportmonks' approval. This actor is not affiliated with or endorsed by Sportmonks.

# Actor input Schema

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

Livescores reads matches in play now (or the whole livescores window). Fixtures by date, date range, ID, head to head and name return matches with teams, scores, state and league. Leagues, season search, team search and player search give the IDs other modes take. Standings, live standings and topscorers read league tables and goal charts. Teams, players and squads read profiles. Transfers reads the latest, a date range or one team. Pre-match odds and prediction probabilities read per fixture and are Sportmonks add-ons. Leagues and feeds depend on your Sportmonks plan.

## `dates` (type: `array`):

Fixtures by date only. Calendar dates as YYYY-MM-DD, up to 31 per run. With a timezone set, Sportmonks reads each date in that timezone.

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

Fixtures by date range and Transfers. YYYY-MM-DD. A fixtures range is 100 days at most.

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

Fixtures by date range and Transfers. YYYY-MM-DD, on or after the start date.

## `liveScope` (type: `string`):

Livescores only.

## `searchQueries` (type: `array`):

Fixture, league, season, team and player search. One name per line, such as Celtic, Premier League, 2025/2026 or Tavernier.

## `leagueIds` (type: `array`):

Fixture modes and livescores (keeps only these leagues), season search (seasons of these leagues) and live standings (one table per league). Numeric Sportmonks league IDs from the Leagues mode, such as 501 for the Scottish Premiership.

## `seasonIds` (type: `array`):

Standings, topscorers and teams by season. Numeric season IDs from Season search or the currentSeason column of Leagues.

## `teamIds` (type: `array`):

Head to head (exactly two), fixtures by date range (one window per team), teams by ID, squads and transfers by team. Numeric team IDs from Team search.

## `playerIds` (type: `array`):

Players by ID only. Numeric player IDs from Player search, squads or topscorers.

## `fixtureIds` (type: `array`):

Fixtures by ID (50 per request), pre-match odds and prediction probabilities. Numeric fixture IDs from any fixture mode.

## `countryIds` (type: `array`):

Leagues (leagues of these countries) and team search and teams by season (keeps only teams from these countries). Numeric Sportmonks country IDs, such as 462 for England.

## `fixtureState` (type: `string`):

Fixture modes and livescores. Filters by the documented Sportmonks fixture state IDs.

## `order` (type: `string`):

Fixtures by date, date range and fixture search.

## `marketIds` (type: `array`):

Pre-match odds only. Keeps these markets, such as 1 for the match winner (1X2) market.

## `bookmakerIds` (type: `array`):

Pre-match odds only. Keeps these bookmakers.

## `transferTypeIds` (type: `array`):

Transfers only. Keeps these Sportmonks transfer type IDs, such as 219 and 220.

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

Optional IANA timezone for kick off times, such as Europe/London or America/New_York. Defaults to UTC.

## `includes` (type: `string`):

Optional. Sportmonks includes separated by semicolons, replacing the defaults, such as participants;scores;events;statistics for fixtures. Each mode adds team, league, player or market names by default. Some includes are plan add-ons.

## `plainRecords` (type: `boolean`):

Sends no includes, so rows carry IDs but no names. Use it when your plan refuses an include.

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

Stops after this many rows. Each page of 50 rows is one Sportmonks API call.

## `requestsPerMinute` (type: `integer`):

Pacing ceiling. Sportmonks limits calls per entity per hour (2,000 to 5,000 by plan).

## `apiKey` (type: `string`):

Your own Sportmonks API token, created in MySportmonks under API, Tokens. It is sent only to api.sportmonks.com in the Authorization header and never logged.

## Actor input object example

```json
{
  "mode": "fixturesByDate",
  "dates": [
    "2026-10-25"
  ],
  "liveScope": "inplay",
  "fixtureState": "any",
  "order": "asc",
  "plainRecords": false,
  "maxResults": 100,
  "requestsPerMinute": 120
}
```

# Actor output Schema

## `records` (type: `string`):

One row per record returned for the chosen mode.

# 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 = {
    "dates": [
        "2026-10-25"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/football-livescores-fixtures-standings-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 = { "dates": ["2026-10-25"] }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/football-livescores-fixtures-standings-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 '{
  "dates": [
    "2026-10-25"
  ]
}' |
apify call nabeelbaghoor/football-livescores-fixtures-standings-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/football-livescores-fixtures-standings-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/CTYTU535zX2Tz2fBn/builds/FpjAvhg6ONxBMZjPP/openapi.json