# OpenLigaDB Football Stats Scraper (`crawlerbros/openligadb-football-stats-scraper`) Actor Scrape OpenLigaDB (openligadb.de) - a free, open football statistics API. Get match results, league tables, teams, and matchday data for Bundesliga, DFB Pokal, UEFA Euro 2024, Champions League, and more. - **URL**: https://apify.com/crawlerbros/openligadb-football-stats-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Integrations - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ## OpenLigaDB Football Stats Scraper Scrape **[OpenLigaDB](https://openligadb.de)** — a free, open-source football statistics API covering Bundesliga, DFB Pokal, UEFA Euro 2024, Champions League, and many other competitions. Get match results, league standings, team lists, and matchday data — completely free, no API key required. ### What You Can Scrape | Mode | Data | |------|------| | `getMatches` | All match results for a league/season (with goal scorers) | | `getTable` | League standings (points, wins, draws, losses, goal difference) | | `getTeams` | List all teams in a league/season | | `getMatchday` | Results for a specific matchday | | `listLeagues` | Full list of all available leagues and seasons | ### Supported Leagues | Code | League | |------|--------| | `bl1` | 1. Bundesliga (Germany) | | `bl2` | 2. Bundesliga (Germany) | | `bl3` | 3. Liga (Germany) | | `dfb` | DFB Pokal | | `em2024` | UEFA Euro 2024 | | `ucl2023` | UEFA Champions League 2023/24 | ### Input Parameters | Field | Type | Default | Description | |-------|------|---------|-------------| | `mode` | select | `getMatches` | What data to retrieve | | `league` | select | `bl1` | League shortcut | | `season` | integer | `2024` | Season start year (2002–2025) | | `matchday` | integer | — | Specific matchday (1–50), required for `getMatchday` mode | | `maxItems` | integer | `100` | Maximum records to return (1–500) | ### Output Fields #### Match Results (getMatches / getMatchday) | Field | Description | |-------|-------------| | `matchId` | Unique match identifier | | `homeTeam` | Home team name | | `guestTeam` | Guest (away) team name | | `homeGoals` | Home team goals scored | | `guestGoals` | Guest team goals scored | | `matchDateTime` | Match date/time in UTC (ISO 8601) | | `groupName` | Matchday name (e.g. "1. Spieltag") | | `leagueShortcut` | League shortcut code (e.g. "bl1") | | `leagueSeason` | Season year | | `isFinished` | Whether the match is complete | | `lastUpdateDateTime` | Last data update timestamp | | `goals` | List of goal scorer details | | `scrapedAt` | Timestamp of scraping | #### League Table (getTable) | Field | Description | |-------|-------------| | `teamName` | Team name | | `teamShortName` | Team abbreviation | | `teamIconUrl` | Team crest image URL | | `teamId` | OpenLigaDB team identifier | | `points` | Total points | | `won` | Matches won | | `draw` | Matches drawn | | `lost` | Matches lost | | `goals` | Goals scored | | `opponentGoals` | Goals conceded | | `goalDiff` | Goal difference | | `matches` | Total matches played | #### Teams (getTeams) | Field | Description | |-------|-------------| | `teamId` | OpenLigaDB team identifier | | `teamName` | Full team name | | `shortName` | Team abbreviation | | `teamIconUrl` | Team crest image URL | ### Example Configurations **Get Bundesliga 2024/25 match results:** ```json { "mode": "getMatches", "league": "bl1", "season": 2024, "maxItems": 100 } ```` **Get Bundesliga standings table:** ```json { "mode": "getTable", "league": "bl1", "season": 2024 } ``` **Get specific matchday results:** ```json { "mode": "getMatchday", "league": "bl1", "season": 2024, "matchday": 5 } ``` **Get all teams in Euro 2024:** ```json { "mode": "getTeams", "league": "em2024", "season": 2024 } ``` **List all available leagues:** ```json { "mode": "listLeagues", "maxItems": 200 } ``` ### Common Use Cases - **Sports analytics** — collect match results for statistical analysis - **Fan dashboards** — build live standing tables and match trackers - **Betting research** — get historical results and goal data - **Football data pipelines** — integrate Bundesliga data into data warehouses - **Research projects** — analyze team performance across seasons ### FAQs **Q: Is this free to use?** A: Yes. OpenLigaDB is a community-maintained open-source sports data platform. The API is completely free with no key required. **Q: What seasons are available?** A: Bundesliga data goes back to 2002. Other leagues vary — use `listLeagues` mode to see all available seasons. **Q: How current is the match data?** A: Match results are typically updated within hours of completion. Live scores are not supported. **Q: What does "season" mean for a German football league?** A: Use the start year of the season. For example, for the 2024/25 Bundesliga season, use `season: 2024`. **Q: What is the `goals` field?** A: Each entry in the goals array contains `scorer` (player name), `minute` (goal minute), `scoreAfter` (score at that point), and optionally `isPenalty` or `isOwnGoal`. **Q: Is there a cost to use this scraper?** A: This scraper uses only standard Apify datacenter resources. No proxy or API credentials are needed. Apify free plan is sufficient. # Actor input Schema ## `mode` (type: `string`): What data to retrieve from OpenLigaDB. ## `league` (type: `string`): League shortcut. Use 'listLeagues' mode to see all available options. ## `season` (type: `integer`): Season start year (e.g. 2024 for the 2024/2025 season). ## `matchday` (type: `integer`): Specific matchday number to fetch (1-50). Required for mode=getMatchday. ## `maxItems` (type: `integer`): Maximum number of records to return (1–500). ## Actor input object example ```json { "mode": "getMatches", "league": "bl1", "season": 2024, "maxItems": 50 } ``` # Actor output Schema ## `football` (type: `string`): Dataset containing all scraped football records. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "getMatches", "league": "bl1", "season": 2024, "maxItems": 50 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/openligadb-football-stats-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "getMatches", "league": "bl1", "season": 2024, "maxItems": 50, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/openligadb-football-stats-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).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": "getMatches", "league": "bl1", "season": 2024, "maxItems": 50 }' | apify call crawlerbros/openligadb-football-stats-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/openligadb-football-stats-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "OpenLigaDB Football Stats Scraper", "description": "Scrape OpenLigaDB (openligadb.de) - a free, open football statistics API. Get match results, league tables, teams, and matchday data for Bundesliga, DFB Pokal, UEFA Euro 2024, Champions League, and more.", "version": "1.0", "x-build-id": "hJI2XGDdWXDPCDNsp" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~openligadb-football-stats-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-openligadb-football-stats-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~openligadb-football-stats-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-openligadb-football-stats-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~openligadb-football-stats-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-openligadb-football-stats-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "getMatches", "getTable", "getTeams", "getMatchday", "listLeagues" ], "type": "string", "description": "What data to retrieve from OpenLigaDB.", "default": "getMatches" }, "league": { "title": "League", "enum": [ "bl1", "bl2", "bl3", "dfb", "em2024", "ucl2023" ], "type": "string", "description": "League shortcut. Use 'listLeagues' mode to see all available options.", "default": "bl1" }, "season": { "title": "Season Year", "minimum": 2002, "maximum": 2025, "type": "integer", "description": "Season start year (e.g. 2024 for the 2024/2025 season).", "default": 2024 }, "matchday": { "title": "Matchday", "minimum": 1, "maximum": 50, "type": "integer", "description": "Specific matchday number to fetch (1-50). Required for mode=getMatchday." }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of records to return (1–500).", "default": 100 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```