10 分钟上手免费足球数据获取：Understat Python 包异步爬取 xG 全指南

10 分钟上手免费足球数据获取Understat Python 包异步爬取 xG 全指南【免费下载链接】understatAn asynchronous Python package for https://understat.com/.项目地址: https://gitcode.com/gh_mirrors/un/understat做足球数据分析最头疼的往往不是算法而是数据从哪来。本文的主角——Understat Python 包正是一个专注于足球数据获取的免费开源工具它用异步方式抓取 understat.com 上的 xG、PPDA 等专业指标安装到跑通第一个查询只需几分钟。如果你正为免费足球数据 API发愁这篇实战指南会把从零到能用的每一步都讲清楚。先弄清一个问题xG 数据为什么这么难拿假设你想评估西甲某支球队本赛季的进攻质量比如他们创造机会的能力到底强不强。摆在面前的无非三条路打开数据网站手动翻表把 JS 动态渲染的表格一条条复制出来一场比赛的数据就要折腾十几分钟自己写爬虫应付动态加载、请求头、JSON 提取半天起步还随时可能因页面改版而报废购买商业数据接口年费动辄数万美元个人玩家和中小团队根本吃不消。更麻烦的是真正有价值的信息——xG预期进球、xA预期助攻、xGChain 这类看不见的指标普通页面展示得十分有限。问题于是变成有没有一条轻量路径跳过抓取工程直接拿到干净的结构化数据这正是 Understat 包存在的理由。Understat 包是什么一个类覆盖四大数据层级这个项目把 understat.com 背后的数据接口全部翻译成了 Python 方法核心只有一个Understat类。它的构造参数只有一个aiohttp.ClientSession也就是说所有请求共享同一个会话、复用底层连接——这正是异步爬取足球数据效率高的原因。整个包的代码规模小得惊人核心逻辑集中在understat/understat.py和understat/utils.py两个文件里却提供了约 17 个方法大致覆盖四个层级数据层级典型方法能拿到什么联赛get_league_players、get_league_results、get_league_table整季球员榜、赛果、积分榜球队get_team_results、get_team_players、get_team_stats单队战绩、队内球员、赛季统计球员get_player_shots、get_player_matches逐次射门、逐场表现单场比赛get_match_shots、get_match_players一场比赛的全部射门与出场名单返回数据全是 Python 原生的dict和list拿到手就能直接丢进 pandas 继续分析省去了繁琐的解析环节。两分钟装好免费足球数据包pip 或源码二选一环境要求很低Python 3.6 以上即可。最省事的方式是 pip 一条命令依赖如 aiohttp会自动装好pip install understat想从源码开始折腾也可以先克隆仓库再本地安装git clone https://gitcode.com/gh_mirrors/un/understat cd understat pip install .装完别急着写代码先跑一遍项目自带的测试确认环境没问题pytest tests/测试全部通过说明包与当前环境兼容良好可以进入正题了。官方 API 说明放在 docs/classes/understat.rst遇到拿不准的方法随时查。第一次异步爬取生成西甲射手榜只需十行代码下面这段代码要解决的问题很具体快速拿到西甲一个赛季里创造机会最多的球员榜单。注意不是按进球数而是按 xG 排序——这正是 xG 数据分析的常见入门操作。import asyncio import aiohttp from understat import Understat async def build_scorer_board(): # 同一个会话内复用连接这是异步提速的关键 async with aiohttp.ClientSession() as session: client Understat(session) # 拉取西甲 2023 赛季全部球员的赛季数据 squad await client.get_league_players(la_liga, 2023) # 注意接口返回的数字大多是字符串先转成浮点数再排序 ranked sorted(squad, keylambda p: float(p[xG]), reverseTrue) for i, p in enumerate(ranked[:10], 1): print(f{i}. {p[player_name]}{p[team_title]} f进球 {p[goals]}xG {round(float(p[xG]), 2)}) asyncio.run(build_scorer_board())执行后控制台会依次打印出 xG 排名前十的球员。每条记录里除了goals、xG还有xA、assists、shots、key_passes、npg非点球进球、npxG非点球 xG、xGChain、xGBuildup等二十多个字段一次请求就把球员的进攻全貌带回来了。顺带一提联赛参数用的是缩写epl、la_liga、bundesliga、serie_a、ligue_1、rfpl六大主流联赛都在支持范围内。精准取数过滤参数与数据类型的两个细节抓回来的是一整个联赛的球员但很多时候你只关心某一支球队。不用在内存里慢慢筛方法本身就支持过滤async def scout_one_team(team_name): async with aiohttp.ClientSession() as session: client Understat(session) # 只保留指定球队的球员等价于网页表格里的筛选 members await client.get_league_players( la_liga, 2023, team_titleteam_name) return members过滤条件既可以写成team_titleteam_name这种关键字参数也可以打包成一个字典传进options参数两者效果一样。get_teams、get_team_results、get_player_shots等方法都遵循这套约定。这里要提醒新手两点数值字段多是字符串。goals: 11里的 11 是字符串做运算前先float()转换上面的排序代码就吃了这个亏才写对。嵌套结构要心里有数。比如比赛记录里主客队是h、a两个字典xG 也是{h: ..., a: ...}的结构取数时别搞混。高级指标一步到位读积分榜直接拿到 PPDA很多分析师关注 PPDA每次防守动作的传球次数——数值越低说明球队前场逼抢越凶。这个指标通常要自己从海量事件里计算但在这里只需要一次调用async def print_standings(): async with aiohttp.ClientSession() as session: client Understat(session) # 一行调用直接返回带表头的联赛积分榜 table await client.get_league_table(la_liga, 2023) for row in table: print(row)返回的是一张二维列表第一行是表头后面每行对应一支球队除了常规的胜平负、积分、进球数还直接附带了xG、NPxG、xGA、PPDA、OPPDA、DC深入进攻三区次数、xPTS预期积分等高级指标。用这张表就能做很有意思的对比找两支积分相近的球队比较它们的 PPDA你会发现防得凶和防得住完全是两回事。想看某一时间段的排名还能传start_date和end_date格式YYYY-MM-DD按日期区间重新计算积分榜。从宏观到微观拆解单场比赛的每一次射门联赛数据是宏观视角想研究一场具体比赛的对攻细节可以切换到单场维度。下面这段代码会打印出某场比赛的全部射门记录按主客队分组并带上每次射门的 xG 值async def dissect_match(match_id): async with aiohttp.ClientSession() as session: client Understat(session) # 返回该场比赛的全部射门记录按主客队分组 shots await client.get_match_shots(match_id) for side in (h, a): print(f--- {side} 队射门 ---) for s in shots[side]: print(s[minute], s[player], s[result], round(float(s[xG]), 3))每条射门记录还带situation定位球/运动战、shotType左脚/右脚/头球、射门坐标X/Y等字段。如果你对某位球员特别感兴趣get_player_shots(球员ID)能拉出他职业生涯的每一次射门配合get_player_grouped_stats还能按赛季、位置、射门区域分组查看统计做球员评估的素材基本齐了。多赛季并发拉取与工具化打磨单一赛季的数据往往不够做 xG 数据分析常常需要连续几个赛季做纵向对比。借助asyncio.gather可以同时发起多个请求把耗时几乎压缩到单次请求的水平import asyncio import aiohttp from understat import Understat async def fetch_season(client, season): data await client.get_league_players(la_liga, season) return season, data async def collect_multi_season(): async with aiohttp.ClientSession() as session: client Understat(session) # 三个赛季的请求同时发出总耗时约等于最慢的那一个 tasks [fetch_season(client, s) for s in (2021, 2022, 2023)] for season, data in await asyncio.gather(*tasks): print(season, 共抓取, len(data), 名球员) asyncio.run(collect_multi_season())跑正式项目前还可以做两件小事让脚本更耐用加一层简单缓存同一赛季的数据没必要反复抓把结果存成本地 JSON下次命中缓存直接读取控制节奏给请求加上超时设置遇到网络波动时捕获异常并重试而不是让整个脚本崩掉。记住你用的是别人的免费服务别用极端频率的循环去轰炸服务器礼貌地取数才能用得长久。结尾合规使用与你的下一步最后把话说明白这个包是社区爱好者为方便数据获取而写的开源项目与 understat.com 没有官方合作关系。使用时请尊重网站的条款与负载控制请求频率也不要把数据用于商业牟利。到这里你已经掌握了完整的取数链路装包、跑通首个查询、按条件过滤、读取含 PPDA 的高级积分榜、拆解单场射门、并发拉取多赛季数据。接下来建议你回到 tests/test_understat.py 看看项目自带的测试用例那里覆盖了每个方法的典型用法是最好的学习范本。从一行射手榜查询开始再到搭建你自己的 xG 分析脚本这套免费足球数据 API 能带你走很远。现在就去跑第一段代码吧十分钟后你就拥有自己的专业级足球数据库了。【免费下载链接】understatAn asynchronous Python package for https://understat.com/.项目地址: https://gitcode.com/gh_mirrors/un/understat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考