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

🎉 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 for 30+ sports, or Basketball API Scraper for basketball box scores and standings. If you only want bookmaker lines and price movement across many sports, use Sports Betting Odds Scraper. This actor covers association football (soccer) only, not American football, basketball or tennis.

---

🤖 Use with AI agents

Already connected to the Apify MCP server? 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, so an agent can discover it, run it and settle the bill over x402 (USDC on Base) or Skyfire — 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:

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.

---

📋 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.

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:

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

Results, three pages (90 matches):

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

A whole squad with market values:

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

Everything about one match:

{
  "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:

{
  "_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:

{
  "_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

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

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

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

---

❓ 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.

---

🤝 Support

Join our active support community

• For issues or questions, open an issue in the actor's Issues tab
• Check SIÁN Agency Store for more automation tools
• 📧 apify@sian-agency.online

---

Built by SIÁN Agency | More Tools