# Football API Scraper — Fixtures, Standings & Match Data (`sian.agency/football-api-scraper`) Actor

Football API scraper for fixtures, results, live scores, league standings, squads, transfers, match lineups, per-player ratings, xG statistics and betting odds. 18 operations across leagues, teams, players and matches, one clean JSON dataset per run.

- **URL**: https://apify.com/sian.agency/football-api-scraper.md
- **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community)
- **Categories:** Sports, Developer tools, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 match extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
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 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

## Football API Scraper — Fixtures, Standings, Lineups & Match Stats ⚽

[![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![Instagram AI Transcript Extractor](https://img.shields.io/badge/Store-Instagram%20AI%20Transcript-E4405F)](https://apify.com/sian.agency/instagram-ai-transcript-extractor?fpr=sian) [![Xiaohongshu RedNote Scraper](https://img.shields.io/badge/Store-Xiaohongshu%20RedNote-FF2442)](https://apify.com/sian.agency/xiaohongshu-rednote-scraper?fpr=sian) [![TikTok AI Transcript Extractor](https://img.shields.io/badge/Store-TikTok%20AI%20Transcript-25F4EE)](https://apify.com/sian.agency/best-tiktok-ai-transcript-extractor?fpr=sian)

#### 🎉 18 football operations in one actor — from a league table to a per-player match rating, no API key of your own

##### Built for fantasy platforms, betting models, live score widgets, club analytics and AI agents

***

### 🔎 What is the Football API Scraper — and when should you use it?

The **Football API Scraper** turns football competitions, clubs, players and matches into clean, structured rows you can filter, export and feed straight into a spreadsheet, database or AI agent. No football data account, no portal API key, no browser automation to maintain — just pick an operation and run.

**Use it when you need:** fixtures and results with scores and kick-off times, league tables including home-only and away-only splits, season team statistics (expected goals, expected assists, possession, clean sheets, goals prevented), squads with market values and contract-end dates, transfers in and out with fees, confirmed lineups with formations and per-player match ratings, goals/cards/substitutions minute by minute, match statistics split by half, pre-match odds across 18 markets, or every football match in play right now.

**Use something else when:** you need a sport other than football. Use [Sports Data Scraper](https://apify.com/sian.agency/sports-data-scraper?fpr=sian) for 30+ sports, or [Basketball API Scraper](https://apify.com/sian.agency/basketball-api-scraper?fpr=sian) for basketball box scores and standings. If you only want bookmaker lines and price movement across many sports, use [Sports Betting Odds Scraper](https://apify.com/sian.agency/sports-betting-odds-scraper?fpr=sian). This actor covers association football (soccer) only, not American football, basketball or tennis.

***

### 🤖 Use with AI agents

Already connected to the [Apify MCP server](https://mcp.apify.com)? Just ask for this Actor by name: sian.agency/football-api-scraper

**Your agent can pay for its own runs.** This Actor is eligible for [agentic payments](https://docs.apify.com/platform/actors/publishing/monetize), so an agent can discover it, run it and settle the bill over [x402](https://www.x402.org/) (USDC on Base) or [Skyfire](https://www.skyfire.xyz/) — without an Apify account or API token of its own. Billing is the same either way: per successful row, never for errors.

Otherwise copy this prompt into Claude, ChatGPT, Cursor or any MCP-enabled assistant:

```text
I want to pull structured football data using the Apify Actor `sian.agency/football-api-scraper`.

Use it when I need: fixtures and results, league tables (including home-only and away-only splits),
season team statistics, squads with market values and contract dates, transfers with fees, match
lineups with per-player ratings, goals and cards, per-half match statistics, pre-match odds, or the
list of football matches currently in play.

Don't use it when: I need a sport other than football — use `sian.agency/sports-data-scraper` for 30+ sports or `sian.agency/basketball-api-scraper` for basketball; for bookmaker lines across many sports use `sian.agency/sports-betting-odds-scraper`.

How to call it: set `operation` to one of
  leagueSearch      -> needs `query` (a competition name), returns Competition IDs
  leagueSeasons     -> needs `tournamentId`, returns Season IDs
  leagueFixtures    -> needs `tournamentId` + `seasonId` (+ `span`: "last" or "next"), 30 matches per page
  leagueStandings   -> needs `tournamentId` + `seasonId` (+ `standingsType`: "total", "home" or "away")
  leagueTopTeams    -> needs `tournamentId` + `seasonId`, one row per club with 32 season metrics
  teamFixtures      -> needs `teamId` (+ `span`)
  teamSquad         -> needs `teamId`
  teamTransfers     -> needs `teamId`
  teamProfile       -> needs `teamId`
  teamSeasonStats   -> needs `teamId` + `tournamentId` + `seasonId`
  playerProfile     -> needs `playerId`
  matchDetails / matchLineups / matchIncidents / matchStatistics / matchOdds / matchBestPlayers
                    -> each needs `matchId`
  liveMatches       -> needs nothing

Start with this input:
{
  "operation": "leagueStandings",
  "tournamentId": 17,
  "seasonId": 76986,
  "standingsType": "total"
}

Ask me which competition and season I care about, look the IDs up with leagueSearch and
leagueSeasons if I don't know them, then run the Actor and summarise the results as a table.
```

**Things you can ask your agent for:**

- *"Build me the Premier League table for last season, then pull the away-only table and tell me which three clubs travel best."*
- *"Get Manchester City's squad with market values and contract end dates, and flag every player whose contract expires within 12 months."*
- *"Take this match ID, pull the lineups and the per-half statistics, and write me a 200-word match report."*

Machine-readable API, MCP config and OpenAPI definition for this Actor are published at [apify.com/sian.agency/football-api-scraper.md](https://apify.com/sian.agency/football-api-scraper.md).

***

### 📋 Overview

Live scores are one operation out of 18. The same `operation` switch also returns competitions, seasons, league tables, clubs, squads, transfers, players, lineups, incidents, match statistics and odds, all on one row contract.

**What you get:**

- ✅ **18 operations, one dataset schema**: fixtures, results, standings, season stats, squads, transfers, profiles, lineups, incidents, match statistics, odds, best players and live matches — no stitching four actors together.
- ⚡ **Home and away league tables**: the same table computed from home fixtures only and away fixtures only, which is the split form and prediction models need.
- 🎯 **Up to 32 season metrics per club**: big chances, ball possession, clean sheets, accurate passes, sprints, kilometres covered, tackles, interceptions — plus expected goals, expected assists and goals prevented wherever the competition publishes them. One clean row per team.
- 💎 **Per-player match ratings**: confirmed lineups with formation, bench, missing players, and each player's rating, expected assists, touches, duels and minutes played.
- 💰 **Charged per successful row, never for errors**: validation runs before any charge, and a row cap you set means you are never billed past your own limit.
- ✨ **Contract and market-value data**: squads carry contract-until dates and market values; transfers carry fees, fee descriptions and dates.

***

### ✨ Features

- ⚽ **League fixtures & results**: 30 matches per page with scores, half-time scores, round, venue, kick-off time and status.
- 🏆 **League standings**: full table plus home-only and away-only splits, with qualification and relegation notes.
- 📊 **Season team statistics**: up to 32 metrics per club across a whole season, each with the club's rank.
- 🔍 **Competition search**: find any league, cup or international tournament by name and get its ID.
- 🗓️ **Season index**: every season ID a competition has ever had, newest first.
- 🏟️ **Team fixtures**: a club's full results and upcoming schedule across all competitions.
- 👥 **Team squad**: every player with position, shirt number, nationality, height, preferred foot, market value and contract end date.
- 🔁 **Team transfers**: arrivals and departures with fee, fee description, both clubs and the transfer date.
- 🛡️ **Team profile**: manager, stadium, capacity, founding year, current position and rolling form.
- 📋 **Match lineups**: starting XI, bench, formation, unavailable players and ~28 per-player match metrics.
- 🟨 **Match incidents**: goals with assists, yellow and red cards with reasons, substitutions, added time — minute by minute.
- 📉 **Match statistics**: 46 metrics split by full match, first half and second half.
- 💰 **Match odds**: 18 pre-match markets including 1X2, double chance, both teams to score, Asian handicap, match goals, cards and corners.
- ⭐ **Match best players**: the man-of-the-match pick per side plus a full rating leaderboard.
- 🔴 **Live matches**: every football match in play right now, in the same row shape as fixtures.
- 🧾 **HTML run report**: saved to the key-value store on every run, even if the run fails.

***

### 🎬 Quick Start

Pick an operation, give it the IDs it needs, run. If you do not know the IDs, run `leagueSearch` first to get a Competition ID, then `leagueSeasons` to get a Season ID — every fixture and standings row then hands you Team IDs and Match IDs for the deeper operations.

```bash
curl -X POST 'https://api.apify.com/v2/acts/sian.agency~football-api-scraper/runs?token=YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"operation": "leagueStandings", "tournamentId": 17, "seasonId": 76986, "standingsType": "total"}'
```

***

### 🚀 Getting Started (3 Simple Steps)

#### Step 1: Find your competition

Run `leagueSearch` with a name like "Premier League", "Champions League" or "Serie A". Each row gives you a **Competition ID**.

#### Step 2: Find your season

Run `leagueSeasons` with that Competition ID. Each row gives you a **Season ID**, newest season first.

#### Step 3: Pull the data you actually want

Run `leagueFixtures`, `leagueStandings` or `leagueTopTeams` with both IDs. Every fixture row carries **Team IDs** and a **Match ID** — feed those to the team and match operations for squads, transfers, lineups, incidents, statistics and odds.

**That's it! Within about a minute you'll have:**

- A full league table, or 90 fixtures with scores
- Team and match IDs to drill into
- A clean JSON, CSV or Excel export

***

### 📥 Input Configuration

| Field | Type | Required | Description |
|---|---|---|---|
| `operation` | string | Yes | Which of the 18 datasets to extract. Defaults to `leagueFixtures`. |
| `tournamentId` | integer | For league ops | Competition ID (17 = Premier League, 8 = LaLiga, 35 = Bundesliga, 23 = Serie A, 34 = Ligue 1, 7 = Champions League) |
| `seasonId` | integer | For season ops | Season ID inside that competition (76986 = Premier League 25/26) |
| `teamId` | integer | For team ops | Club or national-team ID (17 = Manchester City, 44 = Liverpool, 2829 = Real Madrid) |
| `playerId` | integer | For `playerProfile` | Player ID (839956 = Erling Haaland) |
| `matchId` | integer | For match ops | Match ID, taken from any fixture, result or live-match row |
| `query` | string | For `leagueSearch` | Competition name to search for |
| `span` | string | No | `last` = played matches with scores, `next` = upcoming fixtures |
| `standingsType` | string | No | `total`, `home` or `away` |
| `page` | integer | No | Zero-based first page for paginated operations |
| `maxPages` | integer | No | Pages to fetch, 30 matches each. Default 3, max 50 |
| `maxResults` | integer | No | Hard cap on rows saved in one run. Default 1000 |

**League table, away split:**

```json
{
  "operation": "leagueStandings",
  "tournamentId": 17,
  "seasonId": 76986,
  "standingsType": "away"
}
```

**Results, three pages (90 matches):**

```json
{
  "operation": "leagueFixtures",
  "tournamentId": 17,
  "seasonId": 76986,
  "span": "last",
  "maxPages": 3
}
```

**A whole squad with market values:**

```json
{
  "operation": "teamSquad",
  "teamId": 17
}
```

**Everything about one match:**

```json
{
  "operation": "matchLineups",
  "matchId": 12436564
}
```

***

### 📤 Output

Every operation writes flat rows to the Apify dataset. `_operation` and `rowType` tell you which shape a row is, so a multi-run dataset stays filterable.

| Field | Type | Description |
|---|---|---|
| `_operation` | string | Operation that produced the row |
| `rowType` | string | `match`, `standingsRow`, `squadPlayer`, `transfer`, `lineupPlayer`, `incident`, `matchStatPeriod`, `oddsMarket`, `bestPlayer`, `team`, `player`, `competition`, `season` |
| `matchId` | integer | Match ID — feed this to the match operations |
| `homeTeamName` / `awayTeamName` | string | The two clubs |
| `homeScore` / `awayScore` | integer | Final or running score |
| `startTime` | string | Kick-off as an ISO 8601 UTC timestamp |
| `position` / `points` | integer | League table position and points |
| `wins` / `draws` / `losses` | integer | League record |
| `goalsFor` / `goalsAgainst` | integer | Goals scored and conceded |
| `playerName` / `playerPosition` | string | Player identity |
| `marketValue` / `contractUntil` | integer / string | Market value and contract end date |
| `playerRating` | number | Per-player match rating out of 10 |
| `formation` | string | Team formation for the match |
| `incidentType` / `incidentMinute` | string / integer | Goal, card or substitution and its minute |
| `statistics` | object | Keyed metrics — season stats, per-half match stats or per-player match stats |
| `oddsChoices` | array | Outcomes for a betting market with fractional odds and movement |

**Example — a standings row:**

```json
{
  "_operation": "leagueStandings",
  "rowType": "standingsRow",
  "status": "success",
  "competitionId": 17,
  "competitionName": "Premier League",
  "seasonId": 76986,
  "standingsSplit": "total",
  "position": 1,
  "teamId": 17,
  "teamName": "Manchester City",
  "teamShortName": "Man City",
  "teamCountry": "England",
  "matchesPlayed": 38,
  "wins": 26,
  "draws": 7,
  "losses": 5,
  "goalsFor": 85,
  "goalsAgainst": 34,
  "goalDifference": "+51",
  "points": 85,
  "promotionText": "Champions League",
  "_fetchedAt": "2026-07-31T13:42:07.118Z"
}
```

**Example — a fixture row:**

```json
{
  "_operation": "leagueFixtures",
  "rowType": "match",
  "matchId": 12436564,
  "competitionName": "Premier League",
  "seasonName": "Premier League 24/25",
  "roundName": "Round 38",
  "startTime": "2025-05-25T15:00:00.000Z",
  "matchStatus": "Ended",
  "homeTeamName": "Ipswich Town",
  "awayTeamName": "Brentford",
  "homeScore": 0,
  "awayScore": 1,
  "winnerCode": 2,
  "venueName": "Portman Road",
  "venueCity": "Ipswich"
}
```

***

### 💼 Use Cases & Examples

#### 1. Fantasy football data feeds

**Fantasy platform operators keeping player prices, availability and scores current without a data-entry team.**

**Input:** `teamSquad` for every club in your league, then `matchLineups` after each round
**Output:** squads with market values, contract dates and positions; per-player minutes, ratings, goals and assists
**Use:** auto-price players, auto-score gameweeks, and flag injuries and unavailable players before deadline.

#### 2. Betting model inputs

**For quantitative bettors and prediction-model builders who need form signal beyond final results.**

**Input:** `leagueStandings` with `standingsType` set to `home` and `away`, plus `teamFixtures` for head-to-head history and `leagueTopTeams` for expected goals
**Output:** home-only and away-only tables, full match history per club, 32 season metrics per team, and `matchOdds` for 18 markets on the fixture you are modelling
**Use:** build home-advantage and expected-goals features that a plain league table cannot give you.

#### 3. Live match trackers and score widgets

**Product teams shipping live score widgets, goal alerts and second-screen apps.**

**Input:** `liveMatches` on a short schedule, then `matchIncidents` for any match you care about
**Output:** every football match in play with running scores and status; goals with assists, cards with reasons, substitutions with minutes
**Use:** push goal notifications and keep a live scoreboard current without maintaining a scraper.

#### 4. Club and scout analytics dashboards

**Analysts and recruitment staff building internal dashboards on squad and market data.**

**Input:** `teamSquad`, `teamTransfers`, `teamSeasonStats` and `matchLineups` across a shortlist of clubs
**Output:** full squads with contract end dates, transfer history with fees, ~120 season metrics per club, and per-player match performance
**Use:** spot contract-expiry opportunities, benchmark squads, and track a target's minutes and ratings over a season.

#### 5. Sports media automation

**Editorial and social teams generating match previews, tables and reports at scale.**

**Input:** `leagueFixtures` for the schedule, `leagueStandings` for the table, `matchLineups` and `matchStatistics` after full time
**Output:** structured fixtures, tables, formations and 46 statistics split by half
**Use:** auto-generate previews, lineup graphics, table updates and post-match reports for every fixture in a round.

#### 6. Historical football datasets for research

**Data scientists and students who need a clean, reproducible football dataset.**

**Input:** `leagueSeasons` to enumerate seasons, then `leagueFixtures` across each
**Output:** every result with scores, dates, rounds and venues in one consistent schema
**Use:** train and back-test models on multiple seasons without hand-cleaning a scraped HTML archive.

#### 7. AI agents that answer football questions

**Agent builders wiring a football tool into an assistant.**

**Input:** the `operation` enum, driven directly by the agent
**Output:** one clean JSON row set per call, with IDs that chain into the next call
**Use:** let an assistant answer "who is top of LaLiga away from home?" or "what was the xG in that match?" with real data instead of a hallucination.

***

### 🔗 Integration Examples

#### JavaScript/Node.js

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_TOKEN' });

const run = await client.actor('sian.agency/football-api-scraper').call({
  operation: 'leagueStandings',
  tournamentId: 17,
  seasonId: 76986,
  standingsType: 'total',
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items.map(r => `${r.position}. ${r.teamName} — ${r.points} pts`));
```

#### Python

```python
from apify_client import ApifyClient
client = ApifyClient('YOUR_TOKEN')

run = client.actor('sian.agency/football-api-scraper').call(
    run_input={
        'operation': 'leagueFixtures',
        'tournamentId': 17,
        'seasonId': 76986,
        'span': 'last',
        'maxPages': 3,
    }
)

for item in client.dataset(run['defaultDatasetId']).iterate_items():
    print(item['homeTeamName'], item['homeScore'], '-', item['awayScore'], item['awayTeamName'])
```

#### cURL

```bash
curl -X POST 'https://api.apify.com/v2/acts/sian.agency~football-api-scraper/runs?token=YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"operation": "teamSquad", "teamId": 17}'
```

#### Automation Workflows (N8N / Zapier / Make)

1. **Trigger**: schedule (e.g. every match day) or webhook
2. **HTTP Request**: call the actor with your chosen `operation`
3. **Process**: filter rows on `_operation` / `rowType`
4. **Action**: write to your database, push a Slack alert, or refresh a dashboard

***

### 📈 Performance & Pricing

#### FREE Tier (Try It Now)

- Full access to all 18 operations — same data, same quality
- No credit card required
- Ideal for evaluating the schema against your model or dashboard

#### PAID Tier (Production Ready)

- Charged **per successful row**, never for error rows
- Set `maxResults` to cap spend on any run before it starts
- League fixtures — the highest-volume operation — carries the lowest per-row rate

💰 **Priced by row value, not by a flat item fee** — a 30-match fixture page and a single team profile do not cost the same, because they are not worth the same.

🔗 [View current pricing](https://apify.com/sian.agency/football-api-scraper?fpr=sian)

***

### ❓ Frequently Asked Questions

**Q: Do I need my own football data API key?**
A: No. The actor handles data access for you — just choose an operation and run it.

**Q: How do I find a Competition ID, Team ID or Match ID?**
A: Run `leagueSearch` for Competition IDs and `leagueSeasons` for Season IDs. Every fixture, result and standings row then contains the Team IDs and Match IDs you need for the deeper operations.

**Q: Which competitions are covered?**
A: Domestic leagues and cups worldwide plus international tournaments — search by name with `leagueSearch` to confirm any specific one.

**Q: Does it cover American football, basketball or tennis?**
A: No. This actor is association football (soccer) only.

**Q: Why did `leagueTopTeams` or `teamSeasonStats` return no rows?**
A: A season that has not kicked off yet has no statistics. Use a season that has been played — `leagueSeasons` lists them newest first.

**Q: Are expected goals (xG) always included?**
A: The `statistics` object is passed through exactly as the source publishes it, and the metric set varies by competition and season. Top European leagues typically include `expectedGoals`, `expectedGoalsOnTarget`, `expectedAssists` and `goalsPrevented`; smaller competitions and very recent seasons may publish only the core set (goals, possession, passing, cards, clean sheets). Check the keys on the row rather than assuming.

**Q: Why is `liveMatches` empty?**
A: Because no football match is in play at that moment. It is a real-time view — run it during a match window, or use `leagueFixtures` to load a schedule instead.

**Q: What output formats are available?**
A: JSON, CSV and Excel — export directly from the Apify dataset.

**Q: Am I charged for failed lookups?**
A: No. Input is validated before anything is charged, and rows that carry `status: "error"` are never billed.

***

### 🐛 Troubleshooting

**A match operation returns "record not found"**

- Check the Match ID came from a fixture, result or live-match row of this actor.
- Very old matches may no longer publish lineups, statistics or odds.

**`leagueStandings` returns no table**

- Knockout cups without a group stage have no league table. Use `leagueFixtures` for those.

**Fewer matches than expected from `leagueFixtures`**

- Each page holds up to 30 matches; raise `maxPages`. Pagination stops automatically when the competition reports no further pages.

**`span: "next"` returned played matches instead**

- The season or team has no upcoming fixtures, so the actor falls back to played matches rather than returning nothing. Check `fixtureWindow` on the rows to see which window was used.

**The run stopped early**

- You hit your own `maxResults` cap. Raise it, or leave it at the default 1000.

***

### ⚠️ Trademark Disclaimer

SIÁN Agency is not affiliated with, endorsed by, or sponsored by any football league, club, competition organiser or data provider named in this documentation or appearing in the extracted data. All club names, competition names, league marks and logos are the property of their respective owners and are referenced solely for identification and descriptive purposes. This actor extracts publicly available football information and is intended for lawful research, analytics and reporting use.

***

### ⚖️ Is it legal to scrape data?

Our actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our actors, when used for ethical purposes by Apify users, are safe.

However, you should be aware that your results could contain personal data. Personal data is protected by the **GDPR** in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers.

You can also read Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/).

***

### 🤝 Support

[![Telegram Support](https://img.shields.io/badge/Telegram-Support%20Group-0088cc?logo=telegram)](https://t.me/+vyh1sRE08sAxMGRi)

**Join our active support community**

- For issues or questions, open an issue in the actor's Issues tab
- Check [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian) for more automation tools
- 📧 <apify@sian-agency.online>

***

**Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)**

# Actor input Schema

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

⚽ Which football dataset to extract. League operations need a Competition ID (plus a Season ID); team operations need a Team ID; match operations need a Match ID; liveMatches needs nothing. Start with leagueSearch to find a Competition ID, then leagueSeasons for its Season IDs. Defaults are set to the English Premier League 25/26.

## `tournamentId` (type: `integer`):

🏆 Numeric competition ID. Required by leagueFixtures, leagueStandings, leagueTopTeams, leagueSeasons and teamSeasonStats. Use the leagueSearch operation to look one up. Examples: 17 = English Premier League, 8 = LaLiga, 35 = Bundesliga, 23 = Serie A, 34 = Ligue 1, 7 = UEFA Champions League.

## `seasonId` (type: `integer`):

📅 Numeric season ID inside the competition. Required by leagueFixtures, leagueStandings, leagueTopTeams and teamSeasonStats. Use the leagueSeasons operation to list them. Example: 76986 = Premier League 25/26. A season that has not kicked off yet has standings but no team statistics.

## `teamId` (type: `integer`):

🛡️ Numeric club or national-team ID. Required by teamFixtures, teamSquad, teamTransfers, teamProfile and teamSeasonStats. Team IDs appear in every fixture and standings row. Examples: 17 = Manchester City, 44 = Liverpool, 42 = Arsenal, 2829 = Real Madrid, 2817 = Barcelona.

## `playerId` (type: `integer`):

👤 Numeric player ID. Required by playerProfile. Player IDs appear in teamSquad, matchLineups and matchIncidents rows. Example: 839956 = Erling Haaland.

## `matchId` (type: `integer`):

⚽ Numeric match ID. Required by matchDetails, matchLineups, matchIncidents, matchStatistics, matchOdds and matchBestPlayers. Match IDs appear in every leagueFixtures, teamFixtures and liveMatches row.

## `query` (type: `string`):

🔍 Competition name to search for. Used only by leagueSearch. Matches leagues, cups and international tournaments — for example "Premier League", "Champions League", "Copa Libertadores".

## `span` (type: `string`):

🕒 Which matches to return for leagueFixtures and teamFixtures. Played = finished matches with final scores. Upcoming = scheduled matches. A finished season has no upcoming matches, so Upcoming automatically falls back to Played.

## `standingsType` (type: `string`):

🏆 Which league table to return for leagueStandings. Full = the complete table. Home = points won at home only. Away = points won away only. The home/away splits are the ones form and betting models actually need.

## `page` (type: `integer`):

📄 Zero-based first page for the paginated operations (leagueFixtures, teamFixtures). Each page returns up to 30 matches.

## `maxPages` (type: `integer`):

📄 How many pages to fetch for the paginated operations. 30 matches per page. Pagination stops early when the competition reports no further pages.

## `maxResults` (type: `integer`):

🎚️ Safety cap on how many rows one run saves. The run stops as soon as the cap is reached, so you are never charged for more rows than you asked for.

## Actor input object example

```json
{
  "operation": "leagueFixtures",
  "tournamentId": 17,
  "seasonId": 76986,
  "teamId": 17,
  "playerId": 839956,
  "matchId": 12436564,
  "query": "Premier League",
  "span": "last",
  "standingsType": "total",
  "page": 0,
  "maxPages": 3,
  "maxResults": 1000
}
```

# Actor output Schema

## `output` (type: `string`):

One flat row per football entity — a match, a league-table row, a squad player, a transfer, a lineup player with match ratings, an incident, a period of match statistics, an odds market or a profile. Curated camelCase fields sit alongside the untouched upstream payload.

## `report` (type: `string`):

HTML run report with the operation, inputs used, success and error row counts, success rate, pages fetched and duration — written even if the run crashes.

# 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 = {
    "operation": "leagueFixtures",
    "tournamentId": 17,
    "seasonId": 76986,
    "teamId": 17,
    "playerId": 839956,
    "matchId": 12436564,
    "query": "Premier League",
    "span": "last",
    "standingsType": "total",
    "maxPages": 3,
    "maxResults": 1000
};

// Run the Actor and wait for it to finish
const run = await client.actor("sian.agency/football-api-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 = {
    "operation": "leagueFixtures",
    "tournamentId": 17,
    "seasonId": 76986,
    "teamId": 17,
    "playerId": 839956,
    "matchId": 12436564,
    "query": "Premier League",
    "span": "last",
    "standingsType": "total",
    "maxPages": 3,
    "maxResults": 1000,
}

# Run the Actor and wait for it to finish
run = client.actor("sian.agency/football-api-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 '{
  "operation": "leagueFixtures",
  "tournamentId": 17,
  "seasonId": 76986,
  "teamId": 17,
  "playerId": 839956,
  "matchId": 12436564,
  "query": "Premier League",
  "span": "last",
  "standingsType": "total",
  "maxPages": 3,
  "maxResults": 1000
}' |
apify call sian.agency/football-api-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=sian.agency/football-api-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/CNV4ewcLtLCcmgSJN/builds/g8Z3creXSHcIxfUjN/openapi.json