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.