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.

---

Data Sources

There are two ways to access the data:

1. Raw GitHub URLs (Primary)

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

2. GitHub Pages Mirror

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.

---

URL Structure

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

---

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

Germany

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

Spain

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

Italy

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

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.

---

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 (2025).

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, 2019, 2020, 2025.

---

JSON Response Format

All files follow the same JSON schema:

{
  "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

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)

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.

---

Common Patterns

Fetch a League Season (curl)

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

Fetch and Parse Match Data (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)

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}")

Filter Matches by Team (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)

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)

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)

# 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)"'

Compare Head-to-Head Results (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)

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)

# 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]))"'

Get Results for a Specific Matchday (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:

# 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

---

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.

---

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

---

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.

---

Changelog

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