# Flashscore Football Scraper - Live Scores, Results & Stats (`clearfetch/flashscore-football-scraper`) Actor

Scrape football matches from Flashscore across every league: fixtures, live scores, final results, halftime and second-half scores, extra time and penalty shootouts, goalscorers with assists, cards, substitutions and match statistics. No proxy, no login.

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

## Pricing

from $1.00 / 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.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Flashscore Football Scraper - Live Scores, Results & Stats

Get football data from Flashscore as clean JSON: fixtures for the days you choose, live scores, final results
with halftime and second-half breakdowns, extra time and penalty shootouts, and, per match, every goal with its
assist, cards with the offence, substitutions and full match statistics including expected goals. Every league
Flashscore covers, from the Premier League to the Brazilian state divisions. No login, no API key and no proxy.

### What data you get

**Matches mode** returns one row per match:

- **Status resolved from Flashscore's own stage codes**, not guessed: scheduled, live, finished, postponed,
  cancelled or interrupted, plus `stageDetail` naming the exact stage (`FIRST_HALF`, `HALF_TIME`,
  `EXTRA_TIME`, `AFTER_PENALTIES`, `AWARDED`).
- **Score with its parts**: full-time score, first and second half, after extra time, and the penalty shootout.
- **Winner including draws**, which is the field most scrapers get wrong by only reporting a side.
- **Competition**: name, country, phase such as Qualification or Play Offs, plus IDs and the Flashscore URL.
- **Teams**: name, Flashscore team ID and slug, three-letter code and crest image.
- **`raw`**: all 41 original feed fields for the match, so nothing is lost if you need something we did not map.

**Match details mode** takes match IDs and returns, per match:

- **Goals, cards and substitutions** with the minute, the side, the player, the assisting player, the running
  score after each goal, and the reason attached to a card or a disallowed goal. 19 incidents in the example below.
- **Match statistics** split by period and group: expected goals, possession, shots, corners, fouls, saves and
  more. 120 rows for that match.
- **Head to head**: recent form for both teams and their previous meetings.

### How to use

1. Choose **Matches** mode and set **Days** (0 is today, -1 yesterday, 1 tomorrow; add several for a range).
2. Narrow it down if you want: by status, by country, or with a regular expression on the competition name.
   A full day of world football is 1,500 to 2,000 matches, so a filter is usually worth setting.
3. Run it, then export as JSON, CSV or Excel, or read it from the API. To go deeper on a match, run the Actor
   again in **Match details** mode with the `matchId` values you got back.

### Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `mode` | string | `matches` | `matches` for fixtures, live scores and results; `matchDetails` for goals, cards, statistics and head to head. |
| `days` | array | `["0"]` | Day offsets from today, from -7 to 7. Several entries are fetched in one run and deduplicated. |
| `status` | array | all | Keep only `scheduled`, `live`, `finished`, `postponed`, `cancelled` or `interrupted`. |
| `countries` | array | all | Keep only these countries or regions, for example England, Spain, Europe. |
| `tournamentFilter` | string | — | Case-insensitive regular expression on the full competition name, e.g. `champions league|europa`. |
| `matchIds` | array | — | Details mode: match IDs such as `nauPfE4F`, or full `flashscore.com/match/...` URLs. |
| `details` | array | all three | Details mode: `summary`, `statistics`, `h2h`. |
| `maxItems` | integer | `0` | Stop after this many rows; 0 means no limit. |
| `maxConcurrency` | integer | `5` | Parallel requests in details mode. |
| `timeoutSecs` | integer | `30` | Per-request timeout. |
| `token` | string | — | Advanced. Overrides the feed signature, which the Actor otherwise discovers by itself. |
| `proxyConfiguration` | object | off | Optional. Not needed in normal use. |

### Output example

One match from a **matches** run (the `raw` object with all 41 feed fields is omitted here for readability):

```json
{
  "matchId": "A7Ob65ig",
  "url": "https://www.flashscore.com/match/A7Ob65ig/",
  "sport": "football",
  "status": "finished",
  "stage": "finished",
  "stageDetail": "FINISHED",
  "stageCode": 3,
  "stageDetailCode": 3,
  "startTime": "2026-09-05T11:30:00.000Z",
  "lastUpdate": "2026-09-05T13:25:43.000Z",
  "note": null,
  "tournament": {
    "name": "Premier League",
    "fullName": "ENGLAND: Premier League",
    "country": "England",
    "phase": null,
    "id": "CfoA8Dmm",
    "stageId": "dYlOSQOD",
    "path": "/football/england/premier-league/",
    "url": "https://www.flashscore.com/football/england/premier-league/"
  },
  "home": {
    "name": "Newcastle",
    "fullName": "Newcastle",
    "id": "xlRGtL0n",
    "slug": "newcastle-utd",
    "url": "https://www.flashscore.com/team/newcastle-utd/xlRGtL0n/",
    "code": "NEW",
    "image": "https://static.flashscore.com/res/image/data/UXo7VXPq-2Vnc5VQf.png"
  },
  "away": {
    "name": "Bournemouth",
    "fullName": "Bournemouth",
    "id": "pEUOvaVb",
    "slug": "bournemouth",
    "url": "https://www.flashscore.com/team/bournemouth/pEUOvaVb/",
    "code": "BOU",
    "image": "https://static.flashscore.com/res/image/data/C60HMWTH-2XyrBA7b.png"
  },
  "score": {
    "home": 2,
    "away": 2,
    "firstHalf": {
      "home": 1,
      "away": 2
    },
    "secondHalf": {
      "home": 1,
      "away": 0
    },
    "afterExtraTime": null,
    "penalties": null
  },
  "winner": "draw",
  "inPlay": false,
  "ok": true,
  "dayOffset": 0,
  "scrapedAt": "2026-09-05T14:25:49.907Z"
}
```

A **match details** item, trimmed to the first incidents, statistics and one head-to-head match:

```json
{
  "matchId": "A7Ob65ig",
  "url": "https://www.flashscore.com/match/A7Ob65ig/",
  "sport": "football",
  "ok": true,
  "summary": {
    "periods": [
      {
        "period": "1st Half",
        "home": 1,
        "away": 2
      },
      {
        "period": "2nd Half",
        "home": 1,
        "away": 0
      }
    ],
    "incidents": [
      {
        "id": "vXvmuLs2",
        "period": "1st Half",
        "minute": "9'",
        "side": "away",
        "overturned": false,
        "label": "Goal",
        "reason": null,
        "scoreHome": 0,
        "scoreAway": 1,
        "participants": [
          {
            "type": "goal",
            "typeCode": 3,
            "name": "Tavernier M.",
            "playerId": "jFqXIRZj",
            "url": "https://www.flashscore.com/player/tavernier-marcus/jFqXIRZj/",
            "role": "Goal"
          }
        ],
        "type": "goal",
        "player": "Tavernier M."
      },
      {
        "id": "hCprNG1c",
        "period": "1st Half",
        "minute": "28'",
        "side": "home",
        "overturned": false,
        "label": "Yellow Card",
        "reason": "Elbowing",
        "scoreHome": null,
        "scoreAway": null,
        "participants": [
          {
            "type": "yellow-card",
            "typeCode": 1,
            "name": "Elanga A.",
            "playerId": "dOlRWlZ6",
            "url": "https://www.flashscore.com/player/elanga-anthony/dOlRWlZ6/",
            "role": "Yellow Card"
          }
        ],
        "type": "yellow-card",
        "player": "Elanga A."
      },
      {
        "id": "ddyGxKko",
        "period": "1st Half",
        "minute": "35'",
        "side": "away",
        "overturned": false,
        "label": "Own goal",
        "reason": null,
        "scoreHome": 0,
        "scoreAway": 2,
        "participants": [
          {
            "type": "own-goal",
            "typeCode": 4,
            "name": "Thiaw M.",
            "playerId": "0vSsR1xI",
            "url": "https://www.flashscore.com/player/thiaw-malick/0vSsR1xI/",
            "role": "Own goal"
          }
        ],
        "type": "own-goal",
        "player": "Thiaw M."
      }
    ]
  },
  "statistics": [
    {
      "period": "Match",
      "group": "Top stats",
      "name": "Expected goals (xG)",
      "home": "0.67",
      "away": "1.50"
    },
    {
      "period": "Match",
      "group": "Top stats",
      "name": "Ball possession",
      "home": "57%",
      "away": "43%"
    },
    {
      "period": "Match",
      "group": "Top stats",
      "name": "Total shots",
      "home": "8",
      "away": "17"
    },
    {
      "period": "Match",
      "group": "Top stats",
      "name": "Shots on target",
      "home": "2",
      "away": "5"
    }
  ],
  "h2h": [
    {
      "heading": "Last matches: Newcastle",
      "section": "Overall",
      "matches": [
        {
          "matchId": "A7Ob65ig",
          "url": "https://www.flashscore.com/match/A7Ob65ig/",
          "date": "2026-09-05T11:30:00.000Z",
          "competition": "Premier League",
          "competitionCode": "PL",
          "country": "England",
          "home": {
            "name": "Newcastle",
            "slug": "newcastle-utd",
            "id": "p6ahwuwJ"
          },
          "away": {
            "name": "Bournemouth",
            "slug": "bournemouth",
            "id": "OtpNdwrc"
          },
          "score": "2:2",
          "scoreHome": 2,
          "scoreAway": 2,
          "winner": null
        }
      ]
    }
  ],
  "scrapedAt": "2026-09-05T14:25:34.913Z"
}
```

A match that cannot be found, or has no data yet, produces `{ "matchId": "...", "ok": false, "error": "..." }`
and is not charged.

### Pricing

- **$0.001 per match** in matches mode. A full day of world football is roughly 1,500 to 2,000 matches, about
  $1.50 to $2.00 for everything, or a few cents once you filter by country or competition.
- **$0.01 per match** in details mode, whatever number of sections you request. Goals, cards, substitutions,
  every statistic and both teams' recent form count as one charge.
- Matches that fail or have no data are free. Runs on the Apify free plan.

### Use cases

- **Betting and trading models**: build a history of results, halftime splits, expected goals and shot volumes,
  then keep it current with a scheduled daily run.
- **Live scoreboards and bots**: poll matches mode for in-play scores and push updates to a site, app or Discord.
- **Fantasy football**: settle goals, assists and cards from the incident feed.
- **Media and newsletters**: generate daily results digests with scorers and headline statistics.
- **Research and machine learning**: label datasets across leagues and seasons, including shootouts, extra time
  and abandoned matches, which most feeds quietly drop.
- **AI agents**: give an assistant a tool that answers "who scored in the Newcastle match" or "what is on today
  in Spain".

### Integrations

```bash
curl -X POST "https://api.apify.com/v2/acts/clearfetch~flashscore-football-scraper/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"days": ["0"], "countries": ["England"], "status": ["finished"]}'
```

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_TOKEN")
run = client.actor("clearfetch/flashscore-football-scraper").call(
    run_input={"days": ["0"], "countries": ["England"], "status": ["finished"]}
)
for match in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(match["home"]["name"], match["score"]["home"], "-", match["score"]["away"], match["away"]["name"])
```

Works with the Apify integrations for n8n, Make, Zapier, Google Sheets, Slack and webhooks, with scheduled runs,
and with AI agents through the Apify MCP server.

### FAQ

**Do I need a proxy?** No. The feed answers ordinary datacenter requests. A proxy input exists if you want one.

**Do I need a Flashscore account?** No. Nothing here requires a login or a cookie.

**How is the score reported after a penalty shootout?** As Flashscore displays it, which adds the shootout
winner's extra point: a 0-0 match won 4-3 on penalties is published as 1-0, with `penalties` carrying 4-3.
Because that inflates the displayed score, `firstHalf` is left null on those matches rather than derived from a
number that would be wrong. Match details mode returns the labelled periods straight from the source.

**How fresh is the data?** Each run reads the feed live, so matches in progress carry their current score.
Schedule a run every few minutes if you need a running scoreboard.

**What if Flashscore changes its feed signature?** The Actor discovers the current signature from the site on
every run and falls back to a known value, so a rotation does not break it. The `token` input is a last resort.

**Which sports does this cover?** Football. The same feed carries other sports; ask if you want one added.

**Is this legal?** It reads the same public endpoints a browser reads, with no login and no personal data.
Scores and results are facts. You are responsible for how you use the data, including any redistribution.

### Changelog

- **1.0.0** (2026-09) — first release: matches mode with day ranges and status, country and competition filters;
  details mode with goals, assists, cards, substitutions, statistics and head to head; status resolved from
  Flashscore's own stage codes; automatic feed-signature discovery.

# Actor input Schema

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

"Matches" returns one row per match for the days you choose. "Match details" takes match IDs and returns goals, cards, substitutions, statistics and head-to-head for each one.

## `days` (type: `array`):

Which days to cover, as offsets from today: 0 is today, -1 yesterday, 1 tomorrow. Range -7 to 7. Add several entries to cover a range in one run.

## `status` (type: `array`):

Keep only matches in these states. Leave empty for all. Status is resolved from Flashscore's own stage codes, so a match in the second half counts as live, not as something else.

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

Keep only competitions from these countries or regions, for example England, Spain, Europe. Case-insensitive, matched against the country shown by Flashscore. Leave empty for all.

## `tournamentFilter` (type: `string`):

Optional case-insensitive regular expression matched against the full competition name, for example "premier league" or "champions league|europa".

## `matchIds` (type: `array`):

Match IDs such as "nauPfE4F", or full flashscore.com/match/... URLs. Only used when the mode is "Match details". Get IDs from the matchId field of a matches run.

## `details` (type: `array`):

Sections to fetch per match. Leave empty for all three. Each match is charged once no matter how many sections you pick.

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

Stop after this many rows. 0 means no limit. A full day of world football is roughly 1,500 to 2,000 matches.

## `maxConcurrency` (type: `integer`):

Parallel requests in details mode.

## `timeoutSecs` (type: `integer`):

Give up on a single feed request after this many seconds.

## `token` (type: `string`):

Advanced. The Actor discovers Flashscore's feed signature automatically and falls back to a known value. Set this only if both stop working and you have a current signature.

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

Optional. The feed answers plain datacenter requests, so no proxy is needed in normal use.

## Actor input object example

```json
{
  "mode": "matches",
  "days": [
    "0"
  ],
  "status": [],
  "countries": [],
  "matchIds": [],
  "details": [],
  "maxItems": 0,
  "maxConcurrency": 5,
  "timeoutSecs": 30,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

In matches mode, one row per match: status, kick-off time, competition with country and phase, both teams, score with halftime, second half, extra time and penalty shootout, and the winner including draws. In match details mode, one row per match with goals and assists, cards, substitutions, disallowed goals, statistics split by period, and head-to-head. Matches with no data appear with ok=false and are not charged.

# 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 = {
    "days": [
        "0"
    ],
    "countries": [],
    "matchIds": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("clearfetch/flashscore-football-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 = {
    "days": ["0"],
    "countries": [],
    "matchIds": [],
}

# Run the Actor and wait for it to finish
run = client.actor("clearfetch/flashscore-football-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 '{
  "days": [
    "0"
  ],
  "countries": [],
  "matchIds": []
}' |
apify call clearfetch/flashscore-football-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,clearfetch/flashscore-football-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/JkSIK64qZZFnN7R3W/builds/0fGTOrkzHgBH1PUfV/openapi.json