# FotMob Leagues List Scraper (`incognito_mode/fotmob-leagues-list-scraper`) Actor

Get the full FotMob directory of football leagues and competitions worldwide — popular, international, and every country's domestic leagues — one clean record per league with its FotMob id, name, country and URL. Discover league ids for the FotMob League and Match scrapers. Failures never billed.

- **URL**: https://apify.com/incognito\_mode/fotmob-leagues-list-scraper.md
- **Developed by:** [Elena Vance](https://apify.com/incognito_mode) (community)
- **Categories:** News, Developer tools, Integrations
- **Stats:** 10 total users, 3 monthly users, 91.2% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 league 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 Leagues List Scraper — Every Football League & Competition ID, in One Run

**Turn FotMob's entire competition directory into clean, structured JSON or CSV:
the FotMob `leagueId`, name, localized name, country, category, and the league
page URL — one tidy record per league. Popular leagues, international
tournaments, and every country's domestic divisions, all flattened into a single
dataset.**

This is the **discovery Actor** of the FotMob family. One signed request returns
roughly **550 leagues**, and the `leagueId`s it emits are exactly what you feed
into the **[FotMob League Scraper](https://apify.com/incognito_mode/fotmob-league-scraper)** (for seasons, tables, fixtures) and, through
that, the **[FotMob Match Details Scraper](https://apify.com/incognito_mode/fotmob-match-details-scraper)**. No login, no account, no HTML
wrangling — and **you are never billed for failed requests**.

> **Good to know:** this Actor works **globally** — there is no geo-restriction.
> It runs through **Apify Proxy**, and **datacenter proxy (the default) is
> enough** — just keep the proxy enabled. A full run is one HTTP request, so it
> is fast and cheap.

***

### Why this Actor

- **The whole league map in one call.** A single signed `allLeagues` request to
  FotMob returns every competition it tracks — no pagination, no crawling, no
  per-country fan-out. One run = the complete directory.
- **The seed for the rest of your pipeline.** Each record carries the stable
  `leagueId` that the **FotMob League Scraper** and **FotMob Match Details
  Scraper** take as input. Run this first, then drive everything else off the
  ids it produces.
- **Three buckets, one flat schema.** Popular leagues, international tournaments,
  and per-country domestic leagues are merged into one consistent record shape,
  each tagged with a `category` so you can split them back apart in one filter.
- **Filter to what you need.** Pull everything by default, or restrict to a
  single category, or list FIFA country codes to get only those countries'
  domestic leagues.
- **Ready-to-use links.** Every record includes both the relative `pageUrl` and a
  fully-formed absolute `leagueUrl` (`https://www.fotmob.com/...`) — click
  through or build deep links straight from the dataset.
- **You never pay for failures.** If the directory request fails, it is reported
  in the run summary — **not** written to your dataset and **not billed**.
- **Fast and lightweight.** One request, hundreds of records, minimal compute.
- **Clean, consistent output.** `leagueId` as an integer, ISO 8601 timestamps,
  whitespace-normalized names, JSON-safe values throughout.

***

### Problems this Actor solves

| If you are… | Your problem | How this Actor solves it |
|---|---|---|
| **Building a football-data pipeline** | The other FotMob scrapers need `leagueId`s, and there is no clean master list | Run this first; feed its `leagueId`s into the **FotMob League Scraper** and **Match Details Scraper** |
| **A data analyst / researcher** | You need a complete, normalized reference table of competitions to join against | One dated record per league — export straight to pandas, Sheets, or BI |
| **An app / chatbot / agent developer** | You want a competition picker or autocomplete without maintaining a hardcoded list | Pull the live directory on a schedule; a stable, normalized schema you can rely on |
| **A betting / stats / fantasy project** | Mapping internal competitions to FotMob ids is manual and error-prone | Match on `name` / `ccode` / `countryName` and capture the canonical `leagueId` |
| **A content creator / journalist** | You need the right league URLs and ids fast | Filter by country code or category and copy the ready-made `leagueUrl` |

***

### What data you get

Each league becomes one dataset record:

| Field | Description |
|---|---|
| `leagueId` | FotMob's stable numeric league id (the record's unique id). Integer. |
| `name` | League / competition name (e.g. `Premier League`) |
| `localizedName` | Localized name for the chosen locale; falls back to `name` |
| `category` | `popular`, `international`, or `domestic` — which FotMob bucket the league came from |
| `ccode` | FIFA country code (e.g. `ENG`, `ESP`, `GER`); `INT` for international tournaments. May be `null` |
| `countryName` | Country name for domestic leagues; `null` for popular / international |
| `pageUrl` | Relative FotMob path (e.g. `/leagues/47/overview/premier-league`). May be `null` |
| `leagueUrl` | Absolute FotMob URL built from `pageUrl`. May be `null` |
| `source` | Always `fotmob-leagues-list-scraper` |
| `scrapedAt` | ISO 8601 timestamp of the run |

#### Example output

```json
{
  "leagueId": 47,
  "name": "Premier League",
  "localizedName": "Premier League",
  "category": "popular",
  "ccode": "ENG",
  "countryName": null,
  "pageUrl": "/leagues/47/overview/premier-league",
  "leagueUrl": "https://www.fotmob.com/leagues/47/overview/premier-league",
  "source": "fotmob-leagues-list-scraper",
  "scrapedAt": "2026-06-18T11:08:55+00:00"
}
```

A league can appear in more than one FotMob bucket (e.g. a popular league is also
a domestic one); records are **de-duplicated by `leagueId`**, so you get exactly
one clean record per league. If the directory request cannot be fetched, nothing
is written to the dataset (and nothing is billed) — the failure is listed in the
run's `SUMMARY` record in the key-value store
(`{ "failures": [ { "input": "allLeagues", "error": "…" } ] }`), and the run's
status message tells you at a glance how many leagues were captured.

***

### How to use it (60 seconds)

1. Click **Try for free / Start**.
2. Choose what to return:
   - **Everything (default):** leave **Category** on `All` to get every league
     FotMob tracks.
   - **One bucket:** set **Category** to `Popular leagues`, `International
     tournaments`, or `Domestic (country) leagues`.
   - **Specific countries:** add FIFA codes (e.g. `ENG`, `ESP`, `GER`) under
     **Country codes** to keep only those countries' domestic leagues.
3. Keep the **Apify Proxy** enabled (datacenter is enough — the default).
4. Click **Save & Start**. Download results as **JSON, CSV, Excel, or via API**
   from the **Dataset** tab; check **Key-value store → SUMMARY** for run totals
   and any failures.

***

### Input reference

| Field | Type | Default | Description |
|---|---|---|---|
| **Category** | select | `all` | Which leagues to return: `all`, `popular`, `international`, or `domestic`. |
| **Country codes (optional)** | list | *(empty)* | FIFA country codes (e.g. `ENG`, `ESP`, `GER`). Filters the **domestic** bucket only; empty = all countries. |
| **Locale country (advanced)** | string | `US` | Country code FotMob uses to localize ordering and the `localizedName`. Most users can leave it at `US` (English names). |
| **Proxy configuration** | object | Apify Proxy (datacenter) | Routes the request through Apify Proxy. Datacenter is enough — keep it enabled. |
| **Max items** | integer | `0` | Stop after producing this many records (`0` = the full directory). |

***

### Notes on coverage

One run captures FotMob's complete competition directory — popular leagues,
international tournaments, and every country's domestic divisions — typically
around **550 leagues**, flattened into a single dataset. The exact count tracks
whatever FotMob currently publishes. Leagues without a usable id are skipped, and
duplicates across buckets are merged by `leagueId`. The **Locale country** option
only changes the localized names and ordering; the set of leagues and their ids
is the same worldwide.

***

### Pricing — what a run costs

This Actor uses transparent **pay-per-event** pricing with a built-in **volume
discount**: a small Actor-start fee, a fixed price per successful league record
for the first 10,000 results of a run, and a cheaper rate for every result beyond
that. **No subscription, no minimums, and failed league records are never
charged.** The exact rates are shown on the Actor's **Pricing** tab.

- **Failed requests are free.** A failed directory fetch is reported in the
  summary, never billed.
- **Bigger runs cost less per item.** The discount tier resets per run, so one
  large run is cheaper than the same job split into many small ones.
- **Cheap by design.** A full run is a single HTTP request that yields hundreds
  of records — there is very little to pay for.
- **Try it free:** an Apify free account includes **$5 of monthly platform
  credit** — enough to try the Actor before paying anything.
- **Stay in control:** set **Max items** and Apify's **maximum charge per run**;
  the Actor stops gracefully at your cap, keeping everything already scraped.

***

### Compared to the alternatives

| | **This Actor** | Build your own scraper | Hardcoded league list |
|---|---|---|---|
| Complete, normalized directory | Yes | You maintain it | Goes stale |
| Stable `leagueId` for downstream scrapers | Yes | You map it | Manual lookup |
| Popular + international + domestic in one schema | Yes | You merge it | Partial |
| Filter by category / country code | Yes | You build it | – |
| Ready-made absolute league URLs | Yes | You construct them | – |
| Never billed for failures | Yes | – | – |
| Export JSON / CSV / Excel / API | Yes, built-in | DIY | Copy-paste |
| Setup time | ~60 seconds | Days; breaks on site changes | Hours, and out of date |

***

### The FotMob Actor family

This is the discovery Actor that produces the league ids the others consume:

- **FotMob Leagues List Scraper** (this Actor) — the full directory of leagues
  and their `leagueId`s.
- **[FotMob League Scraper](https://apify.com/incognito_mode/fotmob-league-scraper)** — takes a `leagueId` and returns a league's seasons,
  standings/tables, and fixtures.
- **[FotMob Matches Scraper](https://apify.com/incognito_mode/fotmob-matches-scraper)** — discovers matches (by date or league).
- **[FotMob Match Details Scraper](https://apify.com/incognito_mode/fotmob-match-details-scraper)** — takes a match id and returns deep
  per-match data.

Typical flow: run this Actor to get `leagueId`s → feed them into the **FotMob
League Scraper** → take the match ids from there into the **FotMob Match Details
Scraper**.

***

### Integrate the data

- **Exports:** JSON, CSV, Excel, XML from the Dataset tab — or fetch
  programmatically:
  ```
  GET https://api.apify.com/v2/datasets/{datasetId}/items?format=json
  ```
- **Run on a schedule:** use Apify **Schedules** to refresh the directory weekly
  or monthly, and **webhooks** to push finished runs into your pipeline (Sheets,
  Slack, your backend).
- **From code:** call the Actor with the [Apify API or SDKs](https://docs.apify.com/api)
  (Python / JavaScript) and read the dataset when the run finishes.
- **Chain it:** pipe the `leagueId`s straight into the **FotMob League Scraper**
  to build a full football-data pipeline.
- **Run summary:** every run writes a `SUMMARY` record (key-value store) with
  totals, successes, failures, and billing counts — ideal for monitoring
  automated pipelines.

***

### FAQ

**Do I need a FotMob account or login?**
No. There is no account or login required.

**Is it geo-restricted?**
No — this Actor works globally. It runs through Apify Proxy, and datacenter proxy
(the default) is enough; just keep the proxy enabled.

**What is `leagueId` for?**
It is FotMob's stable numeric id for a competition, and the key input to the
**FotMob League Scraper** and **FotMob Match Details Scraper**. Run this Actor
first to discover the ids you need.

**Why is `countryName` sometimes `null`?**
`countryName` is only set for **domestic** leagues. Popular leagues and
international tournaments return `null` for it (use `ccode`, which is `INT` for
international tournaments).

**How do I get only one country's leagues?**
Leave **Category** on `all` or set it to `domestic`, then add the FIFA code(s)
(e.g. `ESP`) under **Country codes**.

**How many leagues will I get?**
Roughly 550 in a full run, matching whatever FotMob currently publishes.

**How fresh is the data?**
Each run fetches the live directory, so you get exactly what FotMob lists at that
moment. Schedule the Actor to keep your reference table current.

**What formats can I export?**
JSON, CSV, Excel, XML — from the Console or via the Apify API.

***

### Disclaimer

This Actor is intended for personal and research use. You are responsible for
ensuring your use complies with FotMob's terms and applicable law. Please scrape
responsibly. This project is **not affiliated with, endorsed by, or sponsored by
FotMob**.

# Actor input Schema

## `category` (type: `string`):

Which leagues to return: all, only popular leagues, only international tournaments, or only domestic (country) leagues.

## `countryCodes` (type: `array`):

Filter domestic leagues to these FIFA country codes (e.g. "ENG", "ESP", "GER"). Leave empty for all countries. Only applies to the domestic category.

## `localeCountry` (type: `string`):

Country code used by FotMob to localize ordering and names. Defaults to US (English names). Most users can leave this blank.

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

Apify Proxy routes the request. Datacenter proxy (the default) is enough for this Actor.

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

Stop after producing this many league records. Set to 0 for no limit (the full directory).

## Actor input object example

```json
{
  "category": "all",
  "countryCodes": [
    "ENG",
    "ESP",
    "GER"
  ],
  "localeCountry": "US",
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "maxItems": 0
}
```

# Actor output Schema

## `leagues` (type: `string`):

All scraped league records (one item per league).

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

JSON summary of the run: totals, successes, failures, and billing counts.

# 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 = {
    "countryCodes": [],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("incognito_mode/fotmob-leagues-list-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 = {
    "countryCodes": [],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("incognito_mode/fotmob-leagues-list-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 '{
  "countryCodes": [],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call incognito_mode/fotmob-leagues-list-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,incognito_mode/fotmob-leagues-list-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/Bn5rORiX6bcxpPUr1/builds/dNc51aeOZjPElzxEM/openapi.json