Football Stats Scraper: 3 Practical Use Cases and Workflow

The Football Stats Scraper extracts structured football statistics directly from ESPN public sports API without requiring an API key, proxy, or registration. It retrieves league standings, match results, team statistics, and player search profiles across 29 global leagues, including the English Premier League, Spanish La Liga, German Bundesliga, Italian Serie A, French Ligue 1, US Major League Soccer, and UEFA Champions League. Users configure collection runs using four operational modes (standings, matchResults, teamStats, playerSearch) and filter outputs using league codes, player queries, date ranges, and maximum item caps up to 500 records. Data is delivered in clean JSON format for analytics, fantasy applications, and dashboards.

Core Capabilities and Operational Modes

The scraper interacts with ESPN public sports API endpoints to gather structured data across global football competitions. Users select from four supported operation modes based on analytical goals:

1. League Standings (mode: standings): Returns the complete competition table including rank, games played, wins, draws, losses, points, goals for, goals against, goal difference, team logos, team URLs, and qualification note annotations.
2. Match Results (mode: matchResults): Retrieves detailed match logs, home and away scores, match dates, venue names, venue cities, spectator attendance, and completion status flags.
3. Team Stats (mode: teamStats): Accesses team-level profiles, season records, and competition metadata for target clubs.
4. Player Search (mode: playerSearch): Queries player profiles by name to extract positional details, age, nationality, and club affiliation.

Data endpoints are publicly accessible, allowing reliable data extraction without managing proxy pools or API credentials.

Input Parameter Mappings and League Configurations

Executing precise extraction runs requires configuring specific input parameters defined in the actor schema.

The primary control field is mode, which dictates the target data type from ESPN API (standings, matchResults, teamStats, or playerSearch). The league parameter identifies the competition using standardized short codes. Defaulting to eng.1 for the English Premier League, the tool supports 29 major competitions worldwide. Key league identifiers include:

• eng.1: English Premier League
• esp.1: Spanish La Liga
• ger.1: German Bundesliga
• ita.1: Italian Serie A
• fra.1: French Ligue 1
• usa.1: US Major League Soccer
• uefa.champions: UEFA Champions League
• uefa.europa: UEFA Europa League
• uefa.europa.conf: UEFA Conference League
• ned.1: Dutch Eredivisie
• por.1: Portuguese Primeira Liga
• bra.1: Brazilian Série A
• arg.1: Argentine Primera División
• mex.1: Mexican Liga MX
• sco.1: Scottish Premiership
• tur.1: Turkish Süper Lig
• jpn.1: Japanese J1 League

Date filtering fields fromDate and toDate accept YYYYMMDD formatted string dates (such as 20250101 and 20250131). These parameters function exclusively when mode is set to matchResults. When omitted, fromDate defaults to 30 days prior and toDate defaults to the current day.

For athlete lookups in playerSearch mode, the playerQuery string field receives search terms such as 'Erling Haaland' or 'Vinicius'. Finally, maxItems sets an integer limit on the payload size between 1 and 500 records (default is 50).

Output Data Schemas and Field Definitions

The scraper generates standardized JSON outputs customized to the selected execution mode.

In standings mode, individual record payloads contain granular team metrics:

• teamName: Full club name string (e.g., "Arsenal")
• teamAbbreviation: Three-letter club code (e.g., "ARS")
• teamId: Unique ESPN team string identifier (e.g., "359")
• leagueId and leagueName: League key (eng.1) and descriptive name (English Premier League)
• season: Descriptive season identifier (e.g., "2024-25 English Premier League")
• rank: Integer table position
• played, won, drawn, lost, points: Cumulative season tally fields
• goalsFor, goalsAgainst, goalDifference: Scoring differential metrics
• standingNote: Tournament qualification status (e.g., "Champions League")
• teamLogoUrl and teamUrl: Direct URLs to club media assets and ESPN pages
• scrapedAt: ISO 8601 UTC timestamp tracking data collection time

In matchResults mode, output objects detail game outcomes:

• matchId: Unique match identifier string (e.g., "727459")
• matchDate and matchDateLocal: Timestamps in ISO UTC and local date formats
• status: Game state indicator (e.g., "FT" for full time)
• isCompleted: Boolean flag indicating completed matches
• homeTeamName, homeScore, homeWinner: Home side statistics and win flag
• awayTeamName, awayScore, awayWinner: Away side statistics and win flag
• venue, venueCity, attendance: Match venue name, location, and attendance numbers

Practical use cases

These use cases come from Football Stats Scraper's published documentation. Each is expanded into an operating pattern so the Football Stats Scraper output has a purpose beyond collection.

Use case 1: Fantasy football

Outcome: track player performance and team form.

Question to answer: Looking only at confirmed differences, which ones are worth a response and which are just formatting noise?

Configure: Start with league (Football league to scrape. Covers all major European and global leagues.), playerQuery (Player name to search for (e.g. 'Erling Haaland', 'Vinicius').), mode (What data to fetch from the football API.). Use the narrowest Football Stats Scraper values that represent the real task, keep the first result set small, and record why each selected input matters to the Football Stats Scraper outcome.

Working method: Timestamp every collection and compare it only against its immediate predecessor using a stable key. Treat a difference as provisional until it survives one more run, and log the specific field that changed alongside the record.

Deliverable: Create a change log entry per run listing what appeared, what disappeared, and what changed enough to matter. Include the Football Stats Scraper source identifier and the collected fields behind every Football Stats Scraper decision.

Stop condition: Pause when records cannot be matched reliably over time, collection scope changed between runs, or missing data looks like a real-world change. Fix the Football Stats Scraper question, comparison rule, or configuration before expanding the Football Stats Scraper run.

Use case 2: Research

Outcome: compile season statistics for any major league.

Question to answer: Which side-by-side comparisons hold up once outliers are set aside, and which depend entirely on them?

Configure: Start with league (Football league to scrape. Covers all major European and global leagues.), fromDate (Start date for match results in YYYYMMDD format (e.g. 20250101). Defaults to 30 days ago.), toDate (End date for match results in YYYYMMDD format (e.g. 20250131). Defaults to today.). Use the narrowest Football Stats Scraper values that represent the real task, keep the first result set small, and record why each selected input matters to the Football Stats Scraper outcome.

Working method: Lock the comparison rule before looking at any results, sort records into groups against that fixed rule, and keep a running note of anything that does not cleanly belong to a group.

Deliverable: Create a side-by-side comparison table with cohort labels, normalized fields, and a short note on what the gap implies. Include the Football Stats Scraper source identifier and the collected fields behind every Football Stats Scraper decision.

Stop condition: Pause when the cohorts are structurally different, coverage is uneven, or the ranking depends mainly on missing values. Fix the Football Stats Scraper question, comparison rule, or configuration before expanding the Football Stats Scraper run.

Use case 3: Dashboards

Outcome: power live league tables for websites and apps.

Question to answer: Once the acceptance rule is fixed, which records satisfy it outright, and which sit in a gray zone?

Configure: Start with league (Football league to scrape. Covers all major European and global leagues.), fromDate (Start date for match results in YYYYMMDD format (e.g. 20250101). Defaults to 30 days ago.), toDate (End date for match results in YYYYMMDD format (e.g. 20250131). Defaults to today.). Use the narrowest Football Stats Scraper values that represent the real task, keep the first result set small, and record why each selected input matters to the Football Stats Scraper outcome.

Working method: Fix the accepted, uncertain, and excluded definitions before the first record is reviewed, then apply the rule consistently and log the field behind every classification so a second pass can check it.

Deliverable: Create a reviewed queue where every record keeps its raw form alongside the rule that accepted, excluded, or flagged it as uncertain. Include the Football Stats Scraper source identifier and the collected fields behind every Football Stats Scraper decision.

Stop condition: Pause when required fields are often absent, relevance cannot be judged consistently, or reviewers disagree on the acceptance rule. Fix the Football Stats Scraper question, comparison rule, or configuration before expanding the Football Stats Scraper run.

Step-by-Step Sports Data Collection Workflow

Follow this five-step operational workflow to set up clean football data extraction:

1. Select Operational Mode and League Identifier: Define the data scope and choose the appropriate mode value (standings, matchResults, teamStats, or playerSearch). Set league to the required short code, such as eng.1 for Premier League or esp.1 for La Liga.
2. Configure Parameters for Target Scope: For match queries, enter fromDate and toDate in YYYYMMDD format. For player searches, enter playerQuery. Run an initial validation pass with maxItems set to 5.
3. Validate JSON Output Payload: Verify that essential fields like matchId, teamName, points, or scrapedAt are correctly populated in the test JSON output.
4. Expand Record Volume for Production Runs: Increase maxItems up to 500 records to capture complete league tables or full monthly match sets.
5. Deduplicate and Store Final Outputs: Ingest raw JSON objects into target analytical storage, using matchId or teamId as primary key fields to prevent duplicate records.

Frequently Asked Questions

Does using this tool require any API key or subscription?

No API key, proxy, or registration is required. The actor directly queries ESPN public sports endpoints and operates within the Apify free tier.

Which leagues are supported by the Football Stats Scraper?

The actor supports 29 global competitions. These include top national leagues like the English Premier League (eng.1), Spanish La Liga (esp.1), German Bundesliga (ger.1), Italian Serie A (ita.1), French Ligue 1 (fra.1), US Major League Soccer (usa.1), and international club competitions like the UEFA Champions League (uefa.champions).

How do I configure date filters for match data?

Set mode to matchResults and enter start and end dates in fromDate and toDate using YYYYMMDD format (e.g., 20250101 and 20250131). Date parameters function exclusively when mode is set to matchResults.

What is the maximum record limit per run?

Each execution returns up to 500 records as specified by maxItems (default is 50). For league standings, a single run typically retrieves every club in the competition table.

How can I search for individual football players?

Set mode to playerSearch and enter the player name in playerQuery (e.g., 'Erling Haaland' or 'Vinicius'). The actor returns matching player profiles with position, age, nationality, and team details.

Resources

• Football Stats Scraper on Apify