A Python Project About Football Data Extraction

Most of the projects in this list came out of a job needing something automated. TacosScore didn't, it came out of wanting clean football data for my own analysis, and getting tired of writing the same messy request-and-parse code against Sofascore's API every time I tried. So I built the library I actually wanted, and published it, publicly, on PyPI.

---

The Problem

• Sofascore's API is undocumented, returns deeply nested, camelCase JSON, and can change shape without notice, so every script ends up guessing at fields against raw dictionaries
• Plain HTTP requests get blocked outright, Akamai's bot protection returns a 403 to anything that doesn't look like a real browser
• Nothing stops a naive script from hammering the API and getting rate-limited or banned mid analysis, there's no built-in backoff to fall back on
• Match and player data live behind dozens of separate endpoints, lineups, stats, incidents, shot maps, heatmaps, so pulling one full match means stitching several calls together by hand every time

---

The Approach

TacosScore is a real, installable package (pip install tacoscore), not a personal script, so it had to actually solve each of those problems, not just work on my machine once.

• Getting past the block, requests go through curl_cffi with Chrome TLS impersonation, so they pass as a real browser instead of tripping Akamai's protection
• Typed data, not JSON soup, every response is converted into typed Python dataclasses with snake_case fields, so autocomplete and type checkers catch mistakes instead of a KeyError at runtime
• Staying under the limit, built-in rate limiting and exponential backoff on 429 responses, configurable per client, so a long analysis run doesn't get itself blocked halfway through
• One call for a whole match, fetch_full_match() orchestrates the multi-endpoint pipeline itself, lineups, stats, incidents, shot maps, with intelligent skipping, instead of the caller stitching endpoints together by hand
• Two ways to call it, a sync TacosScoreClient and an async AsyncTacosScoreClient, plus a full interactive CLI with every major endpoint as its own subcommand
• Ready for analysis, not just access, every model exports straight to a pandas DataFrame via .to_dataframe(), and spatial data ships with StatsBomb (120×80) and FIFA (105×68) pitch coordinate converters for anyone plotting heatmaps or shot maps

132+ tests cover the parsers, the client, the CLI and the extraction rules, since a library other people might actually install has a different bar than a script only I ever run.

---

The Outcome

• Published on PyPI, installable with a single pip install, MIT licensed, versioned releases starting at 0.1.3
• 132+ tests, covering parsers, clients, the CLI and extraction rules
• Full coverage, match metadata, lineups, team stats, incidents and shot maps, player heatmaps and per-player shot maps, tournament and team/player profile data, all through one typed interface
• Two interfaces, one library, a Python client for scripts and notebooks, and a CLI for anyone who'd rather not write Python at all