openfootball

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

openfootball / football.json API

openfootball is a free, open, public domain collection of football (soccer) data. The football.json repository provides pre-built JSON files for major leagues and tournaments worldwide. No API key or authentication is required.

openfootball是一个免费、开源、公有领域的足球数据集合。football.json仓库为全球主要联赛和赛事提供预构建的JSON文件。无需API密钥或身份验证。

Data Sources

数据来源

There are two ways to access the data:

有两种访问数据的方式：

1. Raw GitHub URLs (Primary)

1. GitHub原始URL（主要方式）

https://raw.githubusercontent.com/openfootball/football.json/master/{season}/{league}.json

https://raw.githubusercontent.com/openfootball/football.json/master/{season}/{league}.json

2. GitHub Pages Mirror

2. GitHub Pages镜像

https://openfootball.github.io/{country}/{season}/{league-name}.json

Recommendation: Use the raw GitHub URLs for the
football.json
repo — they use a simple, consistent naming convention and are the most reliable.

https://openfootball.github.io/{country}/{season}/{league-name}.json

推荐： 使用football.json仓库的GitHub原始URL——它们采用简单、一致的命名规则，且最可靠。

URL Structure

URL结构

https://raw.githubusercontent.com/openfootball/football.json/master/{season}/{code}.json

Component	Description	Examples
`{season}`	Season directory — cross-year or calendar year	`2024-25` , `2023-24` , `2025` , `2019`
`{code}`	League code in `{country}.{division}` format	`en.1` , `de.1` , `es.1` , `it.1` , `fr.1`

https://raw.githubusercontent.com/openfootball/football.json/master/{season}/{code}.json

组成部分	描述	示例
`{season}`	赛季目录——跨年度或自然年度	`2024-25` , `2023-24` , `2025` , `2019`
`{code}`	联赛代码，格式为 `{country}.{division}`	`en.1` , `de.1` , `es.1` , `it.1` , `fr.1`

Available Leagues

可用联赛

England

英格兰

Code	League	Tier
`en.1`	English Premier League	1st division
`en.2`	English Championship	2nd division
`en.3`	English League One	3rd division
`en.4`	English League Two	4th division

代码	联赛	级别
`en.1`	英超联赛	第一级别
`en.2`	英冠联赛	第二级别
`en.3`	英甲联赛	第三级别
`en.4`	英乙联赛	第四级别

Germany

德国

Code	League	Tier
`de.1`	Deutsche Bundesliga	1st division
`de.2`	2. Bundesliga	2nd division
`de.3`	3. Liga	3rd division

代码	联赛	级别
`de.1`	德甲联赛	第一级别
`de.2`	德乙联赛	第二级别
`de.3`	德丙联赛	第三级别

Spain

西班牙

Code	League	Tier
`es.1`	Primera División (La Liga)	1st division
`es.2`	Segunda División	2nd division

代码	联赛	级别
`es.1`	西甲联赛	第一级别
`es.2`	西乙联赛	第二级别

Italy

意大利

Code	League	Tier
`it.1`	Serie A	1st division
`it.2`	Serie B	2nd division

代码	联赛	级别
`it.1`	意甲联赛	第一级别
`it.2`	意乙联赛	第二级别

France

法国

Code	League	Tier
`fr.1`	Ligue 1	1st division
`fr.2`	Ligue 2	2nd division

Note: Not all leagues are available for all seasons. The
football.json
repo is continuously updated — check the repository for the full list of available files.

代码	联赛	级别
`fr.1`	法甲联赛	第一级别
`fr.2`	法乙联赛	第二级别

注意： 并非所有赛季都提供所有联赛的数据。football.json仓库会持续更新——请查看仓库获取完整的可用文件列表。

Available Seasons

可用赛季

Season directories in the

football.json

repo go back to

2010-11

. European leagues use cross-year format (

2024-25

), while some calendar-year leagues use single-year format (

Format	Usage	Examples
`YYYY-YY`	European club seasons (Aug–May)	`2024-25` , `2023-24` , `2015-16`
`YYYY`	Calendar-year competitions	`2025` , `2020` , `2019`

Known season directories:

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

football.json仓库中的赛季目录最早可追溯至

2010-11

。欧洲联赛采用跨年度格式（

2024-25

），而部分自然年度联赛采用单年度格式（

）。

格式	用途	示例
`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

JSON Response Format

JSON响应格式

All files follow the same JSON schema:

json

{
  "name": "English Premier League 2024/25",
  "matches": [
    {
      "round": "Matchday 1",
      "date": "2024-08-16",
      "time": "20:00",
      "team1": "Manchester United FC",
      "team2": "Fulham FC",
      "score": {
        "ht": [0, 0],
        "ft": [1, 0]
      }
    }
  ]
}

所有文件遵循相同的JSON schema：

json

{
  "name": "English Premier League 2024/25",
  "matches": [
    {
      "round": "Matchday 1",
      "date": "2024-08-16",
      "time": "20:00",
      "team1": "Manchester United FC",
      "team2": "Fulham FC",
      "score": {
        "ht": [0, 0],
        "ft": [1, 0]
      }
    }
  ]
}

Top-Level Fields

顶级字段

Field	Type	Description
`name`	string	Human-readable league name and season
`matches`	array	Array of match objects

字段	类型	描述
`name`	字符串	易读的联赛名称和赛季
`matches`	数组	比赛对象数组

Match Object Fields

比赛对象字段

Field	Type	Required	Description
`round`	string	Yes	Round/matchday name (e.g., `"Matchday 1"` , `"Round of 16"` )
`date`	string	Yes	Match date in `YYYY-MM-DD` format
`time`	string	No	Kick-off time in `HH:MM` format (24-hour, local time)
`team1`	string	Yes	Home team name
`team2`	string	Yes	Away team name
`score`	object	No	Score object (absent for unplayed future matches)
`status`	string	No	Special status (e.g., `"awarded"` for administratively decided results)

字段	类型	必填	描述
`round`	字符串	是	轮次/比赛日名称（例如 `"Matchday 1"` , `"Round of 16"` ）
`date`	字符串	是	比赛日期，格式为 `YYYY-MM-DD`
`time`	字符串	否	开球时间，格式为 `HH:MM` （24小时制，当地时间）
`team1`	字符串	是	主队名称
`team2`	字符串	是	客队名称
`score`	对象	否	比分对象（未开赛的未来比赛无此字段）
`status`	字符串	否	特殊状态（例如 `"awarded"` 表示由官方判定的赛果）

Score Object Fields

比分对象字段

Field	Type	Description
`ft`	`[int, int]`	Full-time score `[home, away]`
`ht`	`[int, int]`	Half-time score `[home, away]` (may be absent for some matches)

Note: Some matches only have
ft
(full-time) without
ht
(half-time). Always check for the presence of
ht
before accessing it.

字段	类型	描述
`ft`	`[int, int]`	全场比分 `[主队, 客队]`
`ht`	`[int, int]`	半场比分 `[主队, 客队]` （部分比赛可能无此字段）

注意： 部分比赛仅包含
ft
（全场比分），没有
ht
（半场比分）。访问
ht
前请务必检查其是否存在。

Common Patterns

常见用法示例

Fetch a League Season (curl)

获取某赛季联赛数据（curl）

bash

curl -s "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json" | jq .

bash

curl -s "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json" | jq .

Fetch and Parse Match Data (Python)

获取并解析比赛数据（Python）

python

import requests

url = "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json"
data = requests.get(url).json()

print(f"League: {data['name']}")
print(f"Total matches: {len(data['matches'])}")

for match in data["matches"][:10]:
    ft = match.get("score", {}).get("ft")
    if ft:
        print(f"  {match['date']}  {match['team1']} {ft[0]}-{ft[1]} {match['team2']}")
    else:
        print(f"  {match['date']}  {match['team1']} vs {match['team2']} (no score)")

python

import requests

url = "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json"
data = requests.get(url).json()

print(f"League: {data['name']}")
print(f"Total matches: {len(data['matches'])}")

for match in data["matches"][:10]:
    ft = match.get("score", {}).get("ft")
    if ft:
        print(f"  {match['date']}  {match['team1']} {ft[0]}-{ft[1]} {match['team2']}")
    else:
        print(f"  {match['date']}  {match['team1']} vs {match['team2']} (no score)")

Build a League Table from Results (Python)

从赛果生成联赛积分榜（Python）

python

import requests
from collections import defaultdict

url = "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json"
data = requests.get(url).json()

table = defaultdict(lambda: {"played": 0, "won": 0, "drawn": 0, "lost": 0,
                              "gf": 0, "ga": 0, "points": 0})

for match in data["matches"]:
    score = match.get("score", {}).get("ft")
    if not score:
        continue

    t1, t2 = match["team1"], match["team2"]
    g1, g2 = score

    for team, gf, ga in [(t1, g1, g2), (t2, g2, g1)]:
        table[team]["played"] += 1
        table[team]["gf"] += gf
        table[team]["ga"] += ga
        if gf > ga:
            table[team]["won"] += 1
            table[team]["points"] += 3
        elif gf == ga:
            table[team]["drawn"] += 1
            table[team]["points"] += 1
        else:
            table[team]["lost"] += 1

python

import requests
from collections import defaultdict

url = "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json"
data = requests.get(url).json()

table = defaultdict(lambda: {"played": 0, "won": 0, "drawn": 0, "lost": 0,
                              "gf": 0, "ga": 0, "points": 0})

for match in data["matches"]:
    score = match.get("score", {}).get("ft")
    if not score:
        continue

    t1, t2 = match["team1"], match["team2"]
    g1, g2 = score

    for team, gf, ga in [(t1, g1, g2), (t2, g2, g1)]:
        table[team]["played"] += 1
        table[team]["gf"] += gf
        table[team]["ga"] += ga
        if gf > ga:
            table[team]["won"] += 1
            table[team]["points"] += 3
        elif gf == ga:
            table[team]["drawn"] += 1
            table[team]["points"] += 1
        else:
            table[team]["lost"] += 1

Sort by points, then goal difference

按积分排序，积分相同则按净胜球排序

sorted_table = sorted(table.items(), key=lambda x: (x[1]["points"], x[1]["gf"] - x[1]["ga"]), reverse=True)

print(f"{'Team':<35} {'P':>3} {'W':>3} {'D':>3} {'L':>3} {'GF':>4} {'GA':>4} {'GD':>4} {'Pts':>4}") print("-" * 70) for i, (team, stats) in enumerate(sorted_table, 1): gd = stats["gf"] - stats["ga"] print(f"{i:>2}. {team:<32} {stats['played']:>3} {stats['won']:>3} " f"{stats['drawn']:>3} {stats['lost']:>3} {stats['gf']:>4} " f"{stats['ga']:>4} {gd:>+4} {stats['points']:>4}")

undefined

sorted_table = sorted(table.items(), key=lambda x: (x[1]["points"], x[1]["gf"] - x[1]["ga"]), reverse=True)

undefined

Filter Matches by Team (Python)

按球队筛选比赛（Python）

python

import requests

url = "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json"
data = requests.get(url).json()

team = "Arsenal FC"
matches = [m for m in data["matches"]
           if team in (m["team1"], m["team2"]) and m.get("score", {}).get("ft")]

for m in matches:
    ft = m["score"]["ft"]
    opponent = m["team2"] if m["team1"] == team else m["team1"]
    venue = "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]
    result = "W" if my_goals > opp_goals else ("D" if my_goals == opp_goals else "L")
    print(f"  {m['date']} ({venue}) {result} {my_goals}-{opp_goals} vs {opponent}")

python

import requests

url = "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json"
data = requests.get(url).json()

team = "Arsenal FC"
matches = [m for m in data["matches"]
           if team in (m["team1"], m["team2"]) and m.get("score", {}).get("ft")]

for m in matches:
    ft = m["score"]["ft"]
    opponent = m["team2"] if m["team1"] == team else m["team1"]
    venue = "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]
    result = "W" if my_goals > opp_goals else ("D" if my_goals == opp_goals else "L")
    print(f"  {m['date']} ({venue}) {result} {my_goals}-{opp_goals} vs {opponent}")

Fetch Multiple Leagues (Python)

获取多个联赛数据（Python）

python

import requests

leagues = {
    "Premier League": "en.1",
    "Bundesliga": "de.1",
    "La Liga": "es.1",
    "Serie A": "it.1",
    "Ligue 1": "fr.1",
}

season = "2024-25"
base = "https://raw.githubusercontent.com/openfootball/football.json/master"

for name, code in leagues.items():
    url = f"{base}/{season}/{code}.json"
    resp = requests.get(url)
    if resp.status_code == 200:
        data = resp.json()
        total = len(data["matches"])
        played = sum(1 for m in data["matches"] if m.get("score", {}).get("ft"))
        print(f"{name}: {played}/{total} matches played")
    else:
        print(f"{name}: not available for {season}")

python

import requests

leagues = {
    "Premier League": "en.1",
    "Bundesliga": "de.1",
    "La Liga": "es.1",
    "Serie A": "it.1",
    "Ligue 1": "fr.1",
}

season = "2024-25"
base = "https://raw.githubusercontent.com/openfootball/football.json/master"

for name, code in leagues.items():
    url = f"{base}/{season}/{code}.json"
    resp = requests.get(url)
    if resp.status_code == 200:
        data = resp.json()
        total = len(data["matches"])
        played = sum(1 for m in data["matches"] if m.get("score", {}).get("ft"))
        print(f"{name}: {played}/{total} matches played")
    else:
        print(f"{name}: not available for {season}")

Fetch and Parse (Node.js)

获取并解析数据（Node.js）

javascript

const url = "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json";

const res = await fetch(url);
const data = await res.json();

console.log(`League: ${data.name}`);
console.log(`Matches: ${data.matches.length}`);

data.matches.slice(0, 10).forEach((m) => {
  const ft = m.score?.ft;
  if (ft) {
    console.log(`  ${m.date}  ${m.team1} ${ft[0]}-${ft[1]} ${m.team2}`);
  }
});

javascript

const url = "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json";

const res = await fetch(url);
const data = await res.json();

console.log(`League: ${data.name}`);
console.log(`Matches: ${data.matches.length}`);

data.matches.slice(0, 10).forEach((m) => {
  const ft = m.score?.ft;
  if (ft) {
    console.log(`  ${m.date}  ${m.team1} ${ft[0]}-${ft[1]} ${m.team2}`);
  }
});

Fetch and Parse (bash + jq)

获取并解析数据（bash + jq）

bash

undefined

bash

undefined

Get all results for a specific team

curl -s "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json"
| jq -r '.matches[] | select(.team1 == "Liverpool FC" or .team2 == "Liverpool FC") | select(.score.ft) | "(.date) (.team1) (.score.ft[0])-(.score.ft[1]) (.team2)"'

undefined

undefined

Compare Head-to-Head Results (Python)

对比两队交锋记录（Python）

python

import requests

url = "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json"
data = requests.get(url).json()

team_a = "Arsenal FC"
team_b = "Liverpool FC"

h2h = [m for m in data["matches"]
       if {m["team1"], m["team2"]} == {team_a, team_b}
       and m.get("score", {}).get("ft")]

for m in h2h:
    ft = m["score"]["ft"]
    ht = m["score"].get("ht", ["?", "?"])
    print(f"{m['date']}: {m['team1']} {ft[0]}-{ft[1]} {m['team2']} (HT: {ht[0]}-{ht[1]})")

python

import requests

url = "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json"
data = requests.get(url).json()

team_a = "Arsenal FC"
team_b = "Liverpool FC"

h2h = [m for m in data["matches"]
       if {m["team1"], m["team2"]} == {team_a, team_b}
       and m.get("score", {}).get("ft")]

for m in h2h:
    ft = m["score"]["ft"]
    ht = m["score"].get("ht", ["?", "?"])
    print(f"{m['date']}: {m['team1']} {ft[0]}-{ft[1]} {m['team2']} (HT: {ht[0]}-{ht[1]})")

Aggregate Stats Across Seasons (Python)

跨赛季统计数据（Python）

python

import requests

base = "https://raw.githubusercontent.com/openfootball/football.json/master"
seasons = ["2022-23", "2023-24", "2024-25"]
team = "Manchester City FC"
all_results = {"W": 0, "D": 0, "L": 0, "GF": 0, "GA": 0}

for season in seasons:
    resp = requests.get(f"{base}/{season}/en.1.json")
    if resp.status_code != 200:
        continue
    data = resp.json()
    for m in data["matches"]:
        ft = m.get("score", {}).get("ft")
        if not ft:
            continue
        if m["team1"] == team:
            gf, ga = ft
        elif m["team2"] == team:
            ga, gf = ft
        else:
            continue
        all_results["GF"] += gf
        all_results["GA"] += ga
        if gf > ga:
            all_results["W"] += 1
        elif gf == ga:
            all_results["D"] += 1
        else:
            all_results["L"] += 1

print(f"{team} across {', '.join(seasons)}:")
print(f"  W{all_results['W']} D{all_results['D']} L{all_results['L']}")
print(f"  Goals: {all_results['GF']} scored, {all_results['GA']} conceded")

python

import requests

base = "https://raw.githubusercontent.com/openfootball/football.json/master"
seasons = ["2022-23", "2023-24", "2024-25"]
team = "Manchester City FC"
all_results = {"W": 0, "D": 0, "L": 0, "GF": 0, "GA": 0}

for season in seasons:
    resp = requests.get(f"{base}/{season}/en.1.json")
    if resp.status_code != 200:
        continue
    data = resp.json()
    for m in data["matches"]:
        ft = m.get("score", {}).get("ft")
        if not ft:
            continue
        if m["team1"] == team:
            gf, ga = ft
        elif m["team2"] == team:
            ga, gf = ft
        else:
            continue
        all_results["GF"] += gf
        all_results["GA"] += ga
        if gf > ga:
            all_results["W"] += 1
        elif gf == ga:
            all_results["D"] += 1
        else:
            all_results["L"] += 1

print(f"{team} across {', '.join(seasons)}:")
print(f"  W{all_results['W']} D{all_results['D']} L{all_results['L']}")
print(f"  Goals: {all_results['GF']} scored, {all_results['GA']} conceded")

Find High-Scoring Matches (bash + jq)

寻找高进球数比赛（bash + jq）

bash

undefined

bash

undefined

Find all matches with 5+ total goals in the Premier League 2024/25

curl -s "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json"
| jq -r '.matches[] | select(.score.ft) | select((.score.ft[0] + .score.ft[1]) >= 5) | "(.date) (.team1) (.score.ft[0])-(.score.ft[1]) (.team2) (Total: (.score.ft[0] + .score.ft[1]))"'

undefined

undefined

Get Results for a Specific Matchday (Python)

获取特定比赛日赛果（Python）

python

import requests

url = "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json"
data = requests.get(url).json()

matchday = "Matchday 38"
matches = [m for m in data["matches"] if m["round"] == matchday]

print(f"--- {matchday} ---")
for m in matches:
    ft = m.get("score", {}).get("ft")
    if ft:
        print(f"  {m['date']} {m.get('time', '')}  {m['team1']} {ft[0]}-{ft[1]} {m['team2']}")
    else:
        print(f"  {m['date']} {m.get('time', '')}  {m['team1']} vs {m['team2']}")

python

import requests

url = "https://raw.githubusercontent.com/openfootball/football.json/master/2024-25/en.1.json"
data = requests.get(url).json()

matchday = "Matchday 38"
matches = [m for m in data["matches"] if m["round"] == matchday]

print(f"--- {matchday} ---")
for m in matches:
    ft = m.get("score", {}).get("ft")
    if ft:
        print(f"  {m['date']} {m.get('time', '')}  {m['team1']} {ft[0]}-{ft[1]} {m['team2']}")
    else:
        print(f"  {m['date']} {m.get('time', '')}  {m['team1']} vs {m['team2']}")

Other Repositories (Source Data)

其他仓库（数据源）

The

football.json

files are auto-generated from plain-text Football.TXT source files in country-specific repos:

Repo	Content	GitHub URL
`england`	EPL, Championship, League One, League Two	openfootball/england
`deutschland`	Bundesliga, 2. Bundesliga, 3. Liga, DFB Pokal	openfootball/deutschland
`espana`	La Liga, Segunda División	openfootball/espana
`italy`	Serie A, Serie B, Coppa Italia	openfootball/italy
`france`	Ligue 1, Ligue 2	openfootball/europe (in `/europe` )
`worldcup`	FIFA World Cup (2022, 2018, 2014, etc.)	openfootball/worldcup
`euro`	Euro 2024, 2020, 2016, etc.	openfootball/euro
`champions-league`	UCL & Europa League	openfootball/champions-league
`clubs`	Club & stadium metadata	openfootball/clubs
`world`	Leagues from N. America, Asia, Africa, Australia	openfootball/world

Country repos also have their own GitHub Pages JSON mirrors. For example:

https://openfootball.github.io/england/2024-25/1-premierleague.json

You can convert Football.TXT source files to JSON yourself using the

fbtxt2json

CLI tool:

bash

undefined

football.json文件是从特定国家仓库中的纯文本Football.TXT源文件自动生成的：

仓库	内容	GitHub地址
`england`	英超、英冠、英甲、英乙	openfootball/england
`deutschland`	德甲、德乙、德丙、德国杯	openfootball/deutschland
`espana`	西甲、西乙	openfootball/espana
`italy`	意甲、意乙、意大利杯	openfootball/italy
`france`	法甲、法乙	openfootball/europe（位于 `/europe` 目录）
`worldcup`	世界杯（2022、2018、2014等）	openfootball/worldcup
`euro`	欧洲杯2024、2020、2016等	openfootball/euro
`champions-league`	欧冠及欧联杯	openfootball/champions-league
`clubs`	俱乐部及球场元数据	openfootball/clubs
`world`	北美、亚洲、非洲、澳洲的联赛	openfootball/world

国家仓库也有自己的GitHub Pages JSON镜像。例如：

https://openfootball.github.io/england/2024-25/1-premierleague.json

你可以使用

fbtxt2json

CLI工具将Football.TXT源文件自行转换为JSON格式：

bash

undefined

Convert a single league file

fbtxt2json england/2025-26/1-premierleague.txt -o en.1.json

Convert an entire country repo at once

fbtxt2json . -o ./_site

---

fbtxt2json . -o ./_site

---

Rate Limits

请求限制

GitHub does not publish specific rate limits for raw content, but general guidelines:

Guideline	Recommendation
Polling interval	≥ 60 seconds between requests for the same file
Concurrent requests	Keep reasonable (< 20 concurrent)
Caching	Cache responses locally — data changes infrequently
Unauthenticated GitHub API	60 requests/hour per IP (only applies to API endpoints, not raw content)

Tip: Since match data doesn't change after a game is completed, you can aggressively cache historical seasons. Only poll the current season for updates.

GitHub未公布原始内容的具体请求限制，但有以下通用准则：

准则	建议
轮询间隔	同一文件的请求间隔≥60秒
并发请求	保持合理数量（<20个并发）
缓存	本地缓存响应——数据更新频率低
未认证GitHub API	每IP每小时60次请求（仅适用于API端点，不适用于原始内容）

提示： 比赛结束后数据不会再更改，因此可以积极缓存历史赛季的数据仅需轮询当前赛季以获取更新。

Error Handling

错误处理

HTTP Status	Meaning	Action
200	Success	Parse the JSON
404	File not found	Check the season, league code, or URL spelling
429	Rate limited	Back off and retry after a delay
5xx	Server error	Retry with exponential backoff

HTTP状态码	含义	操作
200	请求成功	解析JSON数据
404	文件不存在	检查赛季、联赛代码或URL拼写
429	请求受限	暂停请求并延迟后重试
5xx	服务器错误	使用指数退避策略重试

Tips

提示

No auth needed — all data is fully public. Start fetching immediately.
Check for
score
before accessing — future/unplayed matches won't have a
```
score
```
field.
Check for
ht
separately — some matches have
```
ft
```
but no
```
ht
```
data.
Team names include suffixes — e.g.,
```
"Arsenal FC"
```
,
```
"Manchester United FC"
```
,
```
"Borussia Dortmund"
```
. Use exact string matching.
Team names vary by league — German teams use German names (
```
"FC Bayern München"
```
), English teams use English names (
```
"Arsenal FC"
```
).
The
status
field is rare — it appears on administratively decided matches (e.g.,
```
"awarded"
```
).
Cache aggressively — completed seasons never change. Only the current season gets updates.
Build tables from the data — the dataset provides raw match results; you compute standings, form, H2H, etc.
Cross-reference leagues — fetch multiple league files to compare across countries.
Public domain (CC0) — use the data however you want with no restrictions whatsoever.
Don't edit the JSON directly — if contributing, edit the Football.TXT source files in the country repos; JSON is auto-generated.
Time field is local — the
```
time
```
value represents the local kick-off time for the match venue.
Scores are
[home, away]
—
```
score.ft[0]
```
is always the
```
team1
```
(home) goals,
```
score.ft[1]
```
is always the
```
team2
```
(away) goals.

无需身份验证——所有数据完全公开，可立即开始获取。
访问前检查
score
字段——未来/未开赛的比赛没有
```
score
```
字段。
单独检查
ht
字段——部分比赛有
```
ft
```
但无
```
ht
```
数据。
球队名称包含后缀——例如
```
"Arsenal FC"
```
,
```
"Manchester United FC"
```
,
```
"Borussia Dortmund"
```
。请使用精确字符串匹配。
球队名称因联赛而异——德国球队使用德语名称（
```
"FC Bayern München"
```
），英格兰球队使用英语名称（
```
"Arsenal FC"
```
）。
status
字段很少出现——仅在官方判定的比赛中出现（例如
```
"awarded"
```
）。
积极缓存数据——已结束的赛季数据不会更改仅需更新当前赛季的数据。
从数据生成积分榜——数据集提供原始比赛结果；你需要自行计算排名、状态、交锋记录等。
跨联赛对比——获取多个联赛文件以进行跨国对比。
公有领域（CC0）——可自由使用数据，无任何限制。
不要直接编辑JSON文件——若要贡献内容，请编辑国家仓库中的Football.TXT源文件；JSON文件是自动生成的。
时间字段为当地时间——
```
time
```
值表示比赛场地的当地开球时间。
比分格式为
[主队, 客队]
——
```
score.ft[0]
```
始终是
```
team1
```
（主队）进球数，
```
score.ft[1]
```
始终是
```
team2
```
（客队）进球数。

Changelog

更新日志

0.1.0 — Initial release with league data access, JSON schema documentation, and common usage patterns.

0.1.0 —— 初始版本，包含联赛数据访问、JSON schema文档及常见用法示例。