# SofaScore Scraper - Live Scores, Fixtures, Stats & Odds (`axlymxp/sofascore-scraper`) Actor

Sofascore data for football and 24 more sports: matches by day, live, league, team or URL with scores, plus optional stats (xG, possession, shots), lineups with ratings, goals and cards, odds and shotmaps. League tables and squads too.

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

## Pricing

from $1.50 / 1,000 dataset items

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

## SofaScore Scraper — Live Scores, Fixtures, Match Stats, Lineups & Odds

Get structured sports data from Sofascore for football and 24 other sports. Collect every match of a day, live
scores, a league's fixtures and results, or a team's recent and upcoming games. Each match comes with teams, scores
by period, round and status. Add match statistics (xG, possession, shots…), lineups with player ratings, goals and
cards, bookmaker odds and shotmaps when you need them. League tables and team squads (market value, contract,
position) are separate modes.

Built for football analysts and scouts, betting models, fantasy and dashboard apps, and journalists who need clean,
schedulable sports data without running their own scraper.

### What you get

| Field | Description |
| --- | --- |
| `matchId`, `url` | Sofascore match id and link |
| `sport`, `status`, `statusDescription`, `startTime` | e.g. `football`, `finished` / `inprogress` / `notstarted`, "2nd half", UTC ISO-8601 |
| `country`, `countryCode`, `tournament`, `tournamentId`, `season`, `seasonId`, `round` | Competition context ("England", "Premier League", "Premier League 26/27", "Round 7") |
| `homeTeam`, `awayTeam` | `id, name, shortName, code, country, url` |
| `homeScore`, `awayScore` | `current` plus `period1`, `period2`, `overtime`, `penalties`, … when available |
| `winner` | `home`, `away` or `draw` |
| `venue`, `city`, `referee`, `attendance`, `hasXg` | Match info (filled when any match detail is requested; youth and lower leagues often have none) |
| `statistics` | Optional. Whole match and per half/period: possession, expected goals, big chances, shots, passes, duels, tackles, saves… with display and numeric values |
| `lineups` | Optional. Formation, starters and bench (position, shirt number, rating, minutes, per-player stats), missing players and why |
| `incidents` | Optional. Goals (scorer, assist, score after the goal), cards with reason, substitutions, VAR, periods, in match order |
| `odds` | Optional. 1X2, double chance, draw no bet, both teams to score, over/under lines…: decimal and fractional, opening and current, winning flag |
| `shotmap` | Optional (football). Every shot: player, minute, xG, xGOT, situation, body part, outcome, pitch coordinates |
| `scrapedAt` | When the row was collected (UTC) |

**Standings mode** rows: `tournament, season, group, position, team, played, wins, draws, losses, scoresFor,
scoresAgainst, scoreDiff, points, winPercentage, gamesBehind, streak, promotion, updatedAt`.
**Squads mode** rows: `name, team, position, positionsDetailed, shirtNumber, country, dateOfBirth, heightCm,
preferredFoot, marketValue, marketValueCurrency, contractUntil, url`.

### Use cases

- **Football analytics and scouting:** a league's full season of results with xG, shots and player ratings from
  lineups; squads with market values and contract end dates.
- **Betting models:** tomorrow's fixtures with opening vs current odds; results with statistics for backtests;
  live-score polling.
- **Apps, bots and dashboards:** scheduled fixtures, live scores and league tables for websites, Discord/Telegram bots
  and fantasy games, across football, basketball, tennis, ice hockey, esports and more.
- **Journalism and research:** match facts (scorers, cards, attendance, referee) and season tables on demand.

### Input

| Field | Description |
| --- | --- |
| `mode` | `matches` (default), `standings` or `squads` |
| `sports` | One or more of 25 sports (default football). Used for days/live and for name lookups |
| `dates` | UTC days: `2026-10-21`, `today`, `yesterday`, `tomorrow`, `+2`, `-3`. Defaults to today when no other source is given |
| `liveOnly` | Only matches in progress right now |
| `tournaments`, `seasonId`, `tournamentMatches` | League URLs, ids or names (`Premier League`), an optional past season id, results/fixtures/both |
| `teams` | Team URLs, ids or names (`Real Madrid`) → recent results and upcoming matches, or the squad in `squads` mode |
| `matchUrls` | Match URLs or ids |
| `countries`, `tournamentFilter`, `statuses` | Filters for day and live lists: country/region (`England`, `Europe`), tournament name words, match status |
| `includeStatistics`, `includeLineups`, `includeIncidents`, `includeOdds`, `includeShotmap` | Per-match details |
| `standingsType` | `total`, `home` or `away` table |
| `maxItems` | Maximum rows |
| `proxyConfiguration` | Leave the default: the actor picks working Apify Proxy IPs by itself |

#### Example: yesterday's top-league results with stats, goals and odds

```json
{
  "dates": ["yesterday"],
  "tournamentFilter": ["Premier League", "LaLiga", "Serie A", "Bundesliga", "Ligue 1", "Champions League"],
  "countries": ["England", "Spain", "Italy", "Germany", "France", "Europe"],
  "statuses": ["finished"],
  "includeStatistics": true,
  "includeIncidents": true,
  "includeOdds": true
}
```

#### Example: Premier League season results, then the table

```json
{ "tournaments": ["Premier League"], "tournamentMatches": "last", "includeStatistics": true, "maxItems": 400 }
```

```json
{ "mode": "standings", "tournaments": ["Premier League", "LaLiga", "NBA"], "sports": ["football", "basketball"] }
```

#### Example output (shortened)

```json
{
  "matchId": 16363890,
  "url": "https://www.sofascore.com/football/match/tottenham-hotspur-coventry-city/lsI#id:16363890",
  "sport": "football",
  "status": "finished",
  "startTime": "2026-10-19T19:00:00Z",
  "country": "England",
  "tournament": "Premier League",
  "season": "Premier League 26/27",
  "round": "Round 7",
  "homeTeam": {"id": 33, "name": "Tottenham Hotspur", "code": "TOT"},
  "awayTeam": {"id": 11, "name": "Coventry City", "code": "COC"},
  "homeScore": {"current": 3, "period1": 1, "period2": 2},
  "awayScore": {"current": 1, "period1": 0, "period2": 1},
  "winner": "home",
  "venue": "Tottenham Hotspur Stadium",
  "referee": "Andy Madley",
  "attendance": 60913,
  "statistics": {"all": {"ballPossession": {"name": "Ball possession", "home": "65%", "away": "35%", "homeValue": 65, "awayValue": 35},
                         "expectedGoals": {"name": "Expected goals", "home": "0.86", "away": "0.77"}}},
  "incidents": [{"type": "goal", "minute": 14, "team": "home", "player": {"id": 334, "name": "James Maddison"}, "homeScore": 1, "awayScore": 0}],
  "odds": [{"market": "Full time", "choices": [{"name": "1", "side": "home", "decimal": 1.53, "initialDecimal": 1.48, "winning": true},
                                              {"name": "X", "side": "draw", "decimal": 4.5}, {"name": "2", "side": "away", "decimal": 6.0}]}],
  "scrapedAt": "2026-10-22T08:00:00Z"
}
```

### Scheduling and integrations

Create a **Schedule** in Apify Console (every few minutes with `liveOnly`, or daily with `dates: ["yesterday"]`).
Read results through the Apify API (`/v2/datasets/{id}/items?format=json|csv|xlsx`) or send them on with webhooks and
integrations (Google Sheets, Slack, Make, Zapier, Airbyte).

### Use it from AI assistants

The actor works as a tool in AI agents through the Apify MCP server (`https://mcp.apify.com`): ask for "yesterday's
Premier League results with xG" or "the LaLiga table" and the agent can run it and read the dataset.

### FAQ

**Which sports?** Football, basketball, tennis, ice hockey, American football, baseball, handball, volleyball, rugby,
cricket, esports, table tennis, darts, snooker, futsal, motorsport, MMA, water polo, badminton, Aussie rules, beach
volleyball, floorball, bandy, mini football and cycling. Details depend on what Sofascore tracks per sport and league.
For tennis-specific fields (set and tie-break scores, point-by-point, ATP/WTA rankings) use our Tennis Scraper.

**How fresh is the data?** Each run reads Sofascore at run time. Live rows show the score at that moment.

**Why are statistics, lineups or shotmaps empty for some matches?** Sofascore only has them for leagues it covers in
depth; lower and youth leagues often have scores and goals only. Statistics and shotmaps exist once a match has
started; lineups appear about an hour before kick-off.

**Do I need a proxy?** No setup needed. The default Apify Proxy setting is enough; the actor switches IPs by itself
when one is blocked.

**Is this legal?** The actor collects publicly visible sports results and statistics. You are responsible for how
you use the data and for complying with Sofascore's terms in your jurisdiction.

**Something is wrong or missing?** Open an issue on the actor page. Issues are read and answered.

# Actor input Schema

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

Matches by day, live, tournament, team or URL; league standings; or team squads.

## `sports` (type: `array`):

Sports for days/live and for name lookups.

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

UTC days to collect every match of: YYYY-MM-DD or today, yesterday, tomorrow, +2, -3. Defaults to today when no other source is given.

## `liveOnly` (type: `boolean`):

Only matches in progress right now (one request per sport). Other sources are ignored.

## `tournaments` (type: `array`):

Tournament URLs, ids or names (e.g. 'Premier League', https://www.sofascore.com/football/tournament/england/premier-league/17). Matches mode: the season's fixtures and/or results. Standings mode: the league table.

## `seasonId` (type: `integer`):

Optional: a past season's id (default = current season). Season ids are in the output's seasonId field.

## `tournamentMatches` (type: `string`):

For tournaments in matches mode: results, fixtures or both.

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

Team URLs, ids or names (e.g. 'Arsenal'). Matches mode: recent results and upcoming matches. Squads mode: the squad.

## `matchUrls` (type: `array`):

e.g. https://www.sofascore.com/football/match/tottenham-hotspur-coventry-city/lsI#id:16363890 or 16363890.

## `countries` (type: `array`):

Keep matches from these countries/regions (Sofascore category name or code, e.g. England, Spain, EN, International).

## `tournamentFilter` (type: `array`):

Keep matches whose tournament name contains any of these words (e.g. 'Premier League', 'Champions League').

## `statuses` (type: `array`):

Keep only these statuses. Empty = all.

## `includeStatistics` (type: `boolean`):

Possession, xG, shots, passes, duels, saves... for the match and each half/period.

## `includeLineups` (type: `boolean`):

Formations, starting XI and bench with ratings, minutes and per-player stats, plus missing players. Usually published ~1 hour before kick-off.

## `includeIncidents` (type: `boolean`):

Goals (scorer, assist), cards, substitutions, VAR, periods.

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

Bookmaker markets (1X2, double chance, BTTS, over/under...): decimal and fractional, opening and current.

## `includeShotmap` (type: `boolean`):

Every shot with player, minute, xG, xGOT, body part, situation and pitch coordinates (football).

## `standingsType` (type: `string`):

Overall, home-only or away-only league table.

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

Maximum number of rows to return. You are charged per row.

## `proxyConfiguration` (type: `object`):

Default (Apify Proxy, automatic) tries datacenter IPs and switches to residential when Sofascore challenges them.

## Actor input object example

```json
{
  "mode": "matches",
  "sports": [
    "football"
  ],
  "dates": [
    "today"
  ],
  "liveOnly": false,
  "tournamentMatches": "both",
  "includeStatistics": false,
  "includeLineups": false,
  "includeIncidents": false,
  "includeOdds": false,
  "includeShotmap": false,
  "standingsType": "total",
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (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": "matches",
    "sports": [
        "football"
    ],
    "dates": [
        "today"
    ],
    "maxItems": 20,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("axlymxp/sofascore-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": "matches",
    "sports": ["football"],
    "dates": ["today"],
    "maxItems": 20,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("axlymxp/sofascore-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": "matches",
  "sports": [
    "football"
  ],
  "dates": [
    "today"
  ],
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call axlymxp/sofascore-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,axlymxp/sofascore-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/OmKfmZ4O4TeUsqYEh/builds/LolV5y4vsdSjwQ6mm/openapi.json