SofaScore Football Scraper

We built SofaScore Football Scraper to provide a straightforward, query-based way to collect comprehensive football data. This Actor connects directly to SofaScore to gather public match, player, team, and competition data on-demand, allowing you to focus on analysis rather than data scraping.

Instead of writing custom browser automation or managing rotating proxy setups, you can retrieve structured results instantly using our seven pre-built modes.

Unofficial Actor: This is an independent tool and is not affiliated with, authorized, or endorsed by SofaScore.

Looking for tennis data? Use our companion Tennis Scraper for live matches, tournaments, point-by-point data, and historical player statistics.

---

What you can do with this Actor

We designed seven focused ways into the football data so you can run specific data-mining jobs without getting bogged down in boilerplate code. You can daisy-chain these modes together using the unique IDs returned in your datasets.

1. Track live matches and odds (liveMatches)

Run the scraper with no configuration to get a current snapshot of matches currently in progress in the active SofaScore live football feed. Each row represents a live match with scores, match periods, red cards, and match-level 1X2 odds when available.

2. Get matches by date (matchesByDate)

Pass a specific date (YYYY-MM-DD) and page number to retrieve scheduled matches. It selects a specific scheduled-competition page for that date, returning match details, status, current scores, and odds.

3. Discover competition seasons (competitionSeasons)

Provide a unique SofaScore competition ID (like Premier League 17) to get a flat list of all historical and current seasons with their unique season IDs, names, and years.

4. Explore competition details (competitionDetails)

Pass a competition ID and an optional season ID to retrieve a full competition aggregate, including standings, historical/upcoming match pages, rounds, cup trees, top leaderboards, and seasonal awards.

5. Inspect match anatomy (matchDetails)

Pass a unique match ID to extract in-depth details: available lineups (with player ratings and match stats), incidents (goals, cards, VAR, substitutions), team statistics, shot maps, and extensive odds markets.

6. Deep-dive into team records (teamDetails)

Pass a unique team ID alongside distinct standings and statistics competition/season contexts. The Actor returns the team's squad roster (with birthdates, market values, and contract info), trophies, and competition-wide overall statistics. Standings and statistics contexts must be supplied separately.

7. Retrieve player profiles (playerDetails)

Pass a unique player ID alongside a statistics competition and season ID. This compiles the player's profile, recent match ratings, overall season statistics, strengths and weaknesses, and career totals.

---

ID Discovery & Chaining Workflow

To scrape detailed records for matches, competitions, teams, or players, you must provide their respective unique SofaScore IDs. This workflow outlines how you can discover and chain these IDs together in a clean data pipeline:

┌───────────────────────┐
               │  liveMatches          │
               │  or matchesByDate     │
               └───────────┬───────────┘
                           │
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
  [  matchId  ]     [ competitionId ]    [  teamId  ]
        │                  │                  │
        ▼                  ▼                  ▼
┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│ matchDetails  │  │ competition-  │  │  teamDetails  │
└───────┬───────┘  │   Seasons     │  └───────────────┘
        │          └───────┬───────┘
        ▼                  ▼
  [ playerId ]        [ seasonId ]
        │                  │
        ▼                  ▼
┌───────────────┐  ┌───────────────┐
│ playerDetails │  │ competition-  │
└───────────────┘  │   Details     │
                   └───────────────┘

1. Discover Core IDs: Run liveMatches or matchesByDate to find match event IDs (matchId), competition IDs (competitionId), and team IDs (teamId).
2. Resolve Season IDs: Run competitionSeasons using your chosen competitionId to resolve the available season IDs. Note that teamDetails and playerDetails require you to explicitly supply these standings and statistics contexts as separate inputs.
3. Discover Player IDs: Inspect available lineups inside matchDetails or leaderboard stats in competitionDetails to extract unique player IDs (playerId).
4. Run Detail Aggregates: Feed these IDs into matchDetails, teamDetails (providing both standings and statistics contexts), or playerDetails for high-resolution profiles.

---

Quick Start

1. Click Try for free on the Actor page.
2. Under Scraper mode, choose Live matches or your desired mode.
3. Click Start.
4. Open the Dataset tab when the run finishes.

For your first run, you can use the default live match mode with no extra input:

{
  "mode": "liveMatches"
}

If no matches are live when you run the Actor, the run succeeds with an empty dataset.

Other Typical Inputs

Retrieve scheduled matches for a specific date (returns one scheduled-competition page):

{
  "mode": "matchesByDate",
  "date": "2026-07-27",
  "page": 1
}

Deep-dive into team records (requires separate standings and statistics contexts):

{
  "mode": "teamDetails",
  "teamId": 42,
  "standingsCompetitionId": 17,
  "standingsSeasonId": 76986,
  "statsCompetitionId": 17,
  "statsSeasonId": 76986
}

---

Data Structure & Examples

Each dataset row represents a single football record. The Apify Dataset stores nested arrays and objects, and JSON exports preserve this rich hierarchical structure. (Tabular exports like CSV or Excel will flatten or serialize these fields).

Note: Odds and optional detail resources (such as lineup stats, shotmaps, or V2 momentum charts) may be unavailable depending on the match status or coverage.

Live Match Snippet (liveMatches)

This is an abridged preview of selected fields, not a complete Dataset row.

{
  "id": 14025099,
  "slug": "arsenal-chelsea",
  "status": "inprogress",
  "currentPeriod": "period1",
  "tournamentName": "Premier League",
  "homeTeamName": "Arsenal",
  "awayTeamName": "Chelsea",
  "score": {
    "home": 1,
    "away": 0,
    "periods": [
      { "period": "period1", "home": 1, "away": 0 }
    ]
  },
  "odds": {
    "home": { "decimal": 1.85, "fractional": "17/20" },
    "draw": { "decimal": 3.6, "fractional": "13/5" },
    "away": { "decimal": 4.2, "fractional": "16/5" }
  }
}

Match Details Snippet (matchDetails)

This is an abridged preview of selected fields, demonstrating the rich nested statistics returned.

{
  "id": 14025099,
  "slug": "arsenal-chelsea",
  "status": "finished",
  "homeTeamName": "Arsenal",
  "awayTeamName": "Chelsea",
  "score": { "home": 2, "away": 1 },
  "venueName": "Emirates Stadium",
  "refereeName": "Michael Oliver",
  "playerOfTheMatchName": "Bukayo Saka",
  "playerOfTheMatchRating": 8.7,
  "incidents": [
    { "incidentType": "goal", "time": 15, "playerName": "Bukayo Saka", "assistName": "Martin Ødegaard" }
  ],
  "homeLineupPlayers": [
    {
      "id": 934235,
      "name": "Bukayo Saka",
      "position": "M",
      "rating": 8.7,
      "substitute": false,
      "statistics": { "goals": 1, "assists": 1, "totalShots": 3, "keyPasses": 4 }
    }
  ],
  "statistics": [
    {
      "period": "ALL",
      "groups": [
        {
          "name": "Shots",
          "items": [
            { "name": "Total shots", "home": "14", "away": "8", "homeValue": 14, "awayValue": 8 }
          ]
        }
      ]
    }
  ]
}

---

Operational & Billing Details

Managed Proxies

To handle rate limits and source blocks, SofaScore requests on Apify are automatically routed through residential proxies. No user-side proxy configuration or credentials are required. Note that while this helps protect runs from immediate blocking, it does not guarantee uninterrupted source availability.

Pay-per-Event Billing

We utilize Apify's Pay Per Event (PPE) model, which charges you based on successful operations rather than compute time or row counts:

• One Successful Result Event: A successful run charges exactly one custom successful-result event, regardless of how many rows are returned.
• Uncharged Scrape Failures: If a scraping operation terminates due to an unrecoverable source error or IP block, a terminal scrape failure is recorded. When possible, the Actor writes a diagnostic error row containing the failure details to help you troubleshoot. These terminal scrape failures do not charge the successful-result event.
• Empty Successes: If a run returns zero results under a valid query (for example, if no matches are live or a valid competition response contains no season rows), it is considered a valid successful operation and charges one successful-result event. Note that invalid parameters or incorrect IDs may trigger a run failure rather than an empty success.

Check the Actor's Pricing tab for current rates.

---

Use with Apify MCP

If you are integrating football data into AI workflows, you can run this Actor through Apify's hosted Model Context Protocol (MCP) server to connect directly to compatible AI clients (such as Claude Desktop):

https://mcp.apify.com?tools=crawlstone/sofascore-football-scraper

Once connected, you can query match details, live scores, team lineups, standings, and player statistics using natural language through your AI assistant.

---

Frequently Asked Questions

What should I do when a run returns zero rows?

This is normal. The scraper returns empty datasets when there are no live matches in progress (e.g., late at night between matchdays) or when a valid competition query returns zero season rows. If you need regular updates, configure an Apify Schedule to run the Actor periodically.

How do I fetch team details if they require standings and statistics contexts?

To run teamDetails, you must supply distinct standings and statistics contexts (such as standingsCompetitionId and statsCompetitionId, alongside their respective season IDs). You can find the available season IDs for your chosen competition by running competitionSeasons first. Note that each Actor run executes exactly one selected mode at a time.

Can I get continuous real-time updates?

No. This Actor is designed for static, on-demand Dataset snapshots. If you need regular snapshots of active match events, configure an Apify Schedule to run the Actor at set intervals.

---

Support

If you need assistance, please open a ticket on this Actor's Discussion tab and include:

• Your Apify Run ID.
• The selected Mode and the Input values you provided.
• A description of what you expected versus what occurred.

Do not share your Apify API Token or other private credentials in support tickets.