ScraperFC API Documentation

An example of API technical writing. Documents a method from the ScraperFC package (Python). Covers parameters, return types, workflow examples, error handling, versioning and data-extraction constraints.
Author

Diggy

Published

November 1, 2025

Copyright 2022 Owen Seymour. Use of this source code is governed by the GPL 3.0 license.

scrape_stats()

  • Class: ScraperFC.fbref.FBref
  • Method: scrape_stats()
  • Returns: A tuple of DataFrames
Usage considerations
  • Before using this scraper on FBref data, review the Sports Reference Terms of Service.
  • Data usage: FBref permits scraping only under certain use cases (e.g., personal or educational). It is not permitted for competing analytics services or for public hosting.
  • Rate limiting: FBref requests no more than 10 site requests per minute. This scraper uses wait_time=7 to pause between requests. Always check the current terms of service before scraping.

scrape_stats() allows you to download FBref season-level Squad Stats, Opponent Stats, and Player Stats for a chosen statistics collection such as “Advanced Goalkeeping”.

You can reference the available statistics collections through this FBref navigation:
Competition > ‘Squad & Player Stats’ dropdown > Statistical Collection > Toggle between ‘Squad & Opponent Stats’ or scroll for ‘Player Stats’

You can find an example of Premier League 2024/25 ‘Player Stats’ from the ‘Standard’ stats collection here.

Prerequisites

  1. Install the ScraperFC package:
pip install ScraperFC

(The package is not currently available on conda or conda-forge.)

  1. Load the fbref module:
from ScraperFC.fbref import FBref
  1. Initialize the scraper object:
fb_scraper = FBref()

Parameters

  • year (str, required)
    • Season to scrape.
    • Format: match the season strings on the Competition History page of the target league (e.g., Big 5 Leagues).
    • You can check accepted year inputs with get_valid_seasons():
valid_seasons = fb_scraper.get_valid_seasons("La Liga")
season_list = list(valid_seasons.keys())
print(season_list)
Output 
['2025-2026', '2024-2025', '2023-2024', '2022-2023', ...]
  • league (str, required)
    • League to scrape (usually the long name, e.g., “Bundesliga”, “Ligue 1”; some exceptions like “EPL”).
    • Check accepted values with comps.keys():
valid_league_names = list(fb_scraper.comps.keys())
print(valid_league_names)
Output 
['Copa Libertadores', 'Champions League', 'Europa League', ...]
  • stat_category (str, required)
    • Stat category to scrape; use the full names except “miscellaneous”, which should be "misc".
    • Check accepted values with stats_categories.keys():
stat_categories = list(fb_scraper.stats_categories.keys())
print(stat_categories)
Output 
['standard', 'goalkeeping', 'advanced goalkeeping', ...]

Returns

A tuple of three pd.DataFrame objects: (squad_stats, opponent_stats, player_stats)

  1. squad_stats: Aggregated stats for all squads in the league and season.
  2. opponent_stats: Aggregated opponent stats for all squads.
  3. player_stats: Player-level stats for the league and season.

Error handling

If an invalid league name is passed, an error message will print the accepted entries:

seasons = ["2025-2026"]
leagues = ["not a league"]
Output 
Scraping not a league 2025-2026...
Failed scraping not a league 2025-2026: not a league is not a valid league for FBref. Valid leagues are ['Copa Libertadores', 'Champions League', 'Europa League', 'Europa Conference League', ...]

Full workflow example

This example loops through multiple leagues and seasons, retrieves the standard and misc stat categories, and stores only the player_stats DataFrames.

from ScraperFC.fbref import FBref
import pandas as pd

# Initialize scraper object
fb_scraper = FBref()

# Select desired seasons and leagues
seasons = ["2022-2023", "2023-2024"]
leagues = ["EPL", "La Liga"]

# Capture the DataFrames during the loop
all_player_dfs = []

# Loop through all desired seasons and leagues
for season in seasons:
    for league in leagues:
        try:
            print(f"Scraping {league} {season}...")

            # Scrape 'standard' stats and omit squad/opponent stats
            _, _, df_standard = fb_scraper.scrape_stats(season, league, "standard")

            # Scrape 'misc' stats and omit squad/opponent stats
            _, _, df_misc = fb_scraper.scrape_stats(season, league, "misc")

            # Populate the list
            all_player_dfs.append(df_standard)
            all_player_dfs.append(df_misc)
        except Exception as e:
            print(f"Failed scraping {league} {season}: {e}")

print("Scraping complete.")

Versioning

This documentation applies to ScraperFC v3.4.0 (current stable release).

To check your installed version:

from importlib.metadata import version

installed_version = version("ScraperFC")
print(f"ScraperFC Version: {installed_version}")
Warning

A major overhaul to the league-names parameter is planned for v4.0. Upgrading may break existing code. To preview upcoming changes, switch the documentation dropdown (bottom-right) from “stable” to “latest”.

Sources