# Football Fixtures, Results & League Tables — Open Data (`boliveira/football-open-data`) Actor

Fixtures, results and league tables for 25 football competitions (Premier League, La Liga, Bundesliga, Serie A, Ligue 1, Brasileirão, Champions League, Peru Liga 1 and more) from open-licensed sources. Seasons back to 2010, one clean schema, no proxies.

- **URL**: https://apify.com/boliveira/football-open-data.md
- **Developed by:** [Bruno Scherer Oliveira](https://apify.com/boliveira) (community)
- **Categories:** Sports, Open source
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.35 / 1,000 row returneds

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

## Football Fixtures, Results & League Tables — Open Data

Get fixtures, results and league tables for **25 football competitions** in one clean schema: Premier League, La Liga, Bundesliga, Serie A, Ligue 1, Eredivisie, Primeira Liga, Brasileirão, Champions League, Peru Liga 1 and more. Seasons go back to **2010/11** for the big leagues.

All data comes from **open-licensed sources**, so you can use the output in your own products: no proxies, no browser and no scraping of sites that forbid it.

### What you get

Each dataset row is either a **match** or a **standing** (`type` field).

**Match**

| Field | Example |
|---|---|
| `competition`, `competitionName`, `country` | `en.1`, `Premier League`, `England` |
| `season` | `2024/25` (or `2026` for calendar-year leagues) |
| `round`, `roundNumber` | `Matchday 1`, `1` |
| `date`, `kickoffUtc` / `kickoffLocal` | `2024-08-16`, `20:00` |
| `homeTeam`, `awayTeam` | `Manchester United FC`, `Fulham FC` |
| `homeGoals`, `awayGoals`, `halftimeHome`, `halftimeAway` | `1`, `0`, `0`, `0` |
| `status` | `finished`, `scheduled` or `result_pending` |
| `goals` (optional) | minute, scorer, penalty / own goal (German competitions and Champions League) |

**Standing**

| Field | Example |
|---|---|
| `table` | `overall` (Peru: `apertura`, `clausura`, `acumulada`) |
| `position`, `team` | `1`, `Liverpool FC` |
| `played`, `won`, `drawn`, `lost` | `38`, `25`, `9`, `4` |
| `goalsFor`, `goalsAgainst`, `goalDifference`, `points` | `86`, `41`, `45`, `84` |
| `computed` | `true` when the table is calculated from match results |
| `notes` | official remarks such as point deductions (Peru) |

Every row also carries `source`, `sourceUrl`, `license` and `scrapedAt`.

### Competitions

| Id | Competition | Source | Seasons |
|---|---|---|---|
| `de.1`, `de.2`, `de.3` | Bundesliga, 2. Bundesliga, 3. Liga | OpenLigaDB | many, incl. current |
| `de.cup` | DFB-Pokal (matches) | OpenLigaDB | many, incl. current |
| `uefa.cl` | Champions League (matches) | OpenLigaDB | many, incl. current |
| `en.1` – `en.4` | Premier League, Championship, League One, League Two | openfootball | 2010/11 → |
| `es.1`, `es.2` | La Liga, Segunda | openfootball | 2012/13 → |
| `it.1`, `it.2` | Serie A, Serie B | openfootball | 2013/14 → |
| `fr.1`, `fr.2` | Ligue 1, Ligue 2 | openfootball | 2014/15 → |
| `at.1`, `at.2` | Austrian Bundesliga, 2. Liga | openfootball | 2010/11 → |
| `nl.1`, `pt.1`, `be.1`, `sco.1`, `tr.1`, `gr.1` | Eredivisie, Primeira Liga, Pro League, Premiership, Süper Lig, Super League | openfootball | 2018/19 → |
| `br.1` | Brasileirão Série A | openfootball | 2019 → (some years missing) |
| `pe.1` | Peru Liga 1 (standings only) | liga1.pe | current season |

### Input

- **Competitions**: one or more ids from the table above.
- **Seasons**: start years, e.g. `2024` for 2024/25. Leave empty for the current season. If a league's current season isn't published yet, you get the latest one and a warning.
- **What to return**: matches, standings, or both.
- **Finished matches only**, **Team filter** (e.g. `arsenal`) and **Include goal events**.

Example:

```json
{
  "competitions": ["en.1", "es.1", "pe.1"],
  "seasons": ["2024", "2025"],
  "include": "both",
  "onlyFinished": true
}
```

### Good to know

- **Freshness.** OpenLigaDB (German competitions, Champions League) is updated by its community on matchday. openfootball (the other European leagues and Brazil) is maintained by volunteers and **can lag a few weeks** in the current season. Past matches it hasn't filled in yet are marked `result_pending` rather than guessed. It is best for history and season-level analysis, not live scores.
- **Computed tables** (openfootball leagues) use 3/1/0 points and rank by points, goal difference, then goals scored. Point deductions and head-to-head tie-breakers are not applied. OpenLigaDB and Peru tables come straight from the source.
- **Peru** standings are fetched from the league's own site at most once every 30 seconds, as its robots.txt asks.
- A run requesting a season that a source doesn't have finishes normally and lists it in `RUN_SUMMARY`. You aren't charged for it.

### Pricing

You pay per dataset row (match or standing). A full Premier League season with its table is 400 rows.

### Licences and attribution

- **OpenLigaDB** data is under the [Open Database License (ODbL) 1.0](https://opendatacommons.org/licenses/odbl/1-0/), © OpenLigaDB contributors ([openligadb.de](https://www.openligadb.de)). If you publish a database built from it, credit OpenLigaDB and share that database under the ODbL. OpenLigaDB runs on donations; consider supporting it.
- **openfootball** data ([openfootball/football.json](https://github.com/openfootball/football.json)) is public domain (CC0 1.0).
- **Peru Liga 1** standings are published by the Liga de Fútbol Profesional at [liga1.pe](https://liga1.pe/tabla-de-posiciones/).

This Actor is not affiliated with any league, club or data provider.

# Actor input Schema

## `competitions` (type: `array`):

Competitions to fetch.

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

Season start years, e.g. 2025 for 2025/26 (or 2025 for calendar-year leagues like Brazil and Peru). Leave empty for the current season. openfootball seasons go back to 2010/11; Peru only has the current season.

## `include` (type: `string`):

Matches (fixtures and results), standings (league tables), or both.

## `onlyFinished` (type: `boolean`):

Drop fixtures that have not been played yet.

## `team` (type: `string`):

Only return rows that mention this team (case-insensitive substring, e.g. 'arsenal').

## `includeGoals` (type: `boolean`):

Add goal minute and scorer to each match (OpenLigaDB competitions only: German leagues, DFB-Pokal, Champions League).

## Actor input object example

```json
{
  "competitions": [
    "en.1"
  ],
  "seasons": [],
  "include": "both",
  "onlyFinished": false,
  "includeGoals": false
}
```

# Actor output Schema

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

Dataset with match and standing rows (field type = match | standing).

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

RUN_SUMMARY record: rows per competition and season, failures and skipped requests.

# 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 = {
    "competitions": [
        "en.1"
    ],
    "seasons": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("boliveira/football-open-data").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 = {
    "competitions": ["en.1"],
    "seasons": [],
}

# Run the Actor and wait for it to finish
run = client.actor("boliveira/football-open-data").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 '{
  "competitions": [
    "en.1"
  ],
  "seasons": []
}' |
apify call boliveira/football-open-data --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,boliveira/football-open-data"
        }
    }
}
```

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/ddEAaf3IznVtylzCp/builds/2hRxlt7KefeVYiUav/openapi.json