# Flashscore: Match Listings, Scores & Fixtures (`extractify-labs/flashscore-extractor`) Actor

Extract match listings from Flashscore for football and basketball. Filter by date (-7 to +7 days), match status, or league. Returns teams, scores, tournament, and match metadata.

- **URL**: https://apify.com/extractify-labs/flashscore-extractor.md
- **Developed by:** [Extractify Labs](https://apify.com/extractify-labs) (community)
- **Categories:** News, Other
- **Features:** Limited permissions
- **Stats:** 400 total users, 45 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $0.001 / result

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

## Flashscore: Match Listings, Scores & Fixtures

Extract match listings from [Flashscore](https://www.flashscore.com) for football (soccer) and basketball — no proxy required. This Flashscore scraper (data extractor) fetches a point-in-time snapshot of matches within a ±7-day window: yesterday's results, today's live matches, and upcoming fixtures, all in one run. Returns 19 structured fields per match including teams, scores, tournament, and match metadata.

### What does this actor extract?

Every match record contains 19 fields covering teams, scores, tournament context, and match identity.

| Field | Type | Example |
|-------|------|---------|
| `match_id` | string | `"aB3xK9mQ"` |
| `match_date` | string (ISO 8601) | `"2026-04-16T19:45:00"` |
| `match_url` | string (URL) | `"https://www.flashscore.com/match/football/..."` |
| `match_status` | string | `"Finished"` / `"1st Half"` / `"Scheduled"` |
| `match_score_home_goals` | integer | `2` |
| `match_score_away_goals` | integer | `1` |
| `stage_description` | string | `"2nd Half"` / `"Half Time"` |
| `home_team_name` | string | `"Manchester City"` |
| `home_team_short_name` | string | `"Man City"` |
| `home_team_id` | string | `"dKq7LP"` |
| `away_team_name` | string | `"Arsenal"` |
| `away_team_short_name` | string | `"Arsenal"` |
| `away_team_id` | string | `"nRs2XB"` |
| `tournament_name` | string | `"Premier League"` |
| `tournament_id` | string | `"TNmw3"` |
| `tournament_url` | string (URL) | `"https://www.flashscore.com/football/england/premier-league/"` |
| `sport_name` | string | `"football"` |
| `sport_id` | string | `"1"` |
| `category_name` | string | `"England"` |

### Who is this for?

This actor serves three primary audiences:

- **Betting and odds analysts:** Feed match results, live statuses, and tournament context into your odds model or results database. Filter to specific leagues (e.g. `"Champions League"`, `"NBA"`) and combine past results with upcoming fixtures in a single run.
- **Fantasy sports and gaming platforms:** Populate your fantasy league dashboard with today's scores and tomorrow's fixtures. Use `dayOffsets` to target any combination of days in the current 14-day window.
- **Data journalists and researchers:** Build a daily match results pipeline for content automation, academic research, or sports analytics. The structured JSON output integrates directly with standard data pipelines and spreadsheet tools.

### Why use this actor?

**Focused, accurate scope.** This actor does exactly what it says: match listings, scores, and fixture metadata. No stats, no odds, no guesswork about what you will get.

**Documented date window.** Fetch up to 7 days back and 7 days forward (14-day total window) in a single run. No competitor documents this as a specific, bounded range.

**No proxy required.** The actor fetches directly from Flashscore's feed endpoint. You pay only for Apify compute — no residential or datacenter proxy costs on top.

**Honest live data model.** Matches with status `"live"` reflect their state at the moment the actor runs. This is a point-in-time snapshot, not a continuous push feed. If you need near-real-time monitoring, schedule the actor to run on a short interval via Apify Scheduler.

### How to use it

1. Open the actor on the [Apify Store](https://apify.com/extractify-labs/flashscore-extractor).
2. Select your sport(s): `football`, `basketball`, or both.
3. Set `dayOffsets` to the days you want. Use `[0]` for today only, `[-1, 0, 1]` for yesterday/today/tomorrow, or any combination from -7 to +7.
4. (Optional) Filter by match status (`finished`, `live`, `scheduled`, or `all`) and by league name (e.g. `["Premier League"]` or `["NBA"]`).
5. Click **Start** and download results as JSON, CSV, or XLSX when the run completes.

**Sample input (JSON):**

```json
{
  "sports": ["football", "basketball"],
  "dayOffsets": [-1, 0, 1],
  "matchStatuses": ["finished", "live"],
  "leagues": ["Premier League"],
  "maxItems": 100
}
```

### Input parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `sports` | array | `["football"]` | Sports to extract. Supported values: `football`, `basketball`. |
| `dayOffsets` | array | `[0]` | Days relative to today. `0` = today, `-1` = yesterday, `7` = 7 days ahead. Range: -7 to +7. |
| `matchStatuses` | array | `["all"]` | Filter by match status: `all`, `finished`, `live`, `scheduled`. If `all` is included, other values are ignored. Note: `live` reflects status at the moment of the run — this is a snapshot, not a real-time feed. |
| `leagues` | array | `[]` | Filter by league or tournament name. Partial, case-insensitive match (e.g. `"Champions"` matches all Champions League variants). Leave empty to return all leagues. |
| `maxItems` | integer | — | Optional cap on total results. Leave unset to return all matches. |

### Output format

A complete match record looks like this:

```json
{
  "match_id": "aB3xK9mQ",
  "match_date": "2026-04-16T19:45:00",
  "match_url": "https://www.flashscore.com/match/football/manchester-city-dKq7LP/arsenal-nRs2XB/?mid=aB3xK9mQ",
  "match_status": "Finished",
  "match_score_home_goals": 2,
  "match_score_away_goals": 1,
  "stage_description": "Finished",
  "home_team_name": "Manchester City",
  "home_team_short_name": "Man City",
  "home_team_id": "dKq7LP",
  "away_team_name": "Arsenal",
  "away_team_short_name": "Arsenal",
  "away_team_id": "nRs2XB",
  "tournament_name": "Premier League",
  "tournament_id": "TNmw3",
  "tournament_url": "https://www.flashscore.com/football/england/premier-league/",
  "sport_name": "football",
  "sport_id": "1",
  "category_name": "England"
}
```

### Which sports are supported?

**Football (soccer) and basketball.** These are the only two sports currently supported. League filtering works across both: you can filter to `"Premier League"` for football or `"NBA"` for basketball in the same run by including both sports in the `sports` array.

The actor does not currently support tennis, hockey, volleyball, or other sports.

### No proxy required

This actor fetches match data directly from Flashscore's internal feed endpoint without residential or datacenter proxies. You are not charged for proxy bandwidth — only standard Apify compute costs apply. This makes it significantly cheaper to run at scale compared to scrapers that require proxy infrastructure.

### What this actor does not cover

This actor is intentionally focused on match listings. It does not extract:

- Betting odds or bookmaker lines
- Match statistics (possession, shots, cards, corners)
- League standings or tables
- Head-to-head (H2H) records
- Player profiles or player statistics
- News articles or match reports
- Images or media assets

If you need any of these, you will need a separate data source.

### FAQ

#### Is this actor a real-time live feed?

No. The actor fetches a point-in-time snapshot each time it runs. Matches with status `"live"` reflect their state at the moment of extraction — they do not update continuously. To approximate near-real-time data, schedule the actor to run at short intervals (e.g. every 2 minutes) using Apify Scheduler.

#### Which sports does this actor support?

Football (soccer) and basketball. These are the only two confirmed working sports. No other sports are currently available.

#### Can I get upcoming fixtures as well as past results?

Yes. Use the `dayOffsets` parameter with positive values for future days (e.g. `7` for matches 7 days from now) and negative values for past days (e.g. `-7` for matches 7 days ago). Any combination within the -7 to +7 range is valid.

#### Does this actor require a proxy?

No. The actor fetches directly from Flashscore's feed endpoint without any proxy. You do not need a residential or datacenter proxy subscription to use it.

#### Can I run this on a schedule?

Yes. Use [Apify Scheduler](https://docs.apify.com/platform/schedules) to run the actor automatically at any interval — every few minutes for near-real-time monitoring, once a day for a results digest, or whatever cadence fits your use case. Each run produces a fresh snapshot; combine it with your own storage or Apify's dataset API to build a running history.

#### Is scraping Flashscore legal?

Web scraping publicly available data is generally permitted for personal use and research purposes. Users are responsible for complying with [Flashscore's terms of service](https://www.flashscore.com/page/terms-of-service/) and applicable local laws. Apify's [legal guidelines on web scraping](https://apify.com/legal/web-scraping) provide further context.

### Related actors

- [Google News Scraper](https://apify.com/apify/google-news-scraper) — Extract sports news articles to accompany your match data

# Changelog

This Actor's version history is a separate document: https://apify.com/extractify-labs/flashscore-extractor/changelog.md

# Actor input Schema

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

Select the type of data you want to extract.

**Available Modes:**

- **score_mode** - Finished, Live & Scheduled Matches: Extracts current scores and results based on your date and status filters. This is the equivalent of going to the homepage of Flashscore and getting all the matches listed there.

## `scoreModeOptions` (type: `object`):

Configure parameters specific to the '\[score_mode] Finished, Live & Scheduled Matches' mode.

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

List the sports you want to scrape. Currently, 'Football' and 'Basketball' are supported.

## `matchStatuses` (type: `array`):

Filter by match status. Use 'finished' for completed matches, 'scheduled' for upcoming ones, or 'live' for matches in progress at the time the actor runs. 'live' reflects status at the moment of extraction, not a real-time data stream.

## `leagues` (type: `array`):

Filter results to specific leagues or tournaments. Enter names as they appear on Flashscore (e.g. "LaLiga", "Premier League", "Champions League"). Matching is case-insensitive. Leave empty to return all leagues.

## `dayOffsets` (type: `array`):

Select the specific days you want to scrape relative to today (range: -7 to 7). For example: \[0] for today, \[-1, 0, 1] for yesterday, today, and tomorrow.

## `overallRules` (type: `object`):

Configure general settings, applicable to all modes.

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

Limit the maximum number of results to scrape. Leave blank to scrape all available data points.

## Actor input object example

```json
{
  "mode": "score_mode",
  "sports": [
    "football"
  ],
  "matchStatuses": [
    "all"
  ],
  "leagues": [
    "LaLiga",
    "Premier League"
  ],
  "dayOffsets": [
    "0"
  ]
}
```

# 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": "score_mode",
    "sports": [
        "football"
    ],
    "dayOffsets": [
        "0"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("extractify-labs/flashscore-extractor").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": "score_mode",
    "sports": ["football"],
    "dayOffsets": ["0"],
}

# Run the Actor and wait for it to finish
run = client.actor("extractify-labs/flashscore-extractor").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": "score_mode",
  "sports": [
    "football"
  ],
  "dayOffsets": [
    "0"
  ]
}' |
apify call extractify-labs/flashscore-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,extractify-labs/flashscore-extractor"
        }
    }
}
```

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/r0k1qP8slnHsOPjbj/builds/ndyghfVW61BXQalyp/openapi.json