Go to Qiita Advent Calendar Top
LoginSignup
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Day 5

個人 Advent Calendar 2025

@lamela

football-data.org API ガイド

Posted at

概要

欧州サッカー好きエンジニアの皆さん、自分のコーディング能力を自分の趣味に活用したくないですか？

football-data.org API を使えば、欧州5大リーグをはじめとした、世界中のサッカーリーグのデータを簡単に取得できます。

ここでは、Pythonでfootball-data.org APIを使う方法をチュートリアル形式で解説していきたいと思います。


football-data.org APIとは

football-data.org が提供する、サッカーの試合や順位表などのデータを取得できるREST APIです。


料金プラン

  • 無料プランの場合、10リクエスト/分まで可能

詳細は公式サイトにて


セットアップ

1. APIキーの取得

まず、football-data.orgでアカウントを作成し、APIキーを取得します。

  1. 上記リンクからアカウント登録
  2. メールアドレスを確認
  3. メール内にトークンが記載されている

2. ヘッダー設定

以下のようにヘッダーの設定をしましょう。

# ヘッダー設定
HEADERS = {
    'X-Auth-Token': API_KEY
}

基本的な使い方

API呼び出し関数の作成

まず、API呼び出しをする関数を作成

def fetch_data(endpoint, filters=None):
    url = f"{BASE_URL}{endpoint}"
    try:
        response = requests.get(url, headers=HEADERS, params=filters)
        response.raise_for_status()  # エラーチェック
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"API呼び出し失敗: {url}: {e}")
        return None

def print_pretty(data):
    """JSONデータを整形して表示"""
    if data:
        print(json.dumps(data, indent=2, ensure_ascii=False))
    else:
        print("データ取得失敗！！！")

エンドポイント詳細解説

football-data.org APIは、5つのメインリソースを提供しています。

1. エリア (Areas)

国や地域のデータを取得できます。

全エリアの取得

def get_areas():
    """利用可能なすべてのエリアを一覧表示"""
    print("\n--- All Areas ---")
    return fetch_data('/areas/')

# 使用例
areas = get_areas()
print_pretty(areas)

特定エリアの取得

def get_area_by_id(area_id):
    """特定のエリアを表示"""
    print(f"\n--- Fetching Area ID: {area_id} ---")
    return fetch_data(f'/areas/{area_id}')

# 使用例: イングランドの情報を取得
area = get_area_by_id(2072)  # 2072 = England
print_pretty(area)

2. 大会 (Competitions)

リーグや大会の情報を取できます。

全大会の取得

def get_competitions(areas=None):
    """
    利用可能なすべての大会を一覧表示
    """
    print("\n--- All Competitions ---")
    filters = {}
    if areas:
        filters['areas'] = areas
    return fetch_data('/competitions/', filters)

# 使用例
competitions = get_competitions()
print_pretty(competitions)

特定大会のシーズン取得

def get_competition_by_id(comp_id):
    """特定の大会のシーズンを表示"""
    print(f"\n--- Competition ID: {comp_id} ---")
    return fetch_data(f'/competitions/{comp_id}')

# 使用例: プレミアリーグのシーズン情報を取得
pl = get_competition_by_id('PL')
print_pretty(pl)

順位表の取得

def get_standings(comp_id, season=None, matchday=None, date=None):
    """特定の大会の順位表を表示"""
    print(f"\n--- Fetching Standings for {comp_id} ---")
    filters = {}
    if season: filters['season'] = season
    if matchday: filters['matchday'] = matchday
    if date: filters['date'] = date
    return fetch_data(f'/competitions/{comp_id}/standings', filters)

# 使用例: プレミアリーグの現在の順位表
standings = get_standings('PL')
print_pretty(standings)

# 特定の節の順位表
standings_md11 = get_standings('PL', matchday=11)
print_pretty(standings_md11)

大会の試合一覧

def get_competition_matches(comp_id, date_from=None, date_to=None, 
                           stage=None, status=None, matchday=None, 
                           group=None, season=None):
    """特定の大会のすべての試合を一覧表示"""
    print(f"\n--- Fetching Matches for {comp_id} ---")
    filters = {
        'dateFrom': date_from,
        'dateTo': date_to,
        'stage': stage,
        'status': status,
        'matchday': matchday,
        'group': group,
        'season': season
    }
    # Noneの値を除外
    filters = {k: v for k, v in filters.items() if v is not None}
    return fetch_data(f'/competitions/{comp_id}/matches', filters)

# 使用例: プレミアリーグの第1節の試合
matches = get_competition_matches('PL', matchday=1)
print_pretty(matches)

# 期間指定で取得
matches = get_competition_matches('PL', 
                                 date_from='2024-01-01', 
                                 date_to='2024-01-31')
print_pretty(matches)

大会のチームの選手一覧

def get_competition_teams(comp_id, season=None):
    """特定の大会のすべてのチームの選手を一覧表示"""
    print(f"\n--- Fetching Teams for {comp_id} ---")
    filters = {}
    if season: filters['season'] = season
    return fetch_data(f'/competitions/{comp_id}/teams', filters)

# 使用例
teams = get_competition_teams('PL')
print_pretty(teams)

得点ランキング

def get_top_scorers(comp_id, limit=None, season=None):
    """特定の大会の得点ランキングを表示"""
    print(f"\n--- Fetching Top Scorers for {comp_id} ---")
    filters = {}
    if limit: filters['limit'] = limit
    if season: filters['season'] = season
    return fetch_data(f'/competitions/{comp_id}/scorers', filters)

# 使用例: セリエAの得点王争い (上位10名)
scorers = get_top_scorers('SA', limit=10)
print_pretty(scorers)

3. チーム (Teams)

チームの情報と試合履歴を取得します。

チーム一覧の取得

def get_teams(limit=None, offset=None):
    """チームを一覧表示"""
    print("\n--- Fetching Teams ---")
    filters = {}
    if limit: filters['limit'] = limit
    if offset: filters['offset'] = offset
    return fetch_data('/teams/', filters)

# 使用例
teams = get_teams(limit=20)
print_pretty(teams)

特定チームの情報

def get_team_by_id(team_id):
    """特定のチームを表示"""
    print(f"\n--- Fetching Team ID: {team_id} ---")
    return fetch_data(f'/teams/{team_id}')

# 使用例: レアル・マドリードの情報
real_madrid = get_team_by_id(86)
print_pretty(real_madrid)

チームの試合履歴

def get_team_matches(team_id, date_from=None, date_to=None, 
                    season=None, competitions=None, status=None, 
                    venue=None, limit=None):
    """特定のチームのすべての試合を表示"""
    print(f"\n--- Fetching Matches for Team ID: {team_id} ---")
    filters = {
        'dateFrom': date_from,
        'dateTo': date_to,
        'season': season,
        'competitions': competitions,
        'status': status,
        'venue': venue,
        'limit': limit
    }
    filters = {k: v for k, v in filters.items() if v is not None}
    return fetch_data(f'/teams/{team_id}/matches/', filters)

# 使用例: レアル・マドリードの今後の試合
upcoming = get_team_matches(86, status='SCHEDULED', limit=5)
print_pretty(upcoming)

# ホームゲームのみ取得
home_matches = get_team_matches(86, venue='HOME', limit=10)
print_pretty(home_matches)

4. 人物 (Persons)

選手やコーチの情報を取得します。

人物情報の取得

def get_person(person_id):
    """特定の人物を表示"""
    print(f"\n--- Fetching Person ID: {person_id} ---")
    return fetch_data(f'/persons/{person_id}')

# 使用例: Scott Parkerの情報を取得
person = get_person(3964)  # 3964 = Scott Parker
print_pretty(person)

人物の試合履歴

def get_person_matches(person_id, date_from=None, date_to=None, 
                      status=None, competitions=None, 
                      limit=None, offset=None):
    """特定の人物のすべての試合を表示"""
    print(f"\n--- Fetching Matches for Person ID: {person_id} ---")
    filters = {
        'dateFrom': date_from,
        'dateTo': date_to,
        'status': status,
        'competitions': competitions,
        'limit': limit,
        'offset': offset
    }
    filters = {k: v for k, v in filters.items() if v is not None}
    return fetch_data(f'/persons/{person_id}/matches', filters)

# 使用例: Scott Parkerの直近の試合を取得
matches = get_person_matches(3964, status='FINISHED', limit=10)
print_pretty(matches)

5. 試合 (Matches)

試合の詳細情報を取得します。

特定試合の詳細

def get_match_by_id(match_id):
    """特定の試合を表示"""
    print(f"\n--- Fetching Match ID: {match_id} ---")
    return fetch_data(f'/matches/{match_id}')

# 使用例
match = get_match_by_id(327295)
print_pretty(match)

複数大会の試合取得

def get_matches(competitions=None, ids=None, date_from=None, 
               date_to=None, status=None):
    """(複数の)大会にまたがる試合を一覧表示"""
    print("\n--- Fetching Matches (Cross-Competition) ---")
    filters = {
        'competitions': competitions,
        'ids': ids,
        'dateFrom': date_from,
        'dateTo': date_to,
        'status': status
    }
    filters = {k: v for k, v in filters.items() if v is not None}
    return fetch_data('/matches', filters)

# 使用例: 今日の試合
from datetime import date
today = date.today().strftime('%Y-%m-%d')
today_matches = get_matches(date_from=today, date_to=today)
print_pretty(today_matches)

# 特定の大会の試合のみ
pl_matches = get_matches(competitions='PL,SA')  # PLとSA
print_pretty(pl_matches)

対戦成績 (Head2Head)

def get_head2head(match_id, limit=None, date_from=None, 
                 date_to=None, competitions=None):
    """試合を行うチーム間の過去の対戦成績を一覧表示"""
    print(f"\n--- Fetching Head2Head for Match ID: {match_id} ---")
    filters = {
        'limit': limit,
        'dateFrom': date_from,
        'dateTo': date_to,
        'competitions': competitions
    }
    filters = {k: v for k, v in filters.items() if v is not None}
    return fetch_data(f'/matches/{match_id}/head2head', filters)

# 使用例: 直近5試合の対戦成績
h2h = get_head2head(327295, limit=5)
print_pretty(h2h)

主要な大会コード一覧

APIの大会コード

コード 大会名
PL プレミアリーグ (イングランド)
PD ラ・リーガ (スペイン)
SA セリエA (イタリア)
BL1 ブンデスリーガ (ドイツ)
FL1 リーグ・アン (フランス)
DED エールディビジ (オランダ)
PPL プリメイラ・リーガ (ポルトガル)
CL UEFAチャンピオンズリーグ
WC FIFAワールドカップ
EC EURO

フィルターパラメータ一覧

各エンドポイントで使用できる主なフィルターパラメータ:

パラメータ 型 説明 例
dateFrom String 開始日 2024-01-01
dateTo String 終了日 2024-12-31
status Enum 試合ステータス SCHEDULED, FINISHED, LIVE
matchday Integer 節 1, 38
season String シーズン 2023, 2024
venue Enum 会場 HOME, AWAY
limit Integer 取得件数 10, 100
offset Integer オフセット 0, 10
stage Enum ステージ FINAL, SEMI_FINALS

ステータスの種類

  • SCHEDULED: 予定
  • LIVE: 進行中
  • IN_PLAY: プレー中
  • PAUSED: 中断中
  • FINISHED: 終了
  • POSTPONED: 延期
  • SUSPENDED: 中止
  • CANCELLED: キャンセル

最後に

この記事では、football-org apiの使い方を解説しました。
これを使うことで、欧州サッカーのデータを簡単に取得することが可能になります。

今後の記事では、このapiを使ったアプリケーションの開発を解説していこうと考えています。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?