【和訳】football-data.org 海外サッカーファンのためのAPI

# はじめに
23-24シーズンが開幕した欧州サッカーですが、個人で使用する何かしらのアプリケーションを作ってみようと思いました。
そこで試合データやチーム情報を取得できるAPIがないか探したところ、ちょうど良いAPIを見つけました。

- [football-data.org](https://www.football-data.org/)

スコアもリアルタイムで反映されるため使い勝手が良さそうです。

ただ、公式ドキュメントはオール英語のため、本記事では日本人向けに翻訳してまとめていきます。

# 対象者
- サッカー好きエンジニア
- 海外サッカーの情報を取得するAPIを探している方
- これからfootball-data.orgを利用する方

# プランについて
無料プランを含む全4プランあります。

![football-data.org 料金プラン](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/527256/2158de8e-5f9a-5e8f-0ec6-f7cc72fee7f1.png)

| プラン                    | Free                | Free + Three        | Standard            | Advanced            | Odds Add-On          |
|------------------------|---------------------|---------------------|---------------------|---------------------|----------------------|
| 価格 (ユーロ/月)             | €0,00 /mo           | €29,- /mo           | €49,- /mo           | €99,- /mo           | €10,- /mo            |
| 価格 (日本円/月)  ※2023/9 時点 | 0円                  | 4,553円               | 7,693円               | 15,493円              | 1,570円               |
| コンペティション数              | 12                    | 15                    | 25                    | 50                    | 20                     |
| 選択可能コンペティション           | -                   | 3 選択可             | -                     | -                     | -                       |
| ライブスコア                 | -                   | ✓                     | ✓                     | ✓                     | -                       |
| 日程表、スケジュール             | -                   | ✓                     | ✓                     | ✓                     | -                       |
| リーグテーブル                | -                   | ✓                     | ✓                     | ✓                     | -                       |
| ラインナップ & サブ            | -                   | ✓                     | ✓                     | ✓                     | -                       |
| ゴールスコアラー               | -                   | ✓                     | ✓                     | ✓                     | -                       |
| ブッキング / カード            | -                   | ✓                     | ✓                     | ✓                     | -                       |
| APIリクエスト数/分            | 10                   | 30                    | 60                    | 100                   | -                       |
| Pre-Match オッズ          | -                   | -                     | -                     | -                     | ✓                       |
| Historical オッズ         | -                   | -                     | -                     | -                     | ✓                       |

## 無料プランに含まれているリーグについて
無料プランで使用できる12コンペティションには欧州主要リーグが含まれているので、個人利用で使う分には「Free」プランで十分かと思います。
- イングランドプレミアリーグ
- リーグアン
- リーガ・エスパニョーラ
- ブンデスリーガ
- セリエA
- UEFA チャンピオンズリーグ
などなど

![無料プランに含まれるリーグ](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/527256/5999786f-f98b-cb25-b75a-0a8796b72df5.png)

# 使い方
## APIトークンの発行
トークンの発行には会員登録が必要です。
https://www.football-data.org/client/register

無料プランだとクレカの登録は必要ないのでその点安心ですね。

画面に従って登録を進めていくと登録完了メールが届きます。

![登録完了メール](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/527256/7cea0de5-4b7a-9fff-e90e-5d8977af2dba.png)

このメールにAPIトークンが記載されているので、こちら控えておきましょう。

もちろんログインするとマイページからもトークンが発行できるのでご安心を。

## トークンを付与する
APIリクエストにはリクエストヘッダー内にトークンを含ませる必要があります。
キーは `X-Auth-Token` です。

```json:Headers
{
  "X-Auth-Token": "発行したAPIトークン"
}
```

# API紹介
ここからは各APIを紹介していきます。
全てのAPIは `mehods: GET`となります。

各APIレスポンスについて知りたい方は公式サイトからどうぞ。
[クイックスタート](https://www.football-data.org/documentation/quickstart)

## エリア
各国のリーグがどの地域、国にあるのかを取得できます。
- ### エリア一覧を取得する
    - ```/v4/areas/```
    - フィルター: -
- ### エリア情報を取得する
    - ```/v4/areas/{id}```
    - フィルター: -
## リーグ情報
各リーグの情報を取得できます。
- ### リーグ一覧を取得する
    - ```/v4/competitions/```
    - フィルター: areas={AREAS}
  ```shell:リクエスト
  curl -X GET http://api.football-data.org/v4/competitions/
  ```
  ```json:レスポンス
  {
    "count": 13,
    "filters": {
        "client": "john doe"
    },
    "competitions": [
        {
            "id": 2013,
            "area": {
                "id": 2032,
                "name": "Brazil",
                "code": "BRA",
                "flag": "https://crests.football-data.org/764.svg"
            },
            "name": "Campeonato Brasileiro Série A",
            "code": "BSA",
            "type": "LEAGUE",
            "emblem": "https://crests.football-data.org/764.svg",
            "plan": "TIER_ONE",
            "currentSeason": {
                "id": 1557,
                "startDate": "2023-04-15",
                "endDate": "2023-12-03",
                "currentMatchday": 22,
                "winner": null
            },
            "numberOfAvailableSeasons": 7,
            "lastUpdated": "2021-07-20T18:42:17Z"
        },
        {
            "id": 2016,
            "area": {
                "id": 2072,
                "name": "England",
                "code": "ENG",
                "flag": "https://crests.football-data.org/770.svg"
            },
            "name": "Championship",
            "code": "ELC",
            "type": "LEAGUE",
            "emblem": "https://crests.football-data.org/ELC.png",
            "plan": "TIER_ONE",
            "currentSeason": {
                "id": 1573,
                "startDate": "2023-08-04",
                "endDate": "2024-05-04",
                "currentMatchday": 5,
                "winner": null
            },
            "numberOfAvailableSeasons": 7,
            "lastUpdated": "2022-03-20T09:31:30Z"
        }
      ]
  }
  ```
- ### 指定したリーグの詳細情報を取得する
    - ```/v4/competitions/{リーグCode}```
    - フィルター: -
  ```shell:リクエスト
  curl -X GET http://api.football-data.org/v4/competitions/PL
  ```

  ```json:レスポンス
  {
    "area": {
        "id": 2072,
        "name": "England",
        "code": "ENG",
        "flag": "https://crests.football-data.org/770.svg"
    },
    "id": 2021,
    "name": "Premier League",
    "code": "PL",
    "type": "LEAGUE",
    "emblem": "https://crests.football-data.org/PL.png",
    "currentSeason": {
        "id": 1564,
        "startDate": "2023-08-11",
        "endDate": "2024-05-19",
        "currentMatchday": 4,
        "winner": null
    },
    seasons: [...]
    "lastUpdated": "2022-03-20T08:58:54Z"
  }
  ```


- ### 指定したリーグの順位表を取得する（有料）
    - ```/v4/competitions/{id}/standings```
    - フィルター: matchday={MATCHDAY}, season={YEAR}, date={DATE}

- ### 指定したリーグのすべての試合一覧を取得する
    - ```/v4/competitions/{id}/matches```
    - フィルター: dateFrom={DATE}, dateTo={DATE}, stage={STAGE}, status={STATUS}, matchday={MATCHDAY}, group={GROUP}, season={YEAR}
  ```shell:リクエスト
  curl -X GET http://api.football-data.org/v4/competitions/2003/matches?matchday=1
  ```
  ``` json:レスポンス
  {
    "filters": {
        "season": "2023",
        "matchday": "23"
    },
    "resultSet": {
        "count": 9,
        "first": "2024-02-24",
        "last": "2024-02-24",
        "played": 0
    },
    "competition": {
        "id": 2002,
        "name": "Bundesliga",
        "code": "BL1",
        "type": "LEAGUE",
        "emblem": "https://crests.football-data.org/BL1.png"
    },
    "matches": [
        {
            "area": {
                "id": 2088,
                "name": "Germany",
                "code": "DEU",
                "flag": "https://crests.football-data.org/759.svg"
            },
            "competition": {
                "id": 2002,
                "name": "Bundesliga",
                "code": "BL1",
                "type": "LEAGUE",
                "emblem": "https://crests.football-data.org/BL1.png"
            },
            "season": {
                "id": 1592,
                "startDate": "2023-08-18",
                "endDate": "2024-05-18",
                "currentMatchday": 3,
                "winner": null
            },
            "id": 441987,
            "utcDate": "2024-02-24T00:00:00Z",
            "status": "SCHEDULED",
            "matchday": 23,
            "stage": "REGULAR_SEASON",
            "group": null,
            "lastUpdated": "2023-06-30T11:01:12Z",
            "homeTeam": {
                "id": 5,
                "name": "FC Bayern München",
                "shortName": "Bayern",
                "tla": "FCB",
                "crest": "https://crests.football-data.org/5.svg"
            },
            "awayTeam": {
                "id": 721,
                "name": "RB Leipzig",
                "shortName": "RB Leipzig",
                "tla": "RBL",
                "crest": "https://crests.football-data.org/721.png"
            },
            "score": {
                "winner": null,
                "duration": "REGULAR",
                "fullTime": {
                    "home": null,
                    "away": null
                },
                "halfTime": {
                    "home": null,
                    "away": null
                }
            },
            "odds": {
                "msg": "Activate Odds-Package in User-Panel to retrieve odds."
            },
            "referees": []
        }
      ]
  }
  ```

- ### 指定したリーグのすべてのチーム一覧を取得する
    - ```/v4/competitions/{id}/teams```
    - フィルター: season={YEAR}
  ```shell:リクエスト
  curl -X GET http://api.football-data.org/v4/competitions/PL/teams
  ```
  ``` json:レスポンス
  {
    "count": 20,
    "filters": {
        "season": "2023"
    },
    "competition": {
        "id": 2021,
        "name": "Premier League",
        "code": "PL",
        "type": "LEAGUE",
        "emblem": "https://crests.football-data.org/PL.png"
    },
    "season": {
        "id": 1564,
        "startDate": "2023-08-11",
        "endDate": "2024-05-19",
        "currentMatchday": 4,
        "winner": null
    },
    "teams": [
        {
            "area": {
                "id": 2072,
                "name": "England",
                "code": "ENG",
                "flag": "https://crests.football-data.org/770.svg"
            },
            "id": 57,
            "name": "Arsenal FC",
            "shortName": "Arsenal",
            "tla": "ARS",
            "crest": "https://crests.football-data.org/57.png",
            "address": "75 Drayton Park London N5 1BU",
            "website": "http://www.arsenal.com",
            "founded": 1886,
            "clubColors": "Red / White",
            "venue": "Emirates Stadium",
            "runningCompetitions": [
                {
                    "id": 2021,
                    "name": "Premier League",
                    "code": "PL",
                    "type": "LEAGUE",
                    "emblem": "https://crests.football-data.org/PL.png"
                }
            ],
            "coach": {
                "id": 179744,
                "firstName": "",
                "lastName": "Mikel Arteta",
                "name": "Mikel Arteta",
                "dateOfBirth": "1982-03-26",
                "nationality": "Spain",
                "contract": {
                    "start": "2019-12",
                    "until": "2025-06"
                }
            },
            "squad": [
                {
                    "id": 3827,
                    "name": "Rúnar Alex Rúnarsson",
                    "position": "Goalkeeper",
                    "dateOfBirth": "1995-02-18",
                    "nationality": "Iceland"
                },
                {
                    "id": 5530,
                    "name": "Aaron Ramsdale",
                    "position": "Goalkeeper",
                    "dateOfBirth": "1998-05-14",
                    "nationality": "England"
                },
            ],
            "staff": [],
            "lastUpdated": "2022-02-22T14:05:46Z"
        }
    ]
  }
  ```

- ### 指定したリーグの得点ランキングを取得する
    - ```/v4/competitions/{id}/scorers```
    - フィルター: limit={LIMIT}, season={YEAR}
    ```shell:リクエスト
    curl -X GET http://api.football-data.org/v4/competitions/PL/scorers
    ```
    ``` json:レスポンス
    {
    "count": 10,
    "filters": {
        "season": "2023",
        "limit": 10
    },
    "competition": {
        "id": 2021,
        "name": "Premier League",
        "code": "PL",
        "type": "LEAGUE",
        "emblem": "https://crests.football-data.org/PL.png"
    },
    "season": {
        "id": 1564,
        "startDate": "2023-08-11",
        "endDate": "2024-05-19",
        "currentMatchday": 4,
        "winner": null
    },
    "scorers": [
        {
            "player": {
                "id": 38101,
                "name": "Erling Haaland",
                "firstName": "Erling",
                "lastName": "Haaland",
                "dateOfBirth": "2000-07-21",
                "nationality": "Norway",
                "section": "Offence",
                "position": null,
                "shirtNumber": null,
                "lastUpdated": "2023-07-30T17:01:18Z"
            },
            "team": {
                "id": 65,
                "name": "Manchester City FC",
                "shortName": "Man City",
                "tla": "MCI",
                "crest": "https://crests.football-data.org/65.png",
                "address": "SportCity Manchester M11 3FF",
                "website": "https://www.mancity.com",
                "founded": 1880,
                "clubColors": "Sky Blue / White",
                "venue": "Etihad Stadium",
                "lastUpdated": "2022-02-10T19:48:37Z"
            },
            "playedMatches": 4,
            "goals": 6,
            "assists": 1,
            "penalties": 1
        },
        {
            "player": {
                "id": 130809,
                "name": "Evan Ferguson",
                "firstName": "Evan",
                "lastName": "Ferguson",
                "dateOfBirth": "2004-10-19",
                "nationality": "Ireland",
                "section": "Offence",
                "position": null,
                "shirtNumber": null,
                "lastUpdated": "2023-07-30T17:01:22Z"
            },
            "team": {
                "id": 397,
                "name": "Brighton & Hove Albion FC",
                "shortName": "Brighton Hove",
                "tla": "BHA",
                "crest": "https://crests.football-data.org/397.svg",
                "address": "44 North Road Brighton & Hove BN1 1YR",
                "website": "http://www.seagulls.co.uk",
                "founded": 1898,
                "clubColors": "Blue / White",
                "venue": "The American Express Community Stadium",
                "lastUpdated": "2021-04-12T13:10:44Z"
            },
            "playedMatches": 4,
            "goals": 4,
            "assists": null,
            "penalties": null
        },
      ]
  }
  ```

## チーム
各リーグのチーム情報を取得できます。
チームの試合結果も取得できるのはありがたいですね。
- ### チーム一覧を取得する
    - ```/v4/teams/```
    - フィルター: limit={LIMIT}, offset={OFFSET}
- ### 指定したチーム情報を取得する
    - ```/v4/teams/{id}```
    - フィルター: -
    ```shell:リクエスト
    curl -X GET http://api.football-data.org/v4//teams/57/
    ```
  ```json:レスポンス
  {
    "area": {
        "id": 2072,
        "name": "England",
        "code": "ENG",
        "flag": "https://crests.football-data.org/770.svg"
    },
    "id": 57,
    "name": "Arsenal FC",
    "shortName": "Arsenal",
    "tla": "ARS",
    "crest": "https://crests.football-data.org/57.png",
    "address": "75 Drayton Park London N5 1BU",
    "website": "http://www.arsenal.com",
    "founded": 1886,
    "clubColors": "Red / White",
    "venue": "Emirates Stadium",
    "runningCompetitions": [
        {
            "id": 2021,
            "name": "Premier League",
            "code": "PL",
            "type": "LEAGUE",
            "emblem": "https://crests.football-data.org/PL.png"
        }
    ],
    "coach": {
        "id": 179744,
        "firstName": "",
        "lastName": "Mikel Arteta",
        "name": "Mikel Arteta",
        "dateOfBirth": "1982-03-26",
        "nationality": "Spain",
        "contract": {
            "start": "2019-12",
            "until": "2025-06"
        }
    },
    "squad": [
        {
            "id": 3827,
            "name": "Rúnar Alex Rúnarsson",
            "position": "Goalkeeper",
            "dateOfBirth": "1995-02-18",
            "nationality": "Iceland"
        },
        {
            "id": 5530,
            "name": "Aaron Ramsdale",
            "position": "Goalkeeper",
            "dateOfBirth": "1998-05-14",
            "nationality": "England"
        },
    ],
    "staff": [],
    "lastUpdated": "2022-02-10T19:48:56Z"
  }
  ```

- ### 指定したチームの試合一覧を取得する
    - ```/v4/teams/{id}/matches/```
    - フィルター: dateFrom={DATE}, dateTo={DATE}, season={YEAR}, competitions={competitionIds}, status={STATUS}, venue={VENUE}, limit={LIMIT}

## 選手
各チームの選手情報を取得できます。
ここでスコアなどのスタッツも取得可能です。
- ### 指定した選手の試合一覧を取得する
    - ```/v4/persons/{id}/matches```
    - フィルター: dateFrom={DATE}, dateTo={DATE}, status={STATUS}, competitions={competitionIds}, limit={LIMIT}, offset={OFFSET}
- ### 指定した選手の情報を取得する
    - ```/v4/persons/{id}```
    - フィルター: -
## 試合
各試合の結果やスタッツを取得できます。
無料プランだと反映に時間がかかるそうですが、有料プランになるとリアルタイムでの取得が可能。
- ### 試合一覧を取得する
    - ```/v4/matches```
    - フィルター: competitions={competitionIds}, ids={matchIds}, dateFrom={DATE}, dateTo={DATE}, status={STATUS}
- ### 指定した試合情報を取得する
    - ```/v4/matches/{id}```
    - フィルター: -
- ### 対戦するチームの過去の試合情報を取得する
    - ```/v4/matches/{id}/head2head```
    - フィルター: limit={LIMIT}, dateFrom={DATE}, dateTo={DATE}, competitions={competitionIds}
# さいごに
各リーグに推しのチームがいるファンにとっては上手く使うことで、そのチームの情報の試合結果のみを一覧で表示するなんでことができそうですね。
大変使い勝手が良さそうなAPIです。