openfootball

openfootball / football.json API

openfootball は、サッカーのデータを集めた無料のオープンなパブリックドメインのコレクションです。football.json リポジトリでは、世界各地の主要リーグや大会の、あらかじめ作成された JSON ファイルを提供しています。API キーや認証は不要です。

---

データソース

データにアクセスする方法は 2 つあります。

1. GitHub の Raw URL（主要な方法）

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

2. GitHub Pages ミラー

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

推奨： football.json リポジトリでは GitHub の Raw URL を使用してください。シンプルで一貫した命名規則が採用されており、最も信頼性が高いためです。

---

URL の構造

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

---

利用可能なリーグ

イングランド

コード	リーグ	ディビジョン
en.1	イングランド・プレミアリーグ	1 部
en.2	イングランド・チャンピオンシップ	2 部
en.3	イングランド・リーグ・ワン	3 部
en.4	イングランド・リーグ・ツー	4 部

ドイツ

コード	リーグ	ディビジョン
de.1	ドイツ・ブンデスリーガ	1 部
de.2	2. ブンデスリーガ	2 部
de.3	3. リーガ	3 部

スペイン

コード	リーグ	ディビジョン
es.1	プリメーラ・ディビシオン（ラ・リーガ）	1 部
es.2	セグンダ・ディビシオン	2 部

イタリア

コード	リーグ	ディビジョン
it.1	セリエ A	1 部
it.2	セリエ B	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": "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]
      }
    }
  ]
}

トップレベルのフィールド

フィールド	型	説明
name	string	人が読み取れる形式のリーグ名とシーズン
matches	array	試合オブジェクトの配列

試合オブジェクトのフィールド

フィールド	型	必須	説明
round	string	はい	ラウンド／節の名称（例："Matchday 1"、"Round of 16"）
date	string	はい	YYYY-MM-DD 形式の試合日
time	string	いいえ	HH:MM 形式のキックオフ時刻（24 時間表記、現地時間）
team1	string	はい	ホームチーム名
team2	string	はい	アウェイチーム名
score	object	いいえ	スコアオブジェクト（未実施の将来の試合では存在しません）
status	string	いいえ	特別なステータス（例：事務手続きにより結果が決定された場合の "awarded"）

スコアオブジェクトのフィールド

フィールド	型	説明
ft	[int, int]	フルタイムのスコア [home, away]
ht	[int, int]	ハーフタイムのスコア [home, away]（一部の試合では存在しない場合があります）

注： 一部の試合では、ハーフタイムの ht がなく、フルタイムの ft のみが記録されています。アクセスする前に、必ず ht が存在するか確認してください。

---

よくあるパターン

リーグのシーズンを取得する（curl）

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

試合データを取得して解析する（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
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}")

チームで試合を絞り込む（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

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

取得して解析する（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}`);
  }
});

取得して解析する（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)"'

直接対決の結果を比較する（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

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

得点の多い試合を見つける（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]))"'

特定の節の試合結果を取得する（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']}")

---

その他のリポジトリ（ソースデータ）

football.json ファイルは、国別リポジトリにあるプレーンテキスト形式の Football.TXT ソースファイルから自動生成されます。

リポジトリ	内容	GitHub URL
england	EPL、チャンピオンシップ、リーグ・ワン、リーグ・ツー	openfootball/england
deutschland	ブンデスリーガ、2. ブンデスリーガ、3. リーガ、DFB ポカール	openfootball/deutschland
espana	ラ・リーガ、セグンダ・ディビシオン	openfootball/espana
italy	セリエ A、セリエ B、コッパ・イタリア	openfootball/italy
france	リーグ・アン、リーグ・ドゥ	openfootball/europe（/europe 内）
worldcup	FIFA ワールドカップ（2022、2018、2014 など）	openfootball/worldcup
euro	EURO 2024、2020、2016 など	openfootball/euro
champions-league	UCL、ヨーロッパリーグ	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 に変換できます。

# 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

---

レート制限

GitHub は raw コンテンツの具体的なレート制限を公開していませんが、一般的なガイドラインは次のとおりです。

ガイドライン	推奨事項
ポーリング間隔	同じファイルへのリクエスト間隔を 60 秒以上にする
同時リクエスト数	適切な範囲に保つ（同時実行数は 20 未満）
キャッシュ	レスポンスをローカルにキャッシュする — データは頻繁には変更されません
認証なしの GitHub API	IP あたり 1 時間に 60 リクエスト（API エンドポイントのみに適用され、raw コンテンツには適用されません）

Tip: 試合データは試合終了後に変更されないため、過去のシーズンは積極的にキャッシュできます。更新確認のためのポーリングは、現行シーズンのみにしてください。

---

エラー処理

HTTP ステータス	意味	対応
200	成功	JSON を解析する
404	ファイルが見つかりません	シーズン、リーグコード、URL のスペルを確認する
429	レート制限	待機してから再試行する
5xx	サーバーエラー	指数バックオフを使って再試行する

---

ヒント

• 認証は不要です — すべてのデータは完全に公開されています。すぐに取得を開始できます。
• アクセスする前に 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 の値は、試合会場の現地キックオフ時刻を表します。
• スコアは [home, away] の形式です — score.ft[0] は常に team1（ホーム）の得点、score.ft[1] は常に team2（アウェイ）の得点です。

---

変更履歴

• 0.1.0 — リーグデータへのアクセス、JSONスキーマのドキュメント、一般的な使用パターンを含む初回リリース。