# openfootball/football.json API [openfootball]() 是一个免费、开放、公共领域的足球 (soccer) 数据集合。 [football.json]() 存储库为全球主要联赛和锦标赛提供预构建的 JSON 文件。 **无需 API 密钥或身份验证。** ** ** ## 数据源有两种方式访问数据： ### 1\.原始 GitHub URL（主要） https://raw.githubusercontent.com/openfootball/football.json/master/{season}/{league}.json ### 2\. GitHub 页面镜像 https://openfootball.github.io/{country}/{season}/{league-name}.json > **建议：** 使用 `football.json` 存储库的原始 GitHub URL — 它们使用简单、一致的命名约定，并且是最可靠的。 ** ** ## 网址结构 https://raw.githubusercontent.com/openfootball/football.json/master/{season}/{code}.json 组件|描述 |示例 ---|---|--- `{季节}` |季节目录 - 跨年或日历年 | `2024-25`、`2023-24`、`2025`、`2019` `{代码}` | “{国家}.{分区}”格式的联赛代码 | `en.1`、`de.1`、`es.1`、`it.1`、`fr.1` ** ** ## 可用联赛 ### 英格兰代码|联赛|等级 ---|---|--- `en.1` |英格兰超级联赛 |第一师 `en.2` |英格兰锦标赛|第二师 `en.3` |英格兰甲级联赛 |第三师 `en.4` |英格兰联赛二 |第四师 ### 德国代码|联赛|等级 ---|---|--- `de.1` |德甲 | 德甲第一师 `de.2` | 2\.德甲 |第二师 `de.3` | 3\.联赛 |第三师 ### 西班牙代码|联赛|等级 ---|---|--- `es.1` |西甲联赛 (西甲) |第一师 `es.2` |乙组 |第二师 ### 意大利代码|联赛|等级 ---|---|--- `it.1` |意甲 |第一师 `it.2` |乙级联赛|第二师 ### 法国代码|联赛|等级 ---|---|--- `fr.1` |联赛 1 |第一师 `fr.2` |联赛2 |第二师 > **注意：** 并非所有联赛都适用于所有赛季。 `football.json` 存储库不断更新 - 检查 [存储库]() 以获取可用文件的完整列表。 ** ** ## 可用季节 “football.json”存储库中的赛季目录可追溯到“2010-11”。欧洲联赛使用跨年度格式（“2024-25”），而一些日历年联赛则使用单年格式（“2025”）。格式|用途 |示例 ---|---|--- `YYYY-YY` |欧洲俱乐部赛季（8 月至 5 月）| `2024-25`、`2023-24`、`2015-16` `YYYY` |历年比赛| “2025 年”、“2020 年”、“2019 年” 已知季节目录：`2010-11`、`2011-12`、`2012-13`、`2013-14`、`2014-15`、`2015-16`、`2016-17`、`2017-18`、`2018-19`、`2019-20`、`2020-21`、 `2021-22`、`2022-23`、`2023-24`、`2024-25`、`2025-26`、`2019`、`2020`、`2025`。 ** ** ## JSON 响应格式所有文件都遵循相同的 JSON 架构： { "name": "英格兰超级联赛 2024/25", “匹配”：[ { "round": "比赛日 1", “日期”：“2024-08-16”， "时间": "20:00", "team1": "曼联足球俱乐部", "team2": "富勒姆足球俱乐部", “分数”：{ "ht": [0, 0], “ft”：[1, 0] } } ] } ### 顶级字段领域|类型 |描述 ---|---|--- `名称` |字符串|人类可读的联赛名称和赛季 `匹配` |数组|匹配对象数组 ### 匹配对象字段领域|类型 |必填|描述 ---|---|---|--- `圆形` |字符串|是的 |回合/比赛日名称（例如“Matchday 1”、“Round of 16”） `日期` |字符串|是的 | “YYYY-MM-DD”格式的匹配日期 `时间` |字符串|没有 |开球时间采用“HH:MM”格式（24 小时制，当地时间） `团队1` |字符串|是的 |主队名称 `团队2` |字符串|是的 |客队名称 `分数` |对象|没有 |得分对象（未来未进行的比赛不存在） `状态` |字符串|没有 |特殊地位（例如，行政决定结果的“授予”） ### 评分对象字段领域|类型 |描述 ---|---|--- `ft` | `[int, int]` |全场比分‘[主客场]` `ht` | `[int, int]` |半场得分“[主场，客场]”（某些比赛可能缺席） > **注意：** 有些比赛只有“ft”（全场）而没有“ht”（半场）。在访问“ht”之前始终检查它是否存在。 ** ** ## 常见模式 ### 获取联赛赛季（curl）卷曲-s“https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json”| jq . ### 获取并解析匹配数据 (Python) 导入请求 url =“https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json” 数据 = requests.get(url).json() print(f"联赛: {data['name']}") print(f"总匹配数：{len(data['matches'])}") 对于 data["matches"][:10] 中的匹配： ft = match.get("分数", {}).get("ft") 如果英尺： print(f" {match['date']} {match['team1']} {ft[0]}-{ft[1]} {match['team2']}") 其他： print(f" {match['date']} {match['team1']} vs {match['team2']} (无得分)") ### 根据结果构建联赛表 (Python) 导入请求从集合导入defaultdict url =“https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json” 数据 = requests.get(url).json() 表 = defaultdict(lambda: {"玩过": 0, "赢了": 0, "平局": 0, "输了": 0, “gf”：0，“ga”：0，“点”：0}）对于数据中的匹配[“匹配”]：得分 = match.get("得分", {}).get("ft") 如果没有得分：继续 t1, t2 = 比赛["球队1"], 比赛["球队2"] g1, g2 = 分数对于 [(t1, g1, g2), (t2, g2, g1)] 中的团队、gf、ga：表[团队][“玩过”] += 1 表[团队]["gf"] += gf 表[团队]["ga"] += ga 如果 gf > ga：表[球队][“获胜”] += 1 表[团队]["分数"] += 3 elif gf == ga: 表[团队][“抽签”] += 1 表[团队]["分数"] += 1 其他：表[团队][“失败”] += 1 # 按积分排序，然后是净胜球排序表 = 排序(表.items(), key=lambda x: (x[1]["points"], x[1]["gf"] - x[1]["ga"]), 反向=真） print(f"{'团队':<35} {'P':>3} {'W':>3} {'D':>3} {'L':>3} {'GF':>4} {'GA':>4} {'GD':>4} {'Pts':>4}") 打印（“-”* 70）对于 i，枚举（sorted_table，1）中的（团队，统计数据）： gd = 统计数据["gf"] - 统计数据["ga"] print(f"{i:>2}.{team:<32} {stats['played']:>3} {stats['won']:>3} " f"{统计['绘制']:>3} {统计['丢失']:>3} {统计['gf']:>4} " f"{stats['ga']:>4} {gd:>+4} {stats['points']:>4}") ### 按球队过滤比赛 (Python) 导入请求 url =“https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json” 数据 = requests.get(url).json() 球队=“阿森纳足球俱乐部” matches = [m for m in data["matches"] if team in (m["team1"], m["team2"]) and m.get("score", {}).get("ft")] 对于匹配中的 m： ft = m["分数"]["ft"] 对手 = m["team2"] if m["team1"] == team else m["team1"] 场地 = "H" if m["team1"] == team else "A" my_goals = ft[0] if m["team1"] == team else ft[1] opp_goals = ft[1] if m["team1"] == team else ft[0] 结果 = "W" 如果 my_goals > opp_goals else ("D" 如果 my_goals == opp_goals else "L") print(f" {m['date']} ({venue}) {结果} {my_goals}-{opp_goals} vs {opponent}") ### 获取多个联赛 (Python) 导入请求联赛 = { "英超联赛": "en.1", "德甲": "de.1", "西甲": "es.1", 《意甲》：“it.1”， "Ligue 1": "fr.1", } 季节=“2024-25” 基=“https://raw.githubusercontent.com/openfootball/football.json/master” 对于名称，在 leagues.items() 中的代码： url = f"{基地}/{季节}/{代码}.json" 响应 = requests.get(url) 如果 resp.status_code == 200：数据 = resp.json() 总计 = len(数据["匹配"]) Play = sum(1 for m in data["matches"] if m.get("score", {}).get("ft")) print(f"{name}: {已玩}/{总计} 场比赛") 其他： print(f"{name}: 不适用于 {season}") ### 获取和解析 (Node.js) const url = "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json"; const res = 等待 fetch(url); const 数据 = 等待 res.json(); console.log(`联赛：${data.name}`); console.log(`匹配：${data.matches.length}`); data.matches.slice(0, 10).forEach((m) => { const ft = m.score?.ft; 如果（英尺）{ console.log(` ${m.date} ${m.team1} ${ft[0]}-${ft[1]} ${m.team2}`); } }); ### 获取并解析（bash + jq） # 获取特定团队的所有结果卷曲-s“https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json”\ | jq -r '.matches[] | select(.team1 == "利物浦足球俱乐部" 或 .team2 == "利物浦足球俱乐部") |选择(.score.ft) | "\(.date) \(.team1) \(.score.ft[0])-\(.score.ft[1]) \(.team2)"' ### 比较头对头结果 (Python) 导入请求 url =“https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json” 数据 = requests.get(url).json() team_a =“阿森纳足球俱乐部” team_b =“利物浦足球俱乐部” h2h = [m 代表数据中的 m[“匹配”] 如果 {m["team1"], m["team2"]} == {team_a, team_b} 和 m.get("score", {}).get("ft")] 对于 h2h 中的 m： ft = m["分数"]["ft"] ht = m["分数"].get("ht", ["?", "?"]) print(f"{m['date']}: {m['team1']} {ft[0]}-{ft[1]} {m['team2']} (HT: {ht[0]}-{ht[1]})") ### 跨季节的汇总统计数据 (Python) 导入请求基=“https://raw.githubusercontent.com/openfootball/football.json/master” 季节 = ["2022-23", "2023-24", "2024-25"] 球队=“曼城足球俱乐部” all_results = {"W": 0, "D": 0, "L": 0, "GF": 0, "GA": 0} 对于季节中的季节： resp = requests.get(f"{base}/{season}/en.1.json") 如果 resp.status_code != 200: 继续数据 = resp.json() 对于 data["matches"] 中的 m： ft = m.get("分数", {}).get("ft") 如果不是英尺：继续如果 m["team1"] == 团队： GF, GA = 英尺 elif m["team2"] == 团队： ga, gf = ft 其他：继续 all_results["GF"] += gf all_results["GA"] += ga 如果 gf > ga： all_results["W"] += 1 elif gf == ga: 所有结果[“D”] += 1 其他：所有结果[“L”] += 1 print(f"{team} across {', '.join(seasons)}:") print(f" W{all_results['W']} D{all_results['D']} L{all_results['L']}") print(f" 进球：{all_results['GF']} 进球，{all_results['GA']} 失球") ### 查找高分比赛（bash + jq） # 查找 2024/25 英超联赛中总进球数超过 5 的所有比赛卷曲-s“https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json”\ | jq -r '.matches[] |选择(.score.ft) |选择((.score.ft[0] + .score.ft[1]) >= 5) | "\(.date) \(.team1) \(.score.ft[0])-\(.score.ft[1]) \(.team2) （总计：\(.score.ft[0] + .score.ft[1]))"' ### 获取特定比赛日的结果 (Python) 导入请求 url =“https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json” 数据 = requests.get(url).json() matchday =“第 38 场比赛” matches = [m for m in data["matches"] if m["round"] == matchday] print(f"--- {比赛日} ---") 对于匹配中的 m： ft = m.get("分数", {}).get("ft") 如果英尺： print(f" {m['date']} {m.get('time', '')} {m['team1']} {ft[0]}-{ft[1]} {m['team2']}") 其他： print(f" {m['date']} {m.get('time', '')} {m['team1']} vs {m['team2']}") ** ** ## 其他存储库（源数据） `football.json` 文件是根据特定国家/地区存储库中的纯文本 Football.TXT 源文件自动生成的：回购|内容 | GitHub 网址 ---|---|--- `英格兰` |英超、冠军、联赛一、联赛二| [openfootball/england]() `德国` |德甲、2. 德甲、3. 西甲、德国杯 | [openfootball/deutschland]() `西班牙` |西甲联赛 | 乙级联赛 | [openfootball/espana]() `意大利` |意甲、意乙、意大利杯| [openfootball/italy]() `法国` |联赛 1、联赛 2 | [openfootball/europe]()（在“/europe”中） “世界杯”| FIFA 世界杯（2022 年、2018 年、2014 年等）| [openfootball/worldcup]() `欧元` | 2024 年、2020 年、2016 年等欧洲杯 | [openfootball/euro]() `冠军联赛` |伦敦大学学院 (UCL) 和欧洲联赛 | [openfootball/champions-league]() `俱乐部` |俱乐部和体育场元数据 | [openfootball/clubs]() `世界` |来自北美、亚洲、非洲、澳大利亚的联赛 | [openfootball/world]() 国家/地区存储库也有自己的 GitHub Pages JSON 镜像。例如： https://openfootball.github.io/england/2024-25/1-premierleague.json 您可以使用 `fbtxt2json` CLI 工具自行将 Football.TXT 源文件转换为 JSON： # 转换单个联赛文件 fbtxt2json 英格兰/2025-26/1-premierleague.txt -o en.1.json # 立即转换整个国家仓库 fbtxt2json 。 -o ./_site ** ** ## 速率限制 GitHub 没有发布原始内容的具体速率限制，而是发布一般准则：指南|推荐 ---|--- 轮询间隔 |对同一文件的请求之间间隔 ≥ 60 秒并发请求 |保持合理（<20并发）缓存 |在本地缓存响应 - 数据很少更改未经身份验证的 GitHub API |每个 IP 每小时 60 个请求（仅适用于 API 端点，不适用于原始内容） > **提示：** 由于比赛数据在比赛结束后不会更改，因此您可以积极缓存历史赛季。仅轮询当前季节的更新。 ** ** ## 错误处理 HTTP 状态 |意义|行动 ---|---|--- 200 | 200成功|解析 JSON 404 | 404找不到文件 |检查赛季、联赛代码或 URL 拼写 429 | 429限价|延迟后退出并重试 5xx |服务器错误 |使用指数退避重试 ** ** ## 提示 * **无需授权** - 所有数据都是完全公开的。立即开始抓取。 * **访问之前检查“分数”** — 未来/未进行的比赛不会有“分数”字段。 * **单独检查`ht`** - 有些匹配有`ft`但没有`ht`数据。 * **球队名称包含后缀** — 例如，“阿森纳足球俱乐部”、“曼联足球俱乐部”、“多特蒙德足球俱乐部”。使用精确的字符串匹配。 * **球队名称因联赛而异** — 德国球队使用德文名称（“FC Bayern München”），英国球队使用英文名称（“Arsenal FC”）。 * **“状态”字段很少见** - 它出现在行政决定的比赛中（例如““已授予””）。 * **积极缓存** - 已完成的赛季永远不会改变。只有当前季节会得到更新。 * **从数据构建表格** - 数据集提供原始匹配结果；您可以计算排名、状态、H2H 等。 * **交叉引用联赛** — 获取多个联赛文件以在不同国家/地区进行比较。 * **公共域 (CC0)** — 随心所欲地使用数据，没有任何限制。 * **不要直接编辑 JSON** — 如果贡献，请编辑国家存储库中的 Football.TXT 源文件； JSON 是自动生成的。 * **时间字段为本地** — “时间”值代表比赛场地的本地开球时间。 * **比分是`[主场、客场]`** — `score.ft[0]` 始终是 `team1`（主场）进球，`score.ft[1]` 始终是 `team2`（客场）进球。 ** ** ## 变更日志 * **0.1.0** — 具有联赛数据访问、JSON 架构文档和常见使用模式的初始版本。

开放式足球

包含技能