# FotMob Football Data Scraper (`fetchfinch/fotmob-data-scraper`) Actor

Fetch FotMob match schedules, live scores, results, league catalogs, standings, historical seasons, fixtures, and top players from public JSON endpoints. Outputs clean match, league, and league-season dataset records.

- **URL**: https://apify.com/fetchfinch/fotmob-data-scraper.md
- **Developed by:** [Fetch Finch](https://apify.com/fetchfinch) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.50 / 1,000 match results

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

## FotMob Football Data Scraper

Extract live and historical football data from FotMob into clean, structured Apify datasets. The Actor supports worldwide matches, league discovery, standings, fixtures, results, seasons, top players, and optional statistics.

No FotMob login or API key is required. The Actor reads FotMob's public JSON endpoints and returns normalized records that are ready for JSON, CSV, Excel, API, and downstream data workflows.

### What you can collect

- **Matches**: one record per fixture, live match, postponed match, or finished result, including teams, scores, kickoff times, status, league context, tournament stage, and a FotMob match URL.
- **Leagues**: the worldwide FotMob league and competition catalog with league IDs, names, localized names, country codes, categories, and URLs.
- **League seasons**: one record per league-season with standings, fixtures, results, match IDs, available seasons, top players, and optional player and team statistics.
- **Matches and leagues**: combine match records and league records in one dataset. Each record includes a `recordType` field.

### Quick start

Choose an operation and start the Actor. The default operation fetches today's matches using the International locale.

#### Worldwide matches

```json
{
  "operation": "matches",
  "matchStatus": "all",
  "timezone": "UTC",
  "countryCode": "INT"
}
```

#### A date range

```json
{
  "operation": "matches",
  "startDate": "2026-08-29",
  "endDate": "2026-09-04",
  "timezone": "Europe/London",
  "matchStatus": "all"
}
```

#### League catalog

```json
{
  "operation": "leagues",
  "countryCode": "INT",
  "locale": "en",
  "maxItems": 0
}
```

Set `leagueCountryCodes` to filter catalog or match records, for example `["ENG"]` or `["ENG", "ESP"]`.

#### League season data

```json
{
  "operation": "leagueSeasons",
  "leagueIds": ["47"],
  "seasons": ["2025/2026"],
  "includeStandings": true,
  "includeFixtures": true,
  "includeTopPlayers": true,
  "includeStats": true
}
```

Use `leagueIds` from the league catalog. If `seasons` is empty, the Actor fetches the most recent seasons according to `maxSeasons`.

### Public example Tasks

Run a preconfigured example, review the input, and start it directly from Apify:

- [Global matches today](https://console.apify.com/create-task-from-example/nw3TPuivXgy83K0Q9)
- [Upcoming matches today](https://console.apify.com/create-task-from-example/7YS5aMR8nOQ1rcb31)
- [England matches today](https://console.apify.com/create-task-from-example/H0HXiLdYG9VBPawQu)
- [Full worldwide league catalog](https://console.apify.com/create-task-from-example/xegbn4saQudChL7Iq)
- [England league catalog](https://console.apify.com/create-task-from-example/1SeU8K5U0UJVSCYdT)
- [Premier League current season](https://console.apify.com/create-task-from-example/FZMiVsfMo12etPqYp)
- [Premier League historical season](https://console.apify.com/create-task-from-example/xnoKcLAxRLk1UrIUc)
- [English Championship current season](https://console.apify.com/create-task-from-example/hP9WdS0c1XYJYff7p)

### Input reference

| Input | Description |
| --- | --- |
| `operation` | `matches`, `leagues`, `leagueSeasons`, or `both` |
| `startDate`, `endDate` | Match dates in `YYYY-MM-DD` format. The end date is inclusive. |
| `timezone` | IANA timezone used for date grouping and local kickoff times. |
| `countryCode` | Three-letter FotMob country or region code used for localization. The default is `INT` for International. |
| `locale` | Locale sent to the league catalog endpoint, such as `en`. |
| `leagueIds` | FotMob league IDs to select or scrape. |
| `leagueCountryCodes` | Country codes used to filter match or league records. |
| `seasons` | Exact seasons such as `2025/2026`. |
| `maxSeasons` | Number of recent seasons to fetch when exact seasons are not supplied. |
| `matchStatus` | `all`, `live`, `upcoming`, `finished`, or `cancelled`. |
| `includeStandings` | Include the season table. |
| `includeFixtures` | Include every fixture and result plus a flat `matchIds` list. |
| `includeTopPlayers` | Include top players by rating, goals, and assists. |
| `includeStats` | Include FotMob player and team statistic categories. |
| `maxItems` | Maximum number of output records. Use `0` for the complete result. |
| `includeRaw` | Add the original FotMob object under `rawData`. |

Advanced options are available for request delay, retries, date range size, and Apify Proxy configuration.

### Output

The default dataset contains one normalized record per match, league, or league-season.

#### Match records

Match records can include:

- `matchId` and `matchUrl`
- `homeTeam` and `awayTeam` objects with IDs and names
- scores, status, kickoff time, local time, and Unix timestamp
- `leagueId`, `leagueName`, `leagueCountryCode`, and tournament stage
- query date, timezone, source URL, and scrape timestamp

#### League records

League records can include:

- `leagueId`, `name`, and `localizedName`
- `countryCode` and `countryName`
- catalog `sections`
- `pageUrl` and a ready-to-use `leagueUrl`
- source URL and scrape timestamp

#### League-season records

League-season records can include:

- league name, short name, color, URL, and selected season
- available seasons and current-season information
- standings with team data and table statistics
- fixtures and results with match IDs
- top players by rating, goals, and assists
- optional player and team statistic categories

Every record includes `recordType`, `scrapedAt`, and `sourceUrl`. The run summary is stored in the default key-value store under `RUN_SUMMARY`.

### Pricing

The Actor uses pay-per-event pricing:

- $0.0025 per match record
- $0.0015 per league record
- $0.008 per league-season record
- $0.00005 per Actor start

Bulk rates apply after 10,000 records in one run. Failed requests are not charged, and Apify's maximum charge setting can be used to control the budget for a run.

### Integrate the data

Results can be exported from Apify as JSON, CSV, Excel, or through the Dataset API. The Actor can also be called from the Apify API, JavaScript, Python, Make, Zapier, n8n, or a scheduled workflow.

Typical football-data workflow:

1. Run the full league catalog to discover FotMob league IDs.
2. Pass selected league IDs to `leagueSeasons` for standings, fixtures, results, and player data.
3. Use the match IDs from the output in a match-details workflow if deeper per-match data is needed.

### Disclaimer

This Actor is not affiliated with, endorsed by, or sponsored by FotMob. Use the data responsibly and ensure that your use complies with FotMob's terms and applicable law.

# Actor input Schema

## `operation` (type: `string`):

Matches are returned as one row per match. Leagues are returned as one row per league. League seasons include standings, fixtures, results, top players, and available seasons. Both combines matches and the league catalog.

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

First date to fetch in the selected timezone. Defaults to today.

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

Last date to fetch, inclusive. Leave empty to fetch only Start date.

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

IANA timezone used by FotMob for the match date and local kickoff time.

## `countryCode` (type: `string`):

Three-letter country or region code sent as FotMob's ccode3/country parameter. It controls localization; use League country codes to filter results.

## `locale` (type: `string`):

Locale sent to the league catalog endpoint.

## `includeNextDayLateNight` (type: `boolean`):

Include matches that FotMob groups with the selected date even when they start after midnight local time.

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

For Matches/Leagues: optional IDs to keep. For League seasons: IDs to scrape; if empty, Premier League (47) is used.

## `seasons` (type: `array`):

League seasons to fetch, for example \["2025/2026"]. Leave empty to fetch the most recent seasons.

## `maxSeasons` (type: `integer`):

Used when Seasons is empty. Fetches the most recent N seasons, up to 10.

## `includeStandings` (type: `boolean`):

Include the season table.

## `includeFixtures` (type: `boolean`):

Include every fixture/result and a flat matchIds list.

## `includeTopPlayers` (type: `boolean`):

Include FotMob's top players by rating, goals, and assists.

## `includeStats` (type: `boolean`):

Include FotMob's player/team stat categories and top-three entries. This can increase record size.

## `leagueCountryCodes` (type: `array`):

Optional output filter, for example \["ENG"] or \["ENG", "ESP"].

## `matchStatus` (type: `string`):

Filter match rows after fetching.

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

Maximum rows written across the entire run. Set to 0 for unlimited.

## `maxDays` (type: `integer`):

Safety limit for multi-day match runs.

## `includeRaw` (type: `boolean`):

Add the original FotMob match or league object under rawData. This increases dataset size.

## `requestDelayMs` (type: `integer`):

Politeness delay before each FotMob request.

## `maxRetries` (type: `integer`):

Retries for temporary network errors, HTTP 429, and HTTP 5xx responses.

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

Optional Apify Proxy configuration. Direct requests work for normal runs; a proxy can help with larger jobs.

## Actor input object example

```json
{
  "operation": "matches",
  "timezone": "Europe/Prague",
  "countryCode": "INT",
  "locale": "en",
  "includeNextDayLateNight": true,
  "maxSeasons": 1,
  "includeStandings": true,
  "includeFixtures": true,
  "includeTopPlayers": true,
  "includeStats": false,
  "matchStatus": "all",
  "maxItems": 0,
  "maxDays": 31,
  "includeRaw": false,
  "requestDelayMs": 250,
  "maxRetries": 3
}
```

# Actor output Schema

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

One record per match or league, depending on the selected operation.

## `summary` (type: `string`):

Request counts, output counts, date range, and errors.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("fetchfinch/fotmob-data-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("fetchfinch/fotmob-data-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 '{}' |
apify call fetchfinch/fotmob-data-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fetchfinch/fotmob-data-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/t6SaHqXT59pHn22Ls/builds/quBiQ95KP4kX5Hca3/openapi.json