# Football API manual

Football API serves the results, tables and fixtures of sixty leagues in thirty countries, the Champions League, Europa League and Conference League, and the World Cup and the Euros with their qualifiers. Every season goes back to 2015/16, or to the league's start where that is later. This manual is the whole API in one file; the pages at https://footballapi.org/documentation say the same with Try it.

## The basics

- Base address: `https://api.footballapi.org/v1`. The `/v1` prefix is optional. Only GET is answered.
- The key goes in the `X-API-Key` header, or `Authorization: Bearer <key>`. A key in the address is refused with `400 bad_request`.
- Keys start `fa_live_`. One key per account; replacing it at https://footballapi.org/account/keys keeps the old one working for 24 hours.
- Every answer is JSON: `data` (rows, or one object) and `meta` (count, paging, `request_id`). On the complimentary key `meta.your_key_reads` says what the key reads.
- Matches, clubs, grounds and referees have our own ids, `mt_`, `cl_`, `gd_` and `rf_` and 9 characters, stable for good.
- Competitions are named as in `/v1/competitions`, such as `premier-league`. A season is its first year: `2026` is 2026/27.
- Times are UTC, ISO 8601 with a Z.
- Odds, betting prices and line-ups are not served on any plan.

## Plans and limits

| | Complimentary key | Membership |
|---|---|---|
| Price | $0 | $29 a month or $299 a year |
| Reads | This season's Premier League | All 68 competitions, back to 2015/16 |
| Live scores | no | yes |
| Calls a minute | 10 | 120 |
| Calls a day | 50, reset 00:00 UTC | no ceiling |

`/v1/usage` never counts against the day. Every answer carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix seconds), on the complimentary key `X-Quota-Remaining`, and on a 429 `Retry-After`.

Answers are kept for at most 5 seconds (live), 5 minutes (recent results, one match, tables, form, head to head), 15 minutes (fixtures) and a day (past seasons, grounds, the collection).

## Errors

An error answers `{"error": {"code", "message", "docs"}, "meta": {"request_id"}}`; `upgrade_required` and `quota_exceeded` add `plan` and `upgrade_url`. Match on `error.code`, never the message.

| HTTP | Code | When |
|---|---|---|
| 400 | `bad_request` | A parameter missing or malformed, or the key in the address |
| 401 | `unauthorized` | No key, or one we do not know |
| 403 | `upgrade_required` | Past what the plan reads, or live scores on the complimentary key |
| 404 | `not_found` | No such endpoint, id, competition or season |
| 422 | `unknown_parameter` | A parameter the endpoint does not take |
| 429 | `rate_limited` | Too many calls this minute; wait Retry-After seconds |
| 429 | `quota_exceeded` | The day's calls are used; they reset at 00:00 UTC |
| 500 | `server_error` | Our side; retry shortly |

## Pagination

`/v1/results` and `/v1/fixtures` page: `page` from 1, `per_page` up to 1000 (default 100). `meta` gives `count`, `page`, `per_page`, `total`, `total_pages`, `next_page`, `prev_page` and `next_cursor`. On results, pass `meta.next_cursor` back as `cursor`, unchanged, until it is null; it is the quicker way through a season.

## Endpoints

### Competitions

#### Competitions

`GET /v1/competitions`  
Every key.

Every league and competition in the collection with its country, its tier, the first season served, and whether your key reads it.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `country` | string | no | Only this country, such as England. |

| Field | Type | What it is |
|---|---|---|
| `competition` | string | The competition's name in the collection, such as premier-league |
| `name` | string | The competition as people write it |
| `country` | string | The country, or Europe or World for a competition across countries |
| `tier` | null or more | The league's level in its country, 1 for the top flight |
| `kind` | string | League, or the kind of competition |
| `since` | string | The first season served |
| `your_key_reads` | boolean | Whether your key reads it |

```bash
curl "https://api.footballapi.org/v1/competitions" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": [
        {
            "competition": "champions-league",
            "name": "Champions League",
            "country": "Europe",
            "tier": null,
            "kind": "Club, Europe",
            "since": "2015/16",
            "your_key_reads": true
        },
        {
            "competition": "europa-league",
            "name": "Europa League",
            "country": "Europe",
            "tier": null,
            "kind": "Club, Europe",
            "since": "2015/16",
            "your_key_reads": true
        }
    ],
    "meta": {
        "count": 68,
        "request_id": "req_791e5810855471ef"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Competition

`GET /v1/competitions/{competition}`  
Every key.

A competition in the collection: the first and last season served, how many matches it holds, and whether your key reads it.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | yes | A competition from /v1/competitions, such as premier-league. In the path. |

| Field | Type | What it is |
|---|---|---|
| `competition` | string | The competition's name in the collection, such as premier-league |
| `name` | string | The competition as people write it |
| `since` | string | The first season served |
| `first_season` | integer | The first season served, by its first year |
| `last_season` | integer | The latest season, by its first year |
| `matches` | integer | Matches counted |
| `groups` | integer | How many groups it is played in; 1 for a single league |
| `your_key_reads` | boolean | Whether your key reads it |

```bash
curl "https://api.footballapi.org/v1/competitions/premier-league" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": {
        "competition": "premier-league",
        "name": "England's Premier League",
        "since": "2015/16",
        "first_season": 2015,
        "last_season": 2026,
        "matches": 14756,
        "groups": 1,
        "your_key_reads": true
    },
    "meta": {
        "request_id": "req_74110ca02ebcffec"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Countries

`GET /v1/countries`  
Every key.

Every country in the collection, with how many of its competitions are served and their names.

| Field | Type | What it is |
|---|---|---|
| `country` | string | The country, or Europe or World for a competition across countries |
| `competitions` | integer | How many of its competitions the collection serves |
| `names` | list | Their names in the collection |

```bash
curl "https://api.footballapi.org/v1/countries" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": [
        {
            "country": "Europe",
            "competitions": 6,
            "names": [
                "champions-league",
                "europa-league",
                "conference-league"
            ]
        },
        {
            "country": "World",
            "competitions": 2,
            "names": [
                "world-cup",
                "world-cup-qualifiers"
            ]
        }
    ],
    "meta": {
        "count": 32,
        "request_id": "req_04a22bc2bb9c2c3f"
    }
}
```

Errors: 401 `unauthorized`, 422 `unknown_parameter`, 429 `quota_exceeded`.

### Seasons

#### Season

`GET /v1/competitions/{competition}/seasons/{season}`  
Complimentary key: this season's Premier League.

A season of a competition: its dates, its clubs and how many matches it holds. Competitions played in groups return each group.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | yes | A competition from /v1/competitions, such as premier-league. In the path. |
| `season` | integer | yes | The first year of the season: 2026 for 2026/27. In the path. From 2015, or the competition's first season. |

| Field | Type | What it is |
|---|---|---|
| `competition` | string | The competition's name in the collection, such as premier-league |
| `country_name` | string | The country, or World or Europe for a tournament |
| `competition_name` | string | The competition as people write it |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `matches` | integer | Matches counted |
| `finished` | integer | Matches played so far |
| `first_match` | string | The day of the first match |
| `last_match` | string | The day of the last match, played or to come |

```bash
curl "https://api.footballapi.org/v1/competitions/premier-league/seasons/2026" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": {
        "competition": "premier-league",
        "country_name": "England",
        "competition_name": "Premier League",
        "season_start_year": 2026,
        "matches": 380,
        "finished": 70,
        "first_match": "2026-08-21",
        "last_match": "2027-05-30"
    },
    "meta": {
        "competition": "premier-league",
        "season": "2026/27",
        "request_id": "req_50bb5d4d8548b96a"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Table

`GET /v1/competitions/{competition}/seasons/{season}/table`  
Complimentary key: this season's Premier League.

A league table as it stands this morning, or as it stood on any date you pass, for home matches, away matches or both. Competitions played in groups return each group.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | yes | A competition from /v1/competitions, such as premier-league. In the path. |
| `season` | integer | yes | The first year of the season: 2026 for 2026/27. In the path. From 2015, or the competition's first season. |
| `date` | date | no | The table on the morning of this day, YYYY-MM-DD. |
| `venue` | string | no | A table of home matches only, or away matches only. home or away. |

| Field | Type | What it is |
|---|---|---|
| `competition` | string | The competition's name in the collection, such as premier-league |
| `country_name` | string | The country, or World or Europe for a tournament |
| `competition_name` | string | The competition as people write it |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `as_of` | null or more | The day the table stands on; null for this morning |
| `venue` | null or more | home or away when the table counts only those; null for both |
| `table` | list | Each club in the table, top first |
| `table[].position` | integer | Place in the table |
| `table[].club_id` | string | Our id for the club, cl_ and 9 characters, the same in every answer and for good |
| `table[].club_name` | string | The club |
| `table[].played` | integer | Matches counted |
| `table[].won` | integer | Matches won |
| `table[].drawn` | integer | Matches drawn |
| `table[].lost` | integer | Matches lost |
| `table[].goals_for` | integer | Goals scored |
| `table[].goals_against` | integer | Goals let in |
| `table[].goal_difference` | integer | Goals scored less goals let in |
| `table[].points` | integer | Three for a win, one for a draw |

```bash
curl "https://api.footballapi.org/v1/competitions/premier-league/seasons/2026/table" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": {
        "competition": "premier-league",
        "country_name": "England",
        "competition_name": "Premier League",
        "season_start_year": 2026,
        "as_of": null,
        "venue": null,
        "table": [
            {
                "position": 1,
                "club_id": "cl_a7vhnxhhh",
                "club_name": "Manchester City",
                "played": 7,
                "won": 7,
                "drawn": 0,
                "lost": 0,
                "goals_for": 19,
                "goals_against": 7,
                "goal_difference": 12,
                "points": 21
            },
            {
                "position": 2,
                "club_id": "cl_9cbmhewrg",
                "club_name": "Arsenal",
                "played": 7,
                "won": 6,
                "drawn": 0,
                "lost": 1,
                "goals_for": 11,
                "goals_against": 5,
                "goal_difference": 6,
                "points": 18
            },
            {
                "position": 3,
                "club_id": "cl_4tesczsmh",
                "club_name": "Brighton",
                "played": 7,
                "won": 5,
                "drawn": 1,
                "lost": 1,
                "goals_for": 23,
                "goals_against": 5,
                "goal_difference": 18,
                "points": 16
            }
        ]
    },
    "meta": {
        "competition": "premier-league",
        "season": "2026/27",
        "as_of": "2026-10-21",
        "request_id": "req_bb2de28f6a88eedb"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Positions

`GET /v1/competitions/{competition}/seasons/{season}/positions`  
Complimentary key: this season's Premier League.

Where every club stood in the table before each of its matches in a season.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | yes | A competition from /v1/competitions, such as premier-league. In the path. |
| `season` | integer | yes | The first year of the season: 2026 for 2026/27. In the path. From 2015, or the competition's first season. |

| Field | Type | What it is |
|---|---|---|
| `match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `kickoff_utc` | string | Kickoff in UTC, ISO 8601 |
| `kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `home` | object | The home side |
| `home.club_id` | string | Our id for the club, cl_ and 9 characters, the same in every answer and for good |
| `home.club_name` | string | The club |
| `home.position` | integer | Place in the table |
| `away` | object | The away side |
| `away.club_id` | string | Our id for the club, cl_ and 9 characters, the same in every answer and for good |
| `away.club_name` | string | The club |
| `away.position` | integer | Place in the table |
| `full_time_result` | string | home, away or draw, at full time |
| `position_gap` | integer | Places between the two clubs in the table at kickoff; below 0 when the away side stood higher |

```bash
curl "https://api.footballapi.org/v1/competitions/premier-league/seasons/2026/positions" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": [
        {
            "match_id": "mt_e2hk79mn5",
            "kickoff_utc": "2026-08-28T19:00:00Z",
            "kickoff_date": "2026-08-28",
            "home": {
                "club_id": "cl_aydtq01vq",
                "club_name": "Crystal Palace",
                "position": 16
            },
            "away": {
                "club_id": "cl_a7vhnxhhh",
                "club_name": "Manchester City",
                "position": 8
            },
            "full_time_result": "away",
            "position_gap": -8
        },
        {
            "match_id": "mt_9hm3yz9rt",
            "kickoff_utc": "2026-08-29T11:30:00Z",
            "kickoff_date": "2026-08-29",
            "home": {
                "club_id": "cl_0s0a8kn8x",
                "club_name": "Liverpool",
                "position": 10
            },
            "away": {
                "club_id": "cl_5bvjqjxyw",
                "club_name": "Nottingham Forest",
                "position": 15
            },
            "full_time_result": "draw",
            "position_gap": 5
        }
    ],
    "meta": {
        "competition": "premier-league",
        "season": "2026/27",
        "request_id": "req_7da802c65dfdf7ed"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Season clubs

`GET /v1/competitions/{competition}/seasons/{season}/clubs`  
Complimentary key: this season's Premier League.

Every club in a competition in one season, with its ground, its city and where the ground is.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | yes | A competition from /v1/competitions, such as premier-league. In the path. |
| `season` | integer | yes | The first year of the season: 2026 for 2026/27. In the path. From 2015, or the competition's first season. |

| Field | Type | What it is |
|---|---|---|
| `club_id` | string | Our id for the club, cl_ and 9 characters, the same in every answer and for good |
| `club_name` | string | The club |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `matches` | integer | Matches counted |

```bash
curl "https://api.footballapi.org/v1/competitions/premier-league/seasons/2026/clubs" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": [
        {
            "club_id": "cl_frt0n2e46",
            "club_name": "Coventry",
            "ground_name": "Coventry Building Society Arena",
            "city_name": "Coventry",
            "matches": 38
        },
        {
            "club_id": "cl_e0nqz3rc3",
            "club_name": "Sunderland",
            "ground_name": "Stadium of Light",
            "city_name": "Sunderland",
            "matches": 38
        }
    ],
    "meta": {
        "count": 20,
        "competition": "premier-league",
        "season": "2026/27",
        "request_id": "req_a60481b59b7ab409"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Season matches

`GET /v1/competitions/{competition}/seasons/{season}/matches`  
Complimentary key: this season's Premier League.

Every match of a competition in one season, in kickoff order, played and still to come, paged.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | yes | A competition from /v1/competitions, such as premier-league. In the path. |
| `season` | integer | yes | The first year of the season: 2026 for 2026/27. In the path. From 2015, or the competition's first season. |
| `page` | integer | no | Which page, from 1. From 1 to 100,000. |
| `per_page` | integer | no | Rows on a page. Default 100. From 1 to 1,000. |
| `cursor` | string | no | meta.next_cursor from the page before, passed back unchanged. Faster than page for long walks. |

| Field | Type | What it is |
|---|---|---|
| `match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `competition` | string | The competition's name in the collection, such as premier-league |
| `country_name` | string | The country, or World or Europe for a tournament |
| `competition_name` | string | The competition as people write it |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `kickoff_utc` | string | Kickoff in UTC, ISO 8601 |
| `kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `kickoff_local_date` | string | The day of kickoff where the match is played |
| `kickoff_local_time` | string | The time of kickoff where the match is played |
| `match_status` | string | Where the match stands, such as finished or not started |
| `home_club_id` | string | Our id for the home club |
| `home_club_name` | string | The home club |
| `away_club_id` | string | Our id for the away club |
| `away_club_name` | string | The away club |
| `home_goals` | integer | Home goals at full time |
| `away_goals` | integer | Away goals at full time |
| `full_time_result` | string | home, away or draw, at full time |
| `half_time_home_goals` | integer | Home goals at half time |
| `half_time_away_goals` | integer | Away goals at half time |
| `half_time_result` | string | home, away or draw, at half time |
| `stoppage_minutes` | integer | Minutes of added time; null when not recorded |
| `is_kickoff_rescheduled` | boolean | Whether kickoff moved from its first date or time |
| `elapsed_minutes` | null or more | Minutes played so far while the match is on; null otherwise |
| `home_league_position` | null or more | The home side's place in its league before kickoff |
| `away_league_position` | null or more | The away side's place in its league before kickoff |
| `away_travel_km` | integer | How far the away side came, ground to ground, in kilometres |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `latitude` | number | Where the ground is, north to south |
| `longitude` | number | Where the ground is, east to west |
| `location_precision` | string | How exact latitude and longitude are: ground, or city |
| `daylight_minutes` | integer | Minutes of daylight that day at the ground |
| `sun_elevation_deg` | number | The sun's height at kickoff, in degrees; below 0 after dark |
| `public_holiday` | null or more | The public holiday that day where the match is played; null when none |
| `kickoff_temperature_c` | number | The temperature at kickoff, in degrees C; null when not recorded |
| `kickoff_rain_mm` | number | Rain in the hour of kickoff, in millimetres; null when not recorded |
| `kickoff_wind_ms` | number | Wind at kickoff, in metres a second; null when not recorded |
| `attendance` | integer | The crowd; null when not recorded |
| `referee_name` | string | The referee |
| `regular_time_home_goals` | integer | Home goals after 90 minutes and added time |
| `regular_time_away_goals` | integer | Away goals after 90 minutes and added time |
| `regular_time_result` | string | home, away or draw, after 90 minutes and added time |
| `extra_time_home_goals` | null or more | Home goals after extra time; null when there was none |
| `extra_time_away_goals` | null or more | Away goals after extra time; null when there was none |
| `shootout_home_goals` | null or more | Home penalties scored in a shootout; null when there was none |
| `shootout_away_goals` | null or more | Away penalties scored in a shootout; null when there was none |
| `club_figures` | object | Each side's figures for the match |
| `club_figures.home` | object | The home side |
| `club_figures.home.xg` | number | Expected goals |
| `club_figures.home.xg_estimate` | number | Expected goals worked out from the shots and the other figures |
| `club_figures.home.shots` | integer | Shots |
| `club_figures.home.shots_on_target` | integer | Shots on target |
| `club_figures.home.corners` | integer | Corners |
| `club_figures.home.fouls` | integer | Fouls committed |
| `club_figures.home.yellow_cards` | integer | Yellow cards |
| `club_figures.home.red_cards` | integer | Red cards |
| `club_figures.home.possession_pct` | integer | Share of the ball, as a percentage |
| `club_figures.away` | object | The away side |
| `club_figures.away.xg` | number | Expected goals |
| `club_figures.away.xg_estimate` | number | Expected goals worked out from the shots and the other figures |
| `club_figures.away.shots` | integer | Shots |
| `club_figures.away.shots_on_target` | integer | Shots on target |
| `club_figures.away.corners` | integer | Corners |
| `club_figures.away.fouls` | integer | Fouls committed |
| `club_figures.away.yellow_cards` | integer | Yellow cards |
| `club_figures.away.red_cards` | integer | Red cards |
| `club_figures.away.possession_pct` | integer | Share of the ball, as a percentage |

```bash
curl "https://api.footballapi.org/v1/competitions/premier-league/seasons/2026/matches?per_page=2" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": [
        {
            "match_id": "mt_146444zr9",
            "competition": "premier-league",
            "country_name": "England",
            "competition_name": "Premier League",
            "season_start_year": 2026,
            "kickoff_utc": "2026-08-21T19:00:00Z",
            "kickoff_date": "2026-08-21",
            "kickoff_local_date": "2026-08-21",
            "kickoff_local_time": "19:00",
            "match_status": "finished",
            "home_club_id": "cl_9cbmhewrg",
            "home_club_name": "Arsenal",
            "away_club_id": "cl_frt0n2e46",
            "away_club_name": "Coventry",
            "home_goals": 3,
            "away_goals": 0,
            "full_time_result": "home",
            "half_time_home_goals": 2,
            "half_time_away_goals": 0,
            "half_time_result": "home",
            "stoppage_minutes": 5,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": null,
            "away_league_position": null,
            "away_travel_km": 137,
            "ground_name": "Emirates Stadium",
            "city_name": "London",
            "latitude": 51.555,
            "longitude": -0.10833333333333,
            "location_precision": "ground",
            "daylight_minutes": 859,
            "sun_elevation_deg": 1.1,
            "public_holiday": null,
            "kickoff_temperature_c": 16.1,
            "kickoff_rain_mm": 0.01,
            "kickoff_wind_ms": 4.4,
            "attendance": 60098,
            "referee_name": "Thomas Bramall",
            "regular_time_home_goals": 3,
            "regular_time_away_goals": 0,
            "regular_time_result": "home",
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": {
                "home": {
                    "xg": 1.88,
                    "xg_estimate": 1.75,
                    "shots": 20,
                    "shots_on_target": 6,
                    "corners": 8,
                    "fouls": 10,
                    "yellow_cards": 1,
                    "red_cards": 0,
                    "possession_pct": 64
                },
                "away": {
                    "xg": 0.2,
                    "xg_estimate": 0.21,
                    "shots": 4,
                    "shots_on_target": 1,
                    "corners": 2,
                    "fouls": 13,
                    "yellow_cards": 1,
                    "red_cards": 0,
                    "possession_pct": 36
                }
            }
        },
        {
            "match_id": "mt_9bf725d14",
            "competition": "premier-league",
            "country_name": "England",
            "competition_name": "Premier League",
            "season_start_year": 2026,
            "kickoff_utc": "2026-08-22T11:30:00Z",
            "kickoff_date": "2026-08-22",
            "kickoff_local_date": "2026-08-22",
            "kickoff_local_time": "11:30",
            "match_status": "finished",
            "home_club_id": "cl_bp6fqwzpj",
            "home_club_name": "Hull City",
            "away_club_id": "cl_3pekhsfp3",
            "away_club_name": "Manchester United",
            "home_goals": 2,
            "away_goals": 0,
            "full_time_result": "home",
            "half_time_home_goals": 2,
            "half_time_away_goals": 0,
            "half_time_result": "home",
            "stoppage_minutes": 7,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": null,
            "away_league_position": null,
            "away_travel_km": 131,
            "ground_name": "MKM Stadium",
            "city_name": "Hull",
            "latitude": 53.746111111111,
            "longitude": -0.36777777777778,
            "location_precision": "ground",
            "daylight_minutes": 868,
            "sun_elevation_deg": 47.7,
            "public_holiday": null,
            "kickoff_temperature_c": 19.2,
            "kickoff_rain_mm": 0.01,
            "kickoff_wind_ms": 3,
            "attendance": 24470,
            "referee_name": "Darren England",
            "regular_time_home_goals": 2,
            "regular_time_away_goals": 0,
            "regular_time_result": "home",
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": {
                "home": {
                    "xg": 1.01,
                    "xg_estimate": 0.99,
                    "shots": 8,
                    "shots_on_target": 4,
                    "corners": 1,
                    "fouls": 10,
                    "yellow_cards": 2,
                    "red_cards": 0,
                    "possession_pct": 28
                },
                "away": {
                    "xg": 1.83,
                    "xg_estimate": 2.22,
                    "shots": 21,
                    "shots_on_target": 5,
                    "corners": 6,
                    "fouls": 9,
                    "yellow_cards": 1,
                    "red_cards": 0,
                    "possession_pct": 72
                }
            }
        }
    ],
    "meta": {
        "count": 2,
        "page": 1,
        "per_page": 2,
        "total": 380,
        "total_pages": 190,
        "next_page": 2,
        "prev_page": null,
        "next_cursor": "A-T6AyCUnqZp_hdnmJlgdgkYxVxvVmWFMb7DznzlqYcymSomuLvR-gngjpejhhBoj_zofw",
        "request_id": "req_36846376b2cd28a9"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Season stats

`GET /v1/competitions/{competition}/seasons/{season}/stats`  
Complimentary key: this season's Premier League.

A season of a competition in figures: matches, goals, home and away wins, draws, clean sheets, scorelines and cards.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | yes | A competition from /v1/competitions, such as premier-league. In the path. |
| `season` | integer | yes | The first year of the season: 2026 for 2026/27. In the path. From 2015, or the competition's first season. |

| Field | Type | What it is |
|---|---|---|
| `competition` | string | The competition's name in the collection, such as premier-league |
| `competition_name` | string | The competition as people write it |
| `country_name` | string | The country, or World or Europe for a tournament |
| `season` | integer | The season, by its first year |
| `first_day` | string | The first day counted |
| `last_day` | string | The last day counted |
| `clubs` | integer | How many clubs |
| `matches` | integer | Matches counted |
| `goals` | integer | Goals in the match |
| `goals_per_match` | number | Goals a match, on average |
| `home_win_pct` | integer | Share of matches the home side won, as a percentage |
| `draw_pct` | number | Share of matches drawn, as a percentage |
| `away_win_pct` | number | Share of matches the away side won, as a percentage |
| `goalless_pct` | number | Share of matches with no goals, as a percentage |
| `over_2_5_pct` | number | Share of matches with three goals or more, as a percentage |
| `home_clean_sheet_pct` | number | Share of matches where the home side let none in, as a percentage |
| `away_clean_sheet_pct` | number | Share of matches where the away side let none in, as a percentage |
| `average_travel_km` | integer | How far away sides came, on average, in kilometres |
| `common_scorelines` | list | The scorelines seen most, most first |
| `common_scorelines[].score` | string | The scoreline, home first |
| `common_scorelines[].matches` | integer | Matches counted |
| `common_scorelines[].share_pct` | number | Share of matches with it, as a percentage |
| `cards` | object | Cards a match |
| `cards.yellow_per_match` | number | Yellow cards a match, on average |
| `cards.red_per_match` | number | Red cards a match, on average |
| `cards.matches` | integer | Matches counted |

```bash
curl "https://api.footballapi.org/v1/competitions/premier-league/seasons/2026/stats" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": {
        "competition": "premier-league",
        "competition_name": "Premier League",
        "country_name": "England",
        "season": 2026,
        "first_day": "2026-08-21",
        "last_day": "2026-10-19",
        "clubs": 20,
        "matches": 70,
        "goals": 203,
        "goals_per_match": 2.9,
        "home_win_pct": 40,
        "draw_pct": 28.6,
        "away_win_pct": 31.4,
        "goalless_pct": 7.1,
        "over_2_5_pct": 54.3,
        "home_clean_sheet_pct": 25.7,
        "away_clean_sheet_pct": 28.6,
        "average_travel_km": 193,
        "common_scorelines": [
            {
                "score": "2-2",
                "matches": 8,
                "share_pct": 11.4
            },
            {
                "score": "0-1",
                "matches": 8,
                "share_pct": 11.4
            },
            {
                "score": "1-1",
                "matches": 7,
                "share_pct": 10
            }
        ],
        "cards": {
            "yellow_per_match": 3.96,
            "red_per_match": 0.19,
            "matches": 70
        }
    },
    "meta": {
        "competition": "premier-league",
        "season": "2026/27",
        "request_id": "req_51fae11310c80cad"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

### Matches

#### Matches

`GET /v1/matches`  
Complimentary key: this season's Premier League.

Every match in the collection, played or still to come, found by competition, club, season, dates, status, result, surface or home and away, paged.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |
| `club` | string | no | Only this club's matches: a club id such as cl_a7vhnxhhh. |
| `season` | integer | no | The first year of the season: 2026 for 2026/27. From 2015, or the competition's first season. |
| `date_from` | date | no | From this day, YYYY-MM-DD. |
| `date_to` | date | no | Up to this day, YYYY-MM-DD. |
| `status` | string | no | Where the match stands. finished or scheduled or postponed or cancelled or abandoned. |
| `result` | string | no | How it ended, from the home side: home, draw or away. home or draw or away. |
| `surface` | string | no | The pitch. grass or artificial_turf. |
| `venue` | string | no | Home matches only, or away matches only. home or away. |
| `page` | integer | no | Which page, from 1. From 1 to 100,000. |
| `per_page` | integer | no | Rows on a page. Default 100. From 1 to 1,000. |
| `cursor` | string | no | meta.next_cursor from the page before, passed back unchanged. Faster than page for long walks. |

| Field | Type | What it is |
|---|---|---|
| `match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `competition` | string | The competition's name in the collection, such as premier-league |
| `country_name` | string | The country, or World or Europe for a tournament |
| `competition_name` | string | The competition as people write it |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `kickoff_utc` | string | Kickoff in UTC, ISO 8601 |
| `kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `kickoff_local_date` | string | The day of kickoff where the match is played |
| `kickoff_local_time` | string | The time of kickoff where the match is played |
| `match_status` | string | Where the match stands, such as finished or not started |
| `home_club_id` | string | Our id for the home club |
| `home_club_name` | string | The home club |
| `away_club_id` | string | Our id for the away club |
| `away_club_name` | string | The away club |
| `home_goals` | null or more | Home goals at full time |
| `away_goals` | null or more | Away goals at full time |
| `full_time_result` | null or more | home, away or draw, at full time |
| `half_time_home_goals` | null or more | Home goals at half time |
| `half_time_away_goals` | null or more | Away goals at half time |
| `half_time_result` | null or more | home, away or draw, at half time |
| `stoppage_minutes` | null or more | Minutes of added time; null when not recorded |
| `is_kickoff_rescheduled` | boolean | Whether kickoff moved from its first date or time |
| `elapsed_minutes` | null or more | Minutes played so far while the match is on; null otherwise |
| `home_league_position` | integer | The home side's place in its league before kickoff |
| `away_league_position` | integer | The away side's place in its league before kickoff |
| `away_travel_km` | integer | How far the away side came, ground to ground, in kilometres |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `latitude` | number | Where the ground is, north to south |
| `longitude` | number | Where the ground is, east to west |
| `location_precision` | string | How exact latitude and longitude are: ground, or city |
| `daylight_minutes` | integer | Minutes of daylight that day at the ground |
| `sun_elevation_deg` | number | The sun's height at kickoff, in degrees; below 0 after dark |
| `public_holiday` | null or more | The public holiday that day where the match is played; null when none |
| `kickoff_temperature_c` | null or more | The temperature at kickoff, in degrees C; null when not recorded |
| `kickoff_rain_mm` | null or more | Rain in the hour of kickoff, in millimetres; null when not recorded |
| `kickoff_wind_ms` | null or more | Wind at kickoff, in metres a second; null when not recorded |
| `attendance` | null or more | The crowd; null when not recorded |
| `referee_name` | null or more | The referee |
| `regular_time_home_goals` | null or more | Home goals after 90 minutes and added time |
| `regular_time_away_goals` | null or more | Away goals after 90 minutes and added time |
| `regular_time_result` | null or more | home, away or draw, after 90 minutes and added time |
| `extra_time_home_goals` | null or more | Home goals after extra time; null when there was none |
| `extra_time_away_goals` | null or more | Away goals after extra time; null when there was none |
| `shootout_home_goals` | null or more | Home penalties scored in a shootout; null when there was none |
| `shootout_away_goals` | null or more | Away penalties scored in a shootout; null when there was none |
| `club_figures` | null or more | Each side's figures for the match |

```bash
curl "https://api.footballapi.org/v1/matches?competition=premier-league&season=2026&per_page=2" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": [
        {
            "match_id": "mt_d1gds0xhp",
            "competition": "premier-league",
            "country_name": "England",
            "competition_name": "Premier League",
            "season_start_year": 2026,
            "kickoff_utc": "2027-05-30T15:00:00Z",
            "kickoff_date": "2027-05-30",
            "kickoff_local_date": "2027-05-30",
            "kickoff_local_time": "15:00",
            "match_status": "scheduled",
            "home_club_id": "cl_e0nqz3rc3",
            "home_club_name": "Sunderland",
            "away_club_id": "cl_a7vhnxhhh",
            "away_club_name": "Manchester City",
            "home_goals": null,
            "away_goals": null,
            "full_time_result": null,
            "half_time_home_goals": null,
            "half_time_away_goals": null,
            "half_time_result": null,
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": 20,
            "away_league_position": 1,
            "away_travel_km": 168,
            "ground_name": "Stadium of Light",
            "city_name": "Sunderland",
            "latitude": 54.914429068932,
            "longitude": -1.3881729713502,
            "location_precision": "ground",
            "daylight_minutes": 1011,
            "sun_elevation_deg": 43.2,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": null,
            "referee_name": null,
            "regular_time_home_goals": null,
            "regular_time_away_goals": null,
            "regular_time_result": null,
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": null
        },
        {
            "match_id": "mt_06ythj4n7",
            "competition": "premier-league",
            "country_name": "England",
            "competition_name": "Premier League",
            "season_start_year": 2026,
            "kickoff_utc": "2027-05-30T15:00:00Z",
            "kickoff_date": "2027-05-30",
            "kickoff_local_date": "2027-05-30",
            "kickoff_local_time": "15:00",
            "match_status": "scheduled",
            "home_club_id": "cl_3pekhsfp3",
            "home_club_name": "Manchester United",
            "away_club_id": "cl_6ccybzgsq",
            "away_club_name": "Fulham",
            "home_goals": null,
            "away_goals": null,
            "full_time_result": null,
            "half_time_home_goals": null,
            "half_time_away_goals": null,
            "half_time_result": null,
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": 13,
            "away_league_position": 18,
            "away_travel_km": 262,
            "ground_name": "Old Trafford",
            "city_name": "Manchester",
            "latitude": 53.463055555556,
            "longitude": -2.2913888888889,
            "location_precision": "ground",
            "daylight_minutes": 994,
            "sun_elevation_deg": 44.3,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": null,
            "referee_name": null,
            "regular_time_home_goals": null,
            "regular_time_away_goals": null,
            "regular_time_result": null,
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": null
        }
    ],
    "meta": {
        "count": 2,
        "page": 1,
        "per_page": 2,
        "total": 380,
        "total_pages": 190,
        "next_page": 2,
        "prev_page": null,
        "next_cursor": "VaHW-WftqcvrOsFaVoRrFeYDLvSP8cNb0K-avynYtAanqfKmBBIwV5FA6VwtB57L6AKnMg",
        "request_id": "req_3a7975b734a2ada3"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Match

`GET /v1/matches/{match_id}`  
Complimentary key: this season's Premier League.

Everything about a match: the score at every stage, both clubs' positions before kickoff, the ground, the referee and the conditions on the day.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `match_id` | string | yes | A match id from any result, fixture or match list, such as mt_e2hk79mn5. In the path. |

| Field | Type | What it is |
|---|---|---|
| `match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `competition` | string | The competition's name in the collection, such as premier-league |
| `country_name` | string | The country, or World or Europe for a tournament |
| `competition_name` | string | The competition as people write it |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `kickoff_utc` | string | Kickoff in UTC, ISO 8601 |
| `kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `kickoff_local_date` | string | The day of kickoff where the match is played |
| `kickoff_local_time` | string | The time of kickoff where the match is played |
| `match_status` | string | Where the match stands, such as finished or not started |
| `home_club_id` | string | Our id for the home club |
| `home_club_name` | string | The home club |
| `away_club_id` | string | Our id for the away club |
| `away_club_name` | string | The away club |
| `home_goals` | integer | Home goals at full time |
| `away_goals` | integer | Away goals at full time |
| `full_time_result` | string | home, away or draw, at full time |
| `half_time_home_goals` | integer | Home goals at half time |
| `half_time_away_goals` | integer | Away goals at half time |
| `half_time_result` | string | home, away or draw, at half time |
| `stoppage_minutes` | null or more | Minutes of added time; null when not recorded |
| `is_kickoff_rescheduled` | boolean | Whether kickoff moved from its first date or time |
| `elapsed_minutes` | null or more | Minutes played so far while the match is on; null otherwise |
| `home_league_position` | integer | The home side's place in its league before kickoff |
| `away_league_position` | integer | The away side's place in its league before kickoff |
| `away_travel_km` | integer | How far the away side came, ground to ground, in kilometres |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `latitude` | number | Where the ground is, north to south |
| `longitude` | number | Where the ground is, east to west |
| `location_precision` | string | How exact latitude and longitude are: ground, or city |
| `daylight_minutes` | integer | Minutes of daylight that day at the ground |
| `sun_elevation_deg` | number | The sun's height at kickoff, in degrees; below 0 after dark |
| `public_holiday` | null or more | The public holiday that day where the match is played; null when none |
| `kickoff_temperature_c` | null or more | The temperature at kickoff, in degrees C; null when not recorded |
| `kickoff_rain_mm` | null or more | Rain in the hour of kickoff, in millimetres; null when not recorded |
| `kickoff_wind_ms` | null or more | Wind at kickoff, in metres a second; null when not recorded |
| `attendance` | integer | The crowd; null when not recorded |
| `referee_name` | string | The referee |
| `regular_time_home_goals` | integer | Home goals after 90 minutes and added time |
| `regular_time_away_goals` | integer | Away goals after 90 minutes and added time |
| `regular_time_result` | string | home, away or draw, after 90 minutes and added time |
| `extra_time_home_goals` | null or more | Home goals after extra time; null when there was none |
| `extra_time_away_goals` | null or more | Away goals after extra time; null when there was none |
| `shootout_home_goals` | null or more | Home penalties scored in a shootout; null when there was none |
| `shootout_away_goals` | null or more | Away penalties scored in a shootout; null when there was none |
| `home_formation` | string | The home side's formation, such as 4-2-3-1 |
| `away_formation` | string | The away side's formation |
| `ground_id` | string | Our id for the ground, gd_ and 9 characters |
| `capacity` | integer | How many the ground holds |
| `surface` | string | The pitch, such as grass |
| `club_figures` | object | Each side's figures for the match |
| `club_figures.home` | object | The home side |
| `club_figures.home.xg` | number | Expected goals |
| `club_figures.home.xg_estimate` | number | Expected goals worked out from the shots and the other figures |
| `club_figures.home.shots` | integer | Shots |
| `club_figures.home.shots_on_target` | integer | Shots on target |
| `club_figures.home.corners` | integer | Corners |
| `club_figures.home.fouls` | integer | Fouls committed |
| `club_figures.home.yellow_cards` | integer | Yellow cards |
| `club_figures.home.red_cards` | integer | Red cards |
| `club_figures.home.possession_pct` | integer | Share of the ball, as a percentage |
| `club_figures.away` | object | The away side |
| `club_figures.away.xg` | number | Expected goals |
| `club_figures.away.xg_estimate` | number | Expected goals worked out from the shots and the other figures |
| `club_figures.away.shots` | integer | Shots |
| `club_figures.away.shots_on_target` | integer | Shots on target |
| `club_figures.away.corners` | integer | Corners |
| `club_figures.away.fouls` | integer | Fouls committed |
| `club_figures.away.yellow_cards` | integer | Yellow cards |
| `club_figures.away.red_cards` | integer | Red cards |
| `club_figures.away.possession_pct` | integer | Share of the ball, as a percentage |
| `stats` | list | Each side's figures for the match |
| `stats[].club_name` | string | The club |
| `stats[].stats` | object | Each side's figures for the match |
| `stats[].stats.corners` | integer | Corners |
| `stats[].stats.expected_goals` | number | Expected goals |
| `stats[].stats.fouls` | integer | Fouls committed |
| `stats[].stats.free_kicks` | integer | Free kicks |
| `stats[].stats.offsides` | integer | Times caught offside |
| `stats[].stats.passes_accurate` | integer | Passes that reached a team-mate |
| `stats[].stats.passes_total` | integer | Passes |
| `stats[].stats.possession_pct` | integer | Share of the ball, as a percentage |
| `stats[].stats.red_cards` | integer | Red cards |
| `stats[].stats.saves` | integer | Saves by the goalkeeper |
| `stats[].stats.shots_blocked` | integer | Shots blocked |
| `stats[].stats.shots_inside_box` | integer | Shots from inside the penalty area |
| `stats[].stats.shots_off_target` | integer | Shots off target |
| `stats[].stats.shots_on_target` | integer | Shots on target |
| `stats[].stats.shots_outside_box` | integer | Shots from outside the penalty area |
| `stats[].stats.shots_total` | integer | Shots |
| `stats[].stats.yellow_cards` | integer | Yellow cards |

```bash
curl "https://api.footballapi.org/v1/matches/mt_95kf4jw9a" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": {
        "match_id": "mt_95kf4jw9a",
        "competition": "premier-league",
        "country_name": "England",
        "competition_name": "Premier League",
        "season_start_year": 2026,
        "kickoff_utc": "2026-10-19T19:00:00Z",
        "kickoff_date": "2026-10-19",
        "kickoff_local_date": "2026-10-19",
        "kickoff_local_time": "19:00",
        "match_status": "finished",
        "home_club_id": "cl_4x2bczxvv",
        "home_club_name": "Tottenham",
        "away_club_id": "cl_frt0n2e46",
        "away_club_name": "Coventry",
        "home_goals": 3,
        "away_goals": 1,
        "full_time_result": "home",
        "half_time_home_goals": 1,
        "half_time_away_goals": 0,
        "half_time_result": "home",
        "stoppage_minutes": null,
        "is_kickoff_rescheduled": false,
        "elapsed_minutes": null,
        "home_league_position": 20,
        "away_league_position": 16,
        "away_travel_km": 135,
        "ground_name": "Tottenham Hotspur Stadium",
        "city_name": "London",
        "latitude": 51.604444444444,
        "longitude": -0.066388888888889,
        "location_precision": "ground",
        "daylight_minutes": 630,
        "sun_elevation_deg": -19.3,
        "public_holiday": null,
        "kickoff_temperature_c": null,
        "kickoff_rain_mm": null,
        "kickoff_wind_ms": null,
        "attendance": 60913,
        "referee_name": "Andrew Madley",
        "regular_time_home_goals": 3,
        "regular_time_away_goals": 1,
        "regular_time_result": "home",
        "extra_time_home_goals": null,
        "extra_time_away_goals": null,
        "shootout_home_goals": null,
        "shootout_away_goals": null,
        "home_formation": "3-4-2-1",
        "away_formation": "4-2-3-1",
        "ground_id": "gd_4wv42jcr4",
        "capacity": 62850,
        "surface": "grass",
        "club_figures": {
            "home": {
                "xg": 0.9,
                "xg_estimate": 1.66,
                "shots": 16,
                "shots_on_target": 5,
                "corners": 4,
                "fouls": 15,
                "yellow_cards": 1,
                "red_cards": 0,
                "possession_pct": 66
            },
            "away": {
                "xg": 0.83,
                "xg_estimate": 1.34,
                "shots": 12,
                "shots_on_target": 1,
                "corners": 4,
                "fouls": 14,
                "yellow_cards": 3,
                "red_cards": 0,
                "possession_pct": 34
            }
        },
        "stats": [
            {
                "club_name": "Tottenham",
                "stats": {
                    "corners": 4,
                    "expected_goals": 0.9,
                    "fouls": 15,
                    "free_kicks": 14,
                    "offsides": 6,
                    "passes_accurate": 499,
                    "passes_total": 559,
                    "possession_pct": 66,
                    "red_cards": 0,
                    "saves": 0,
                    "shots_blocked": 4,
                    "shots_inside_box": 10,
                    "shots_off_target": 7,
                    "shots_on_target": 5,
                    "shots_outside_box": 6,
                    "shots_total": 16,
                    "yellow_cards": 1
                }
            },
            {
                "club_name": "Coventry",
                "stats": {
                    "corners": 4,
                    "expected_goals": 0.83,
                    "fouls": 14,
                    "free_kicks": 15,
                    "offsides": 1,
                    "passes_accurate": 221,
                    "passes_total": 285,
                    "possession_pct": 34,
                    "red_cards": 0,
                    "saves": 2,
                    "shots_blocked": 4,
                    "shots_inside_box": 11,
                    "shots_off_target": 7,
                    "shots_on_target": 1,
                    "shots_outside_box": 1,
                    "shots_total": 12,
                    "yellow_cards": 3
                }
            }
        ]
    },
    "meta": {
        "request_id": "req_06c6b9a0356d2a31"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Events

`GET /v1/matches/{match_id}/events`  
Complimentary key: this season's Premier League.

Every goal and card of a match, in the order it happened, to the minute.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `match_id` | string | yes | A match id from any result, fixture or match list, such as mt_e2hk79mn5. In the path. |

| Field | Type | What it is |
|---|---|---|
| `match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `country_name` | string | The country, or World or Europe for a tournament |
| `competition_name` | string | The competition as people write it |
| `home_club_id` | string | Our id for the home club |
| `home_club_name` | string | The home club |
| `away_club_id` | string | Our id for the away club |
| `away_club_name` | string | The away club |
| `home_goals` | integer | Home goals at full time |
| `away_goals` | integer | Away goals at full time |
| `half_time` | object | The score at half time |
| `half_time.home` | integer | The home side |
| `half_time.away` | integer | The away side |
| `stoppage_minutes` | null or more | Minutes of added time; null when not recorded |
| `has_events` | boolean | Whether goals and cards are recorded for this match |
| `goals` | integer | Goals in the match |
| `red_cards` | integer | Red cards |
| `timeline` | list | Each goal and card, in the order it happened |
| `timeline[].type` | string | What happened |
| `timeline[].minute` | string | The minute of the match |
| `timeline[].club_name` | string | The club |

```bash
curl "https://api.footballapi.org/v1/matches/mt_95kf4jw9a/events" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": {
        "match_id": "mt_95kf4jw9a",
        "kickoff_date": "2026-10-19",
        "country_name": "England",
        "competition_name": "Premier League",
        "home_club_id": "cl_4x2bczxvv",
        "home_club_name": "Tottenham",
        "away_club_id": "cl_frt0n2e46",
        "away_club_name": "Coventry",
        "home_goals": 3,
        "away_goals": 1,
        "half_time": {
            "home": 1,
            "away": 0
        },
        "stoppage_minutes": null,
        "has_events": true,
        "goals": 4,
        "red_cards": 0,
        "timeline": [
            {
                "type": "goal",
                "minute": "14",
                "club_name": "Tottenham"
            },
            {
                "type": "goal",
                "minute": "49",
                "club_name": "Coventry"
            },
            {
                "type": "goal",
                "minute": "58",
                "club_name": "Tottenham"
            }
        ]
    },
    "meta": {
        "count": 0,
        "request_id": "req_b24aa3ae4ad27f98"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Match stats

`GET /v1/matches/{match_id}/stats`  
Complimentary key: this season's Premier League.

Each side's figures for a match: shots, shots on target, possession, passes, corners, fouls, offsides, cards and expected goals.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `match_id` | string | yes | A match id from any result, fixture or match list, such as mt_e2hk79mn5. In the path. |

| Field | Type | What it is |
|---|---|---|
| `match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `home_club_name` | string | The home club |
| `away_club_name` | string | The away club |
| `kickoff_utc` | string | Kickoff in UTC, ISO 8601 |
| `match_status` | string | Where the match stands, such as finished or not started |
| `stats` | list | Each side's figures for the match |
| `stats[].club_name` | string | The club |
| `stats[].stats` | object | Each side's figures for the match |
| `stats[].stats.corners` | integer | Corners |
| `stats[].stats.expected_goals` | number | Expected goals |
| `stats[].stats.fouls` | integer | Fouls committed |
| `stats[].stats.free_kicks` | integer | Free kicks |
| `stats[].stats.offsides` | integer | Times caught offside |
| `stats[].stats.passes_accurate` | integer | Passes that reached a team-mate |
| `stats[].stats.passes_total` | integer | Passes |
| `stats[].stats.possession_pct` | integer | Share of the ball, as a percentage |
| `stats[].stats.red_cards` | integer | Red cards |
| `stats[].stats.saves` | integer | Saves by the goalkeeper |
| `stats[].stats.shots_blocked` | integer | Shots blocked |
| `stats[].stats.shots_inside_box` | integer | Shots from inside the penalty area |
| `stats[].stats.shots_off_target` | integer | Shots off target |
| `stats[].stats.shots_on_target` | integer | Shots on target |
| `stats[].stats.shots_outside_box` | integer | Shots from outside the penalty area |
| `stats[].stats.shots_total` | integer | Shots |
| `stats[].stats.yellow_cards` | integer | Yellow cards |

```bash
curl "https://api.footballapi.org/v1/matches/mt_95kf4jw9a/stats" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": {
        "match_id": "mt_95kf4jw9a",
        "home_club_name": "Tottenham",
        "away_club_name": "Coventry",
        "kickoff_utc": "2026-10-19T19:00:00Z",
        "match_status": "finished",
        "stats": [
            {
                "club_name": "Tottenham",
                "stats": {
                    "corners": 4,
                    "expected_goals": 0.9,
                    "fouls": 15,
                    "free_kicks": 14,
                    "offsides": 6,
                    "passes_accurate": 499,
                    "passes_total": 559,
                    "possession_pct": 66,
                    "red_cards": 0,
                    "saves": 0,
                    "shots_blocked": 4,
                    "shots_inside_box": 10,
                    "shots_off_target": 7,
                    "shots_on_target": 5,
                    "shots_outside_box": 6,
                    "shots_total": 16,
                    "yellow_cards": 1
                }
            },
            {
                "club_name": "Coventry",
                "stats": {
                    "corners": 4,
                    "expected_goals": 0.83,
                    "fouls": 14,
                    "free_kicks": 15,
                    "offsides": 1,
                    "passes_accurate": 221,
                    "passes_total": 285,
                    "possession_pct": 34,
                    "red_cards": 0,
                    "saves": 2,
                    "shots_blocked": 4,
                    "shots_inside_box": 11,
                    "shots_off_target": 7,
                    "shots_on_target": 1,
                    "shots_outside_box": 1,
                    "shots_total": 12,
                    "yellow_cards": 3
                }
            }
        ]
    },
    "meta": {
        "request_id": "req_e40600e3f584dc59"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

### Results

#### Results

`GET /v1/results`  
Complimentary key: this season's Premier League.

Settled matches newest first, by day, by date range, by competition or by club, paged. Every season goes back to 2015/16, or to the league's start.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |
| `club` | string | no | Only this club's matches: a club id such as cl_a7vhnxhhh. |
| `date` | date | no | One day, YYYY-MM-DD. |
| `date_from` | date | no | From this day, YYYY-MM-DD. |
| `date_to` | date | no | Up to this day, YYYY-MM-DD. |
| `page` | integer | no | Which page, from 1. From 1 to 100,000. |
| `per_page` | integer | no | Rows on a page. Default 100. From 1 to 1,000. |
| `cursor` | string | no | meta.next_cursor from the page before, passed back unchanged. Faster than page for long walks. |

| Field | Type | What it is |
|---|---|---|
| `match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `competition` | string | The competition's name in the collection, such as premier-league |
| `country_name` | string | The country, or World or Europe for a tournament |
| `competition_name` | string | The competition as people write it |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `kickoff_utc` | string | Kickoff in UTC, ISO 8601 |
| `kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `kickoff_local_date` | string | The day of kickoff where the match is played |
| `kickoff_local_time` | string | The time of kickoff where the match is played |
| `match_status` | string | Where the match stands, such as finished or not started |
| `home_club_id` | string | Our id for the home club |
| `home_club_name` | string | The home club |
| `away_club_id` | string | Our id for the away club |
| `away_club_name` | string | The away club |
| `home_goals` | integer | Home goals at full time |
| `away_goals` | integer | Away goals at full time |
| `full_time_result` | string | home, away or draw, at full time |
| `half_time_home_goals` | integer | Home goals at half time |
| `half_time_away_goals` | integer | Away goals at half time |
| `half_time_result` | string | home, away or draw, at half time |
| `stoppage_minutes` | null or more | Minutes of added time; null when not recorded |
| `is_kickoff_rescheduled` | boolean | Whether kickoff moved from its first date or time |
| `elapsed_minutes` | null or more | Minutes played so far while the match is on; null otherwise |
| `home_league_position` | integer | The home side's place in its league before kickoff |
| `away_league_position` | integer | The away side's place in its league before kickoff |
| `away_travel_km` | integer | How far the away side came, ground to ground, in kilometres |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `latitude` | number | Where the ground is, north to south |
| `longitude` | number | Where the ground is, east to west |
| `location_precision` | string | How exact latitude and longitude are: ground, or city |
| `daylight_minutes` | integer | Minutes of daylight that day at the ground |
| `sun_elevation_deg` | number | The sun's height at kickoff, in degrees; below 0 after dark |
| `public_holiday` | null or more | The public holiday that day where the match is played; null when none |
| `kickoff_temperature_c` | null or more | The temperature at kickoff, in degrees C; null when not recorded |
| `kickoff_rain_mm` | null or more | Rain in the hour of kickoff, in millimetres; null when not recorded |
| `kickoff_wind_ms` | null or more | Wind at kickoff, in metres a second; null when not recorded |
| `attendance` | integer | The crowd; null when not recorded |
| `referee_name` | string | The referee |
| `regular_time_home_goals` | integer | Home goals after 90 minutes and added time |
| `regular_time_away_goals` | integer | Away goals after 90 minutes and added time |
| `regular_time_result` | string | home, away or draw, after 90 minutes and added time |
| `extra_time_home_goals` | null or more | Home goals after extra time; null when there was none |
| `extra_time_away_goals` | null or more | Away goals after extra time; null when there was none |
| `shootout_home_goals` | null or more | Home penalties scored in a shootout; null when there was none |
| `shootout_away_goals` | null or more | Away penalties scored in a shootout; null when there was none |
| `club_figures` | object | Each side's figures for the match |
| `club_figures.home` | object | The home side |
| `club_figures.home.xg` | number | Expected goals |
| `club_figures.home.xg_estimate` | number | Expected goals worked out from the shots and the other figures |
| `club_figures.home.shots` | integer | Shots |
| `club_figures.home.shots_on_target` | integer | Shots on target |
| `club_figures.home.corners` | integer | Corners |
| `club_figures.home.fouls` | integer | Fouls committed |
| `club_figures.home.yellow_cards` | integer | Yellow cards |
| `club_figures.home.red_cards` | integer | Red cards |
| `club_figures.home.possession_pct` | integer | Share of the ball, as a percentage |
| `club_figures.away` | object | The away side |
| `club_figures.away.xg` | number | Expected goals |
| `club_figures.away.xg_estimate` | number | Expected goals worked out from the shots and the other figures |
| `club_figures.away.shots` | integer | Shots |
| `club_figures.away.shots_on_target` | integer | Shots on target |
| `club_figures.away.corners` | integer | Corners |
| `club_figures.away.fouls` | integer | Fouls committed |
| `club_figures.away.yellow_cards` | integer | Yellow cards |
| `club_figures.away.red_cards` | integer | Red cards |
| `club_figures.away.possession_pct` | integer | Share of the ball, as a percentage |

```bash
curl "https://api.footballapi.org/v1/results?competition=premier-league&per_page=2" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": [
        {
            "match_id": "mt_95kf4jw9a",
            "competition": "premier-league",
            "country_name": "England",
            "competition_name": "Premier League",
            "season_start_year": 2026,
            "kickoff_utc": "2026-10-19T19:00:00Z",
            "kickoff_date": "2026-10-19",
            "kickoff_local_date": "2026-10-19",
            "kickoff_local_time": "19:00",
            "match_status": "finished",
            "home_club_id": "cl_4x2bczxvv",
            "home_club_name": "Tottenham",
            "away_club_id": "cl_frt0n2e46",
            "away_club_name": "Coventry",
            "home_goals": 3,
            "away_goals": 1,
            "full_time_result": "home",
            "half_time_home_goals": 1,
            "half_time_away_goals": 0,
            "half_time_result": "home",
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": 20,
            "away_league_position": 16,
            "away_travel_km": 135,
            "ground_name": "Tottenham Hotspur Stadium",
            "city_name": "London",
            "latitude": 51.604444444444,
            "longitude": -0.066388888888889,
            "location_precision": "ground",
            "daylight_minutes": 630,
            "sun_elevation_deg": -19.3,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": 60913,
            "referee_name": "Andrew Madley",
            "regular_time_home_goals": 3,
            "regular_time_away_goals": 1,
            "regular_time_result": "home",
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": {
                "home": {
                    "xg": 0.9,
                    "xg_estimate": 1.66,
                    "shots": 16,
                    "shots_on_target": 5,
                    "corners": 4,
                    "fouls": 15,
                    "yellow_cards": 1,
                    "red_cards": 0,
                    "possession_pct": 66
                },
                "away": {
                    "xg": 0.83,
                    "xg_estimate": 1.34,
                    "shots": 12,
                    "shots_on_target": 1,
                    "corners": 4,
                    "fouls": 14,
                    "yellow_cards": 3,
                    "red_cards": 0,
                    "possession_pct": 34
                }
            }
        },
        {
            "match_id": "mt_3pfb14gzr",
            "competition": "premier-league",
            "country_name": "England",
            "competition_name": "Premier League",
            "season_start_year": 2026,
            "kickoff_utc": "2026-10-18T15:30:00Z",
            "kickoff_date": "2026-10-18",
            "kickoff_local_date": "2026-10-18",
            "kickoff_local_time": "15:30",
            "match_status": "finished",
            "home_club_id": "cl_5bvjqjxyw",
            "home_club_name": "Nottingham Forest",
            "away_club_id": "cl_9cbmhewrg",
            "away_club_name": "Arsenal",
            "home_goals": 0,
            "away_goals": 1,
            "full_time_result": "away",
            "half_time_home_goals": 0,
            "half_time_away_goals": 0,
            "half_time_result": "draw",
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": 18,
            "away_league_position": 3,
            "away_travel_km": 169,
            "ground_name": "City Ground",
            "city_name": "Nottingham",
            "latitude": 52.94,
            "longitude": -1.132778,
            "location_precision": "ground",
            "daylight_minutes": 630,
            "sun_elevation_deg": 12.1,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": 30893,
            "referee_name": "Michael Oliver",
            "regular_time_home_goals": 0,
            "regular_time_away_goals": 1,
            "regular_time_result": "away",
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": {
                "home": {
                    "xg": 0.79,
                    "xg_estimate": 1.1,
                    "shots": 14,
                    "shots_on_target": 2,
                    "corners": 8,
                    "fouls": 14,
                    "yellow_cards": 1,
                    "red_cards": 0,
                    "possession_pct": 26
                },
                "away": {
                    "xg": 1.09,
                    "xg_estimate": 0.89,
                    "shots": 9,
                    "shots_on_target": 1,
                    "corners": 6,
                    "fouls": 8,
                    "yellow_cards": 1,
                    "red_cards": 0,
                    "possession_pct": 74
                }
            }
        }
    ],
    "meta": {
        "count": 2,
        "page": 1,
        "per_page": 2,
        "total": 14446,
        "total_pages": 7223,
        "next_page": 2,
        "prev_page": null,
        "next_cursor": "uAIfpUPNnzUavfl_M-pg_XaOxXFDwItzDe9-0s_bm5TCAvcK_roiyZ88DdhFqRM1ovRYfw",
        "request_id": "req_dc5191a88e65250a"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Today

`GET /v1/results/today`  
Complimentary key: this season's Premier League.

Every match settled today so far, by the UTC calendar, in every competition your key reads.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |

| Field | Type | What it is |
|---|---|---|
| `match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `competition` | string | The competition's name in the collection, such as premier-league |
| `country_name` | string | The country, or World or Europe for a tournament |
| `competition_name` | string | The competition as people write it |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `kickoff_utc` | string | Kickoff in UTC, ISO 8601 |
| `kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `kickoff_local_date` | string | The day of kickoff where the match is played |
| `kickoff_local_time` | string | The time of kickoff where the match is played |
| `match_status` | string | Where the match stands, such as finished or not started |
| `home_club_id` | string | Our id for the home club |
| `home_club_name` | string | The home club |
| `away_club_id` | string | Our id for the away club |
| `away_club_name` | string | The away club |
| `home_goals` | integer | Home goals at full time |
| `away_goals` | integer | Away goals at full time |
| `full_time_result` | string | home, away or draw, at full time |
| `half_time_home_goals` | integer | Home goals at half time |
| `half_time_away_goals` | integer | Away goals at half time |
| `half_time_result` | string | home, away or draw, at half time |
| `stoppage_minutes` | null or more | Minutes of added time; null when not recorded |
| `is_kickoff_rescheduled` | boolean | Whether kickoff moved from its first date or time |
| `elapsed_minutes` | null or more | Minutes played so far while the match is on; null otherwise |
| `home_league_position` | integer | The home side's place in its league before kickoff |
| `away_league_position` | integer | The away side's place in its league before kickoff |
| `away_travel_km` | integer | How far the away side came, ground to ground, in kilometres |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `latitude` | number | Where the ground is, north to south |
| `longitude` | number | Where the ground is, east to west |
| `location_precision` | string | How exact latitude and longitude are: ground, or city |
| `daylight_minutes` | integer | Minutes of daylight that day at the ground |
| `sun_elevation_deg` | integer | The sun's height at kickoff, in degrees; below 0 after dark |
| `public_holiday` | null or more | The public holiday that day where the match is played; null when none |
| `kickoff_temperature_c` | null or more | The temperature at kickoff, in degrees C; null when not recorded |
| `kickoff_rain_mm` | null or more | Rain in the hour of kickoff, in millimetres; null when not recorded |
| `kickoff_wind_ms` | null or more | Wind at kickoff, in metres a second; null when not recorded |
| `attendance` | null or more | The crowd; null when not recorded |
| `referee_name` | string | The referee |
| `regular_time_home_goals` | integer | Home goals after 90 minutes and added time |
| `regular_time_away_goals` | integer | Away goals after 90 minutes and added time |
| `regular_time_result` | string | home, away or draw, after 90 minutes and added time |
| `extra_time_home_goals` | null or more | Home goals after extra time; null when there was none |
| `extra_time_away_goals` | null or more | Away goals after extra time; null when there was none |
| `shootout_home_goals` | null or more | Home penalties scored in a shootout; null when there was none |
| `shootout_away_goals` | null or more | Away penalties scored in a shootout; null when there was none |
| `club_figures` | object | Each side's figures for the match |
| `club_figures.home` | object | The home side |
| `club_figures.home.xg` | number | Expected goals |
| `club_figures.home.xg_estimate` | number | Expected goals worked out from the shots and the other figures |
| `club_figures.home.shots` | integer | Shots |
| `club_figures.home.shots_on_target` | integer | Shots on target |
| `club_figures.home.corners` | integer | Corners |
| `club_figures.home.fouls` | integer | Fouls committed |
| `club_figures.home.yellow_cards` | integer | Yellow cards |
| `club_figures.home.red_cards` | integer | Red cards |
| `club_figures.home.possession_pct` | integer | Share of the ball, as a percentage |
| `club_figures.away` | object | The away side |
| `club_figures.away.xg` | number | Expected goals |
| `club_figures.away.xg_estimate` | number | Expected goals worked out from the shots and the other figures |
| `club_figures.away.shots` | integer | Shots |
| `club_figures.away.shots_on_target` | integer | Shots on target |
| `club_figures.away.corners` | integer | Corners |
| `club_figures.away.fouls` | integer | Fouls committed |
| `club_figures.away.yellow_cards` | integer | Yellow cards |
| `club_figures.away.red_cards` | integer | Red cards |
| `club_figures.away.possession_pct` | integer | Share of the ball, as a percentage |

```bash
curl "https://api.footballapi.org/v1/results/today" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": [
        {
            "match_id": "mt_9297jqxps",
            "competition": "liga-mx",
            "country_name": "Mexico",
            "competition_name": "Liga MX",
            "season_start_year": 2026,
            "kickoff_utc": "2026-10-21T03:00:00Z",
            "kickoff_date": "2026-10-21",
            "kickoff_local_date": "2026-10-21",
            "kickoff_local_time": "03:00",
            "match_status": "finished",
            "home_club_id": "cl_bjjxdnf2k",
            "home_club_name": "Tigres UANL",
            "away_club_id": "cl_2gmwcrjzv",
            "away_club_name": "Leon",
            "home_goals": 0,
            "away_goals": 2,
            "full_time_result": "away",
            "half_time_home_goals": 0,
            "half_time_away_goals": 1,
            "half_time_result": "away",
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": 14,
            "away_league_position": 7,
            "away_travel_km": 530,
            "ground_name": "Estadio Universitario",
            "city_name": "Monterey",
            "latitude": 25.722805555556,
            "longitude": -100.31205555556,
            "location_precision": "ground",
            "daylight_minutes": 687,
            "sun_elevation_deg": -39,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": null,
            "referee_name": "Marco Antonio Ortiz Nava",
            "regular_time_home_goals": 0,
            "regular_time_away_goals": 2,
            "regular_time_result": "away",
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": {
                "home": {
                    "xg": 1.93,
                    "xg_estimate": 1.75,
                    "shots": 20,
                    "shots_on_target": 6,
                    "corners": 16,
                    "fouls": 5,
                    "yellow_cards": 0,
                    "red_cards": 0,
                    "possession_pct": 70
                },
                "away": {
                    "xg": 2.27,
                    "xg_estimate": 1.32,
                    "shots": 12,
                    "shots_on_target": 5,
                    "corners": 4,
                    "fouls": 18,
                    "yellow_cards": 1,
                    "red_cards": 0,
                    "possession_pct": 30
                }
            }
        },
        {
            "match_id": "mt_frd5e4m0v",
            "competition": "liga-mx",
            "country_name": "Mexico",
            "competition_name": "Liga MX",
            "season_start_year": 2026,
            "kickoff_utc": "2026-10-21T01:00:00Z",
            "kickoff_date": "2026-10-21",
            "kickoff_local_date": "2026-10-21",
            "kickoff_local_time": "01:00",
            "match_status": "finished",
            "home_club_id": "cl_65j4qj867",
            "home_club_name": "FC Juarez",
            "away_club_id": "cl_0hyxdbdzp",
            "away_club_name": "Atlante FC",
            "home_goals": 0,
            "away_goals": 1,
            "full_time_result": "away",
            "half_time_home_goals": 0,
            "half_time_away_goals": 0,
            "half_time_result": "draw",
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": 18,
            "away_league_position": 16,
            "away_travel_km": 1566,
            "ground_name": "Estadio Olímpico Benito Juárez",
            "city_name": "Ciudad Juarez",
            "latitude": 31.75305,
            "longitude": -106.467814,
            "location_precision": "ground",
            "daylight_minutes": 677,
            "sun_elevation_deg": -7.4,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": null,
            "referee_name": "Katia García",
            "regular_time_home_goals": 0,
            "regular_time_away_goals": 1,
            "regular_time_result": "away",
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": {
                "home": {
                    "xg": 0.44,
                    "xg_estimate": 0.43,
                    "shots": 7,
                    "shots_on_target": 1,
                    "corners": 8,
                    "fouls": 18,
                    "yellow_cards": 4,
                    "red_cards": 0,
                    "possession_pct": 61
                },
                "away": {
                    "xg": 0.77,
                    "xg_estimate": 1.11,
                    "shots": 10,
                    "shots_on_target": 3,
                    "corners": 9,
                    "fouls": 22,
                    "yellow_cards": 2,
                    "red_cards": 0,
                    "possession_pct": 39
                }
            }
        }
    ],
    "meta": {
        "count": 4,
        "request_id": "req_de823f78bc3591cc"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Yesterday

`GET /v1/results/yesterday`  
Complimentary key: this season's Premier League.

Every match settled yesterday, by the UTC calendar, in every competition your key reads. Pass a competition to keep to one.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |

| Field | Type | What it is |
|---|---|---|
| `match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `competition` | string | The competition's name in the collection, such as premier-league |
| `country_name` | string | The country, or World or Europe for a tournament |
| `competition_name` | string | The competition as people write it |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `kickoff_utc` | string | Kickoff in UTC, ISO 8601 |
| `kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `kickoff_local_date` | string | The day of kickoff where the match is played |
| `kickoff_local_time` | string | The time of kickoff where the match is played |
| `match_status` | string | Where the match stands, such as finished or not started |
| `home_club_id` | string | Our id for the home club |
| `home_club_name` | string | The home club |
| `away_club_id` | string | Our id for the away club |
| `away_club_name` | string | The away club |
| `home_goals` | integer | Home goals at full time |
| `away_goals` | integer | Away goals at full time |
| `full_time_result` | string | home, away or draw, at full time |
| `half_time_home_goals` | integer | Home goals at half time |
| `half_time_away_goals` | integer | Away goals at half time |
| `half_time_result` | string | home, away or draw, at half time |
| `stoppage_minutes` | null or more | Minutes of added time; null when not recorded |
| `is_kickoff_rescheduled` | boolean | Whether kickoff moved from its first date or time |
| `elapsed_minutes` | null or more | Minutes played so far while the match is on; null otherwise |
| `home_league_position` | null or more | The home side's place in its league before kickoff |
| `away_league_position` | null or more | The away side's place in its league before kickoff |
| `away_travel_km` | integer | How far the away side came, ground to ground, in kilometres |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `latitude` | number | Where the ground is, north to south |
| `longitude` | number | Where the ground is, east to west |
| `location_precision` | string | How exact latitude and longitude are: ground, or city |
| `daylight_minutes` | integer | Minutes of daylight that day at the ground |
| `sun_elevation_deg` | integer | The sun's height at kickoff, in degrees; below 0 after dark |
| `public_holiday` | null or more | The public holiday that day where the match is played; null when none |
| `kickoff_temperature_c` | null or more | The temperature at kickoff, in degrees C; null when not recorded |
| `kickoff_rain_mm` | null or more | Rain in the hour of kickoff, in millimetres; null when not recorded |
| `kickoff_wind_ms` | null or more | Wind at kickoff, in metres a second; null when not recorded |
| `attendance` | null or more | The crowd; null when not recorded |
| `referee_name` | string | The referee |
| `regular_time_home_goals` | integer | Home goals after 90 minutes and added time |
| `regular_time_away_goals` | integer | Away goals after 90 minutes and added time |
| `regular_time_result` | string | home, away or draw, after 90 minutes and added time |
| `extra_time_home_goals` | null or more | Home goals after extra time; null when there was none |
| `extra_time_away_goals` | null or more | Away goals after extra time; null when there was none |
| `shootout_home_goals` | null or more | Home penalties scored in a shootout; null when there was none |
| `shootout_away_goals` | null or more | Away penalties scored in a shootout; null when there was none |
| `club_figures` | object | Each side's figures for the match |
| `club_figures.home` | object | The home side |
| `club_figures.home.xg` | number | Expected goals |
| `club_figures.home.xg_estimate` | number | Expected goals worked out from the shots and the other figures |
| `club_figures.home.shots` | integer | Shots |
| `club_figures.home.shots_on_target` | integer | Shots on target |
| `club_figures.home.corners` | integer | Corners |
| `club_figures.home.fouls` | integer | Fouls committed |
| `club_figures.home.yellow_cards` | integer | Yellow cards |
| `club_figures.home.red_cards` | integer | Red cards |
| `club_figures.home.possession_pct` | integer | Share of the ball, as a percentage |
| `club_figures.away` | object | The away side |
| `club_figures.away.xg` | number | Expected goals |
| `club_figures.away.xg_estimate` | number | Expected goals worked out from the shots and the other figures |
| `club_figures.away.shots` | integer | Shots |
| `club_figures.away.shots_on_target` | integer | Shots on target |
| `club_figures.away.corners` | integer | Corners |
| `club_figures.away.fouls` | integer | Fouls committed |
| `club_figures.away.yellow_cards` | integer | Yellow cards |
| `club_figures.away.red_cards` | integer | Red cards |
| `club_figures.away.possession_pct` | integer | Share of the ball, as a percentage |

```bash
curl "https://api.footballapi.org/v1/results/yesterday" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": [
        {
            "match_id": "mt_5wa63w50c",
            "competition": "champions-league",
            "country_name": "World",
            "competition_name": "UEFA Champions League",
            "season_start_year": 2026,
            "kickoff_utc": "2026-10-20T19:00:00Z",
            "kickoff_date": "2026-10-20",
            "kickoff_local_date": "2026-10-20",
            "kickoff_local_time": "19:00",
            "match_status": "finished",
            "home_club_id": "cl_a61p5h89m",
            "home_club_name": "VfB Stuttgart",
            "away_club_id": "cl_1xzgy7vsr",
            "away_club_name": "Atletico Madrid",
            "home_goals": 1,
            "away_goals": 1,
            "full_time_result": "draw",
            "half_time_home_goals": 1,
            "half_time_away_goals": 0,
            "half_time_result": "home",
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": null,
            "away_league_position": null,
            "away_travel_km": 1373,
            "ground_name": "MHP Arena",
            "city_name": "Stuttgart",
            "latitude": 48.792222,
            "longitude": 9.231944,
            "location_precision": "ground",
            "daylight_minutes": 636,
            "sun_elevation_deg": -26,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": null,
            "referee_name": "Serdar Gozubuyuk",
            "regular_time_home_goals": 1,
            "regular_time_away_goals": 1,
            "regular_time_result": "draw",
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": {
                "home": {
                    "xg": 1.53,
                    "xg_estimate": 1.88,
                    "shots": 18,
                    "shots_on_target": 5,
                    "corners": 9,
                    "fouls": 15,
                    "yellow_cards": 1,
                    "red_cards": 0,
                    "possession_pct": 54
                },
                "away": {
                    "xg": 0.9,
                    "xg_estimate": 1.34,
                    "shots": 10,
                    "shots_on_target": 3,
                    "corners": 4,
                    "fouls": 7,
                    "yellow_cards": 0,
                    "red_cards": 1,
                    "possession_pct": 46
                }
            }
        },
        {
            "match_id": "mt_axv6nfqym",
            "competition": "champions-league",
            "country_name": "World",
            "competition_name": "UEFA Champions League",
            "season_start_year": 2026,
            "kickoff_utc": "2026-10-20T19:00:00Z",
            "kickoff_date": "2026-10-20",
            "kickoff_local_date": "2026-10-20",
            "kickoff_local_time": "19:00",
            "match_status": "finished",
            "home_club_id": "cl_d6zjnzmp1",
            "home_club_name": "Paris Saint Germain",
            "away_club_id": "cl_39f8dsw23",
            "away_club_name": "Barcelona",
            "home_goals": 4,
            "away_goals": 2,
            "full_time_result": "home",
            "half_time_home_goals": 1,
            "half_time_away_goals": 0,
            "half_time_result": "home",
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": null,
            "away_league_position": null,
            "away_travel_km": 830,
            "ground_name": "Parc des Princes",
            "city_name": "Paris",
            "latitude": 48.84145,
            "longitude": 2.25305,
            "location_precision": "ground",
            "daylight_minutes": 636,
            "sun_elevation_deg": -21.5,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": null,
            "referee_name": "Michael Oliver",
            "regular_time_home_goals": 4,
            "regular_time_away_goals": 2,
            "regular_time_result": "home",
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": {
                "home": {
                    "xg": 3.77,
                    "xg_estimate": 2.98,
                    "shots": 22,
                    "shots_on_target": 14,
                    "corners": 2,
                    "fouls": 11,
                    "yellow_cards": 0,
                    "red_cards": 0,
                    "possession_pct": 47
                },
                "away": {
                    "xg": 2.22,
                    "xg_estimate": 1.88,
                    "shots": 18,
                    "shots_on_target": 5,
                    "corners": 3,
                    "fouls": 10,
                    "yellow_cards": 1,
                    "red_cards": 0,
                    "possession_pct": 53
                }
            }
        }
    ],
    "meta": {
        "count": 37,
        "date": "2026-10-20",
        "request_id": "req_16422232ac350822"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Latest

`GET /v1/results/latest`  
Complimentary key: this season's Premier League.

The most recent results in every competition your key reads, newest first.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |
| `per_page` | integer | no | How many results. Default 100. From 1 to 1,000. |

| Field | Type | What it is |
|---|---|---|
| `match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `competition` | string | The competition's name in the collection, such as premier-league |
| `country_name` | string | The country, or World or Europe for a tournament |
| `competition_name` | string | The competition as people write it |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `kickoff_utc` | string | Kickoff in UTC, ISO 8601 |
| `kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `kickoff_local_date` | string | The day of kickoff where the match is played |
| `kickoff_local_time` | string | The time of kickoff where the match is played |
| `match_status` | string | Where the match stands, such as finished or not started |
| `home_club_id` | string | Our id for the home club |
| `home_club_name` | string | The home club |
| `away_club_id` | string | Our id for the away club |
| `away_club_name` | string | The away club |
| `home_goals` | integer | Home goals at full time |
| `away_goals` | integer | Away goals at full time |
| `full_time_result` | string | home, away or draw, at full time |
| `half_time_home_goals` | integer | Home goals at half time |
| `half_time_away_goals` | integer | Away goals at half time |
| `half_time_result` | string | home, away or draw, at half time |
| `stoppage_minutes` | null or more | Minutes of added time; null when not recorded |
| `is_kickoff_rescheduled` | boolean | Whether kickoff moved from its first date or time |
| `elapsed_minutes` | null or more | Minutes played so far while the match is on; null otherwise |
| `home_league_position` | integer | The home side's place in its league before kickoff |
| `away_league_position` | integer | The away side's place in its league before kickoff |
| `away_travel_km` | integer | How far the away side came, ground to ground, in kilometres |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `latitude` | number | Where the ground is, north to south |
| `longitude` | number | Where the ground is, east to west |
| `location_precision` | string | How exact latitude and longitude are: ground, or city |
| `daylight_minutes` | integer | Minutes of daylight that day at the ground |
| `sun_elevation_deg` | number | The sun's height at kickoff, in degrees; below 0 after dark |
| `public_holiday` | null or more | The public holiday that day where the match is played; null when none |
| `kickoff_temperature_c` | null or more | The temperature at kickoff, in degrees C; null when not recorded |
| `kickoff_rain_mm` | null or more | Rain in the hour of kickoff, in millimetres; null when not recorded |
| `kickoff_wind_ms` | null or more | Wind at kickoff, in metres a second; null when not recorded |
| `attendance` | integer | The crowd; null when not recorded |
| `referee_name` | string | The referee |
| `regular_time_home_goals` | integer | Home goals after 90 minutes and added time |
| `regular_time_away_goals` | integer | Away goals after 90 minutes and added time |
| `regular_time_result` | string | home, away or draw, after 90 minutes and added time |
| `extra_time_home_goals` | null or more | Home goals after extra time; null when there was none |
| `extra_time_away_goals` | null or more | Away goals after extra time; null when there was none |
| `shootout_home_goals` | null or more | Home penalties scored in a shootout; null when there was none |
| `shootout_away_goals` | null or more | Away penalties scored in a shootout; null when there was none |
| `club_figures` | object | Each side's figures for the match |
| `club_figures.home` | object | The home side |
| `club_figures.home.xg` | number | Expected goals |
| `club_figures.home.xg_estimate` | number | Expected goals worked out from the shots and the other figures |
| `club_figures.home.shots` | integer | Shots |
| `club_figures.home.shots_on_target` | integer | Shots on target |
| `club_figures.home.corners` | integer | Corners |
| `club_figures.home.fouls` | integer | Fouls committed |
| `club_figures.home.yellow_cards` | integer | Yellow cards |
| `club_figures.home.red_cards` | integer | Red cards |
| `club_figures.home.possession_pct` | integer | Share of the ball, as a percentage |
| `club_figures.away` | object | The away side |
| `club_figures.away.xg` | number | Expected goals |
| `club_figures.away.xg_estimate` | number | Expected goals worked out from the shots and the other figures |
| `club_figures.away.shots` | integer | Shots |
| `club_figures.away.shots_on_target` | integer | Shots on target |
| `club_figures.away.corners` | integer | Corners |
| `club_figures.away.fouls` | integer | Fouls committed |
| `club_figures.away.yellow_cards` | integer | Yellow cards |
| `club_figures.away.red_cards` | integer | Red cards |
| `club_figures.away.possession_pct` | integer | Share of the ball, as a percentage |

```bash
curl "https://api.footballapi.org/v1/results/latest?competition=premier-league&per_page=2" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": [
        {
            "match_id": "mt_95kf4jw9a",
            "competition": "premier-league",
            "country_name": "England",
            "competition_name": "Premier League",
            "season_start_year": 2026,
            "kickoff_utc": "2026-10-19T19:00:00Z",
            "kickoff_date": "2026-10-19",
            "kickoff_local_date": "2026-10-19",
            "kickoff_local_time": "19:00",
            "match_status": "finished",
            "home_club_id": "cl_4x2bczxvv",
            "home_club_name": "Tottenham",
            "away_club_id": "cl_frt0n2e46",
            "away_club_name": "Coventry",
            "home_goals": 3,
            "away_goals": 1,
            "full_time_result": "home",
            "half_time_home_goals": 1,
            "half_time_away_goals": 0,
            "half_time_result": "home",
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": 20,
            "away_league_position": 16,
            "away_travel_km": 135,
            "ground_name": "Tottenham Hotspur Stadium",
            "city_name": "London",
            "latitude": 51.604444444444,
            "longitude": -0.066388888888889,
            "location_precision": "ground",
            "daylight_minutes": 630,
            "sun_elevation_deg": -19.3,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": 60913,
            "referee_name": "Andrew Madley",
            "regular_time_home_goals": 3,
            "regular_time_away_goals": 1,
            "regular_time_result": "home",
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": {
                "home": {
                    "xg": 0.9,
                    "xg_estimate": 1.66,
                    "shots": 16,
                    "shots_on_target": 5,
                    "corners": 4,
                    "fouls": 15,
                    "yellow_cards": 1,
                    "red_cards": 0,
                    "possession_pct": 66
                },
                "away": {
                    "xg": 0.83,
                    "xg_estimate": 1.34,
                    "shots": 12,
                    "shots_on_target": 1,
                    "corners": 4,
                    "fouls": 14,
                    "yellow_cards": 3,
                    "red_cards": 0,
                    "possession_pct": 34
                }
            }
        },
        {
            "match_id": "mt_3pfb14gzr",
            "competition": "premier-league",
            "country_name": "England",
            "competition_name": "Premier League",
            "season_start_year": 2026,
            "kickoff_utc": "2026-10-18T15:30:00Z",
            "kickoff_date": "2026-10-18",
            "kickoff_local_date": "2026-10-18",
            "kickoff_local_time": "15:30",
            "match_status": "finished",
            "home_club_id": "cl_5bvjqjxyw",
            "home_club_name": "Nottingham Forest",
            "away_club_id": "cl_9cbmhewrg",
            "away_club_name": "Arsenal",
            "home_goals": 0,
            "away_goals": 1,
            "full_time_result": "away",
            "half_time_home_goals": 0,
            "half_time_away_goals": 0,
            "half_time_result": "draw",
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": 18,
            "away_league_position": 3,
            "away_travel_km": 169,
            "ground_name": "City Ground",
            "city_name": "Nottingham",
            "latitude": 52.94,
            "longitude": -1.132778,
            "location_precision": "ground",
            "daylight_minutes": 630,
            "sun_elevation_deg": 12.1,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": 30893,
            "referee_name": "Michael Oliver",
            "regular_time_home_goals": 0,
            "regular_time_away_goals": 1,
            "regular_time_result": "away",
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": {
                "home": {
                    "xg": 0.79,
                    "xg_estimate": 1.1,
                    "shots": 14,
                    "shots_on_target": 2,
                    "corners": 8,
                    "fouls": 14,
                    "yellow_cards": 1,
                    "red_cards": 0,
                    "possession_pct": 26
                },
                "away": {
                    "xg": 1.09,
                    "xg_estimate": 0.89,
                    "shots": 9,
                    "shots_on_target": 1,
                    "corners": 6,
                    "fouls": 8,
                    "yellow_cards": 1,
                    "red_cards": 0,
                    "possession_pct": 74
                }
            }
        }
    ],
    "meta": {
        "count": 2,
        "request_id": "req_e179a48a7c4b5836"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

### Fixtures

#### Fixtures

`GET /v1/fixtures`  
Complimentary key: this season's Premier League.

Matches still to come in the competitions your key reads, soonest first, with kickoff in UTC and the local date.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |
| `date_from` | date | no | From this day, YYYY-MM-DD. |
| `date_to` | date | no | Up to this day, YYYY-MM-DD. |
| `page` | integer | no | Which page, from 1. From 1 to 100,000. |
| `per_page` | integer | no | Rows on a page. Default 100. From 1 to 1,000. |

| Field | Type | What it is |
|---|---|---|
| `match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `competition` | string | The competition's name in the collection, such as premier-league |
| `country_name` | string | The country, or World or Europe for a tournament |
| `competition_name` | string | The competition as people write it |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `kickoff_utc` | string | Kickoff in UTC, ISO 8601 |
| `kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `kickoff_local_date` | string | The day of kickoff where the match is played |
| `kickoff_local_time` | string | The time of kickoff where the match is played |
| `match_status` | string | Where the match stands, such as finished or not started |
| `home_club_id` | string | Our id for the home club |
| `home_club_name` | string | The home club |
| `away_club_id` | string | Our id for the away club |
| `away_club_name` | string | The away club |
| `home_goals` | null or more | Home goals at full time |
| `away_goals` | null or more | Away goals at full time |
| `full_time_result` | null or more | home, away or draw, at full time |
| `half_time_home_goals` | null or more | Home goals at half time |
| `half_time_away_goals` | null or more | Away goals at half time |
| `half_time_result` | null or more | home, away or draw, at half time |
| `stoppage_minutes` | null or more | Minutes of added time; null when not recorded |
| `is_kickoff_rescheduled` | boolean | Whether kickoff moved from its first date or time |
| `elapsed_minutes` | null or more | Minutes played so far while the match is on; null otherwise |
| `home_league_position` | integer | The home side's place in its league before kickoff |
| `away_league_position` | integer | The away side's place in its league before kickoff |
| `away_travel_km` | integer | How far the away side came, ground to ground, in kilometres |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `latitude` | number | Where the ground is, north to south |
| `longitude` | number | Where the ground is, east to west |
| `location_precision` | string | How exact latitude and longitude are: ground, or city |
| `daylight_minutes` | integer | Minutes of daylight that day at the ground |
| `sun_elevation_deg` | number | The sun's height at kickoff, in degrees; below 0 after dark |
| `public_holiday` | null or more | The public holiday that day where the match is played; null when none |
| `kickoff_temperature_c` | null or more | The temperature at kickoff, in degrees C; null when not recorded |
| `kickoff_rain_mm` | null or more | Rain in the hour of kickoff, in millimetres; null when not recorded |
| `kickoff_wind_ms` | null or more | Wind at kickoff, in metres a second; null when not recorded |
| `attendance` | null or more | The crowd; null when not recorded |
| `referee_name` | null or more | The referee |
| `regular_time_home_goals` | null or more | Home goals after 90 minutes and added time |
| `regular_time_away_goals` | null or more | Away goals after 90 minutes and added time |
| `regular_time_result` | null or more | home, away or draw, after 90 minutes and added time |
| `extra_time_home_goals` | null or more | Home goals after extra time; null when there was none |
| `extra_time_away_goals` | null or more | Away goals after extra time; null when there was none |
| `shootout_home_goals` | null or more | Home penalties scored in a shootout; null when there was none |
| `shootout_away_goals` | null or more | Away penalties scored in a shootout; null when there was none |
| `club_figures` | null or more | Each side's figures for the match |

```bash
curl "https://api.footballapi.org/v1/fixtures?competition=premier-league&per_page=2" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": [
        {
            "match_id": "mt_47y6n1wr1",
            "competition": "premier-league",
            "country_name": "England",
            "competition_name": "Premier League",
            "season_start_year": 2026,
            "kickoff_utc": "2026-10-23T19:00:00Z",
            "kickoff_date": "2026-10-23",
            "kickoff_local_date": "2026-10-23",
            "kickoff_local_time": "19:00",
            "match_status": "scheduled",
            "home_club_id": "cl_6hrwkbdmn",
            "home_club_name": "Ipswich",
            "away_club_id": "cl_5bvjqjxyw",
            "away_club_name": "Nottingham Forest",
            "home_goals": null,
            "away_goals": null,
            "full_time_result": null,
            "half_time_home_goals": null,
            "half_time_away_goals": null,
            "half_time_result": null,
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": 10,
            "away_league_position": 19,
            "away_travel_km": 183,
            "ground_name": "Portman Road Stadium",
            "city_name": "Ipswich",
            "latitude": 52.059444444444,
            "longitude": 1.1555555555556,
            "location_precision": "city",
            "daylight_minutes": 613,
            "sun_elevation_deg": -21.2,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": null,
            "referee_name": null,
            "regular_time_home_goals": null,
            "regular_time_away_goals": null,
            "regular_time_result": null,
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": null
        },
        {
            "match_id": "mt_2yj81sb7s",
            "competition": "premier-league",
            "country_name": "England",
            "competition_name": "Premier League",
            "season_start_year": 2026,
            "kickoff_utc": "2026-10-24T11:30:00Z",
            "kickoff_date": "2026-10-24",
            "kickoff_local_date": "2026-10-24",
            "kickoff_local_time": "11:30",
            "match_status": "scheduled",
            "home_club_id": "cl_7me91q2ds",
            "home_club_name": "Aston Villa",
            "away_club_id": "cl_a7vhnxhhh",
            "away_club_name": "Manchester City",
            "home_goals": null,
            "away_goals": null,
            "full_time_result": null,
            "half_time_home_goals": null,
            "half_time_away_goals": null,
            "half_time_result": null,
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": 12,
            "away_league_position": 1,
            "away_travel_km": 110,
            "ground_name": "Villa Park",
            "city_name": "Birmingham",
            "latitude": 52.509166666667,
            "longitude": -1.8847222222222,
            "location_precision": "ground",
            "daylight_minutes": 609,
            "sun_elevation_deg": 25.8,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": null,
            "referee_name": null,
            "regular_time_home_goals": null,
            "regular_time_away_goals": null,
            "regular_time_result": null,
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": null
        }
    ],
    "meta": {
        "count": 2,
        "page": 1,
        "per_page": 2,
        "total": 30,
        "total_pages": 15,
        "next_page": 2,
        "prev_page": null,
        "next_cursor": null,
        "request_id": "req_ccace595cb6e7d84"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Today

`GET /v1/fixtures/today`  
Complimentary key: this season's Premier League.

Every match kicking off today, by the UTC calendar, in every competition your key reads.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |

| Field | Type | What it is |
|---|---|---|
| `match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `competition` | string | The competition's name in the collection, such as premier-league |
| `country_name` | string | The country, or World or Europe for a tournament |
| `competition_name` | string | The competition as people write it |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `kickoff_utc` | string | Kickoff in UTC, ISO 8601 |
| `kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `kickoff_local_date` | string | The day of kickoff where the match is played |
| `kickoff_local_time` | string | The time of kickoff where the match is played |
| `match_status` | string | Where the match stands, such as finished or not started |
| `home_club_id` | string | Our id for the home club |
| `home_club_name` | string | The home club |
| `away_club_id` | string | Our id for the away club |
| `away_club_name` | string | The away club |
| `home_goals` | integer | Home goals at full time |
| `away_goals` | integer | Away goals at full time |
| `full_time_result` | string | home, away or draw, at full time |
| `half_time_home_goals` | integer | Home goals at half time |
| `half_time_away_goals` | integer | Away goals at half time |
| `half_time_result` | string | home, away or draw, at half time |
| `stoppage_minutes` | null or more | Minutes of added time; null when not recorded |
| `is_kickoff_rescheduled` | boolean | Whether kickoff moved from its first date or time |
| `elapsed_minutes` | null or more | Minutes played so far while the match is on; null otherwise |
| `home_league_position` | integer | The home side's place in its league before kickoff |
| `away_league_position` | integer | The away side's place in its league before kickoff |
| `away_travel_km` | integer | How far the away side came, ground to ground, in kilometres |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `latitude` | number | Where the ground is, north to south |
| `longitude` | number | Where the ground is, east to west |
| `location_precision` | string | How exact latitude and longitude are: ground, or city |
| `daylight_minutes` | integer | Minutes of daylight that day at the ground |
| `sun_elevation_deg` | number | The sun's height at kickoff, in degrees; below 0 after dark |
| `public_holiday` | null or more | The public holiday that day where the match is played; null when none |
| `kickoff_temperature_c` | null or more | The temperature at kickoff, in degrees C; null when not recorded |
| `kickoff_rain_mm` | null or more | Rain in the hour of kickoff, in millimetres; null when not recorded |
| `kickoff_wind_ms` | null or more | Wind at kickoff, in metres a second; null when not recorded |
| `attendance` | null or more | The crowd; null when not recorded |
| `referee_name` | string | The referee |
| `regular_time_home_goals` | integer | Home goals after 90 minutes and added time |
| `regular_time_away_goals` | integer | Away goals after 90 minutes and added time |
| `regular_time_result` | string | home, away or draw, after 90 minutes and added time |
| `extra_time_home_goals` | null or more | Home goals after extra time; null when there was none |
| `extra_time_away_goals` | null or more | Away goals after extra time; null when there was none |
| `shootout_home_goals` | null or more | Home penalties scored in a shootout; null when there was none |
| `shootout_away_goals` | null or more | Away penalties scored in a shootout; null when there was none |
| `club_figures` | object | Each side's figures for the match |
| `club_figures.home` | object | The home side |
| `club_figures.home.xg` | number | Expected goals |
| `club_figures.home.xg_estimate` | number | Expected goals worked out from the shots and the other figures |
| `club_figures.home.shots` | integer | Shots |
| `club_figures.home.shots_on_target` | integer | Shots on target |
| `club_figures.home.corners` | integer | Corners |
| `club_figures.home.fouls` | integer | Fouls committed |
| `club_figures.home.yellow_cards` | integer | Yellow cards |
| `club_figures.home.red_cards` | integer | Red cards |
| `club_figures.home.possession_pct` | integer | Share of the ball, as a percentage |
| `club_figures.away` | object | The away side |
| `club_figures.away.xg` | number | Expected goals |
| `club_figures.away.xg_estimate` | number | Expected goals worked out from the shots and the other figures |
| `club_figures.away.shots` | integer | Shots |
| `club_figures.away.shots_on_target` | integer | Shots on target |
| `club_figures.away.corners` | integer | Corners |
| `club_figures.away.fouls` | integer | Fouls committed |
| `club_figures.away.yellow_cards` | integer | Yellow cards |
| `club_figures.away.red_cards` | integer | Red cards |
| `club_figures.away.possession_pct` | integer | Share of the ball, as a percentage |

```bash
curl "https://api.footballapi.org/v1/fixtures/today" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": [
        {
            "match_id": "mt_8d5d38f0m",
            "competition": "liga-mx",
            "country_name": "Mexico",
            "competition_name": "Liga MX",
            "season_start_year": 2026,
            "kickoff_utc": "2026-10-21T00:07:00Z",
            "kickoff_date": "2026-10-21",
            "kickoff_local_date": "2026-10-21",
            "kickoff_local_time": "00:07",
            "match_status": "finished",
            "home_club_id": "cl_2fvpjhwam",
            "home_club_name": "Guadalajara Chivas",
            "away_club_id": "cl_6ch6x31ew",
            "away_club_name": "Necaxa",
            "home_goals": 1,
            "away_goals": 0,
            "full_time_result": "home",
            "half_time_home_goals": 0,
            "half_time_away_goals": 0,
            "half_time_result": "draw",
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": 4,
            "away_league_position": 17,
            "away_travel_km": 181,
            "ground_name": "Estadio Akron",
            "city_name": "Guadalajara",
            "latitude": 20.681667,
            "longitude": -103.462778,
            "location_precision": "ground",
            "daylight_minutes": 696,
            "sun_elevation_deg": 3.6,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": null,
            "referee_name": "Vicente Jassiel Reynoso Arce",
            "regular_time_home_goals": 1,
            "regular_time_away_goals": 0,
            "regular_time_result": "home",
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": {
                "home": {
                    "xg": 0.76,
                    "xg_estimate": 0.88,
                    "shots": 10,
                    "shots_on_target": 3,
                    "corners": 9,
                    "fouls": 14,
                    "yellow_cards": 0,
                    "red_cards": 0,
                    "possession_pct": 60
                },
                "away": {
                    "xg": 0.58,
                    "xg_estimate": 1.1,
                    "shots": 11,
                    "shots_on_target": 4,
                    "corners": 5,
                    "fouls": 17,
                    "yellow_cards": 1,
                    "red_cards": 0,
                    "possession_pct": 40
                }
            }
        },
        {
            "match_id": "mt_bgwy6yqv0",
            "competition": "liga-mx",
            "country_name": "Mexico",
            "competition_name": "Liga MX",
            "season_start_year": 2026,
            "kickoff_utc": "2026-10-21T01:00:00Z",
            "kickoff_date": "2026-10-21",
            "kickoff_local_date": "2026-10-21",
            "kickoff_local_time": "01:00",
            "match_status": "finished",
            "home_club_id": "cl_1zehkhe1x",
            "home_club_name": "Atletico San Luis",
            "away_club_id": "cl_bv4730etq",
            "away_club_name": "Club Queretaro",
            "home_goals": 2,
            "away_goals": 1,
            "full_time_result": "home",
            "half_time_home_goals": 0,
            "half_time_away_goals": 0,
            "half_time_result": "draw",
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": null,
            "home_league_position": 15,
            "away_league_position": 6,
            "away_travel_km": 182,
            "ground_name": "Estadio Libertad Financiera",
            "city_name": "San Luis de Potosi",
            "latitude": 22.138706,
            "longitude": -100.950864,
            "location_precision": "ground",
            "daylight_minutes": 694,
            "sun_elevation_deg": -11.1,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": null,
            "referee_name": "Adonai Escobedo Gonzalez",
            "regular_time_home_goals": 2,
            "regular_time_away_goals": 1,
            "regular_time_result": "home",
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": {
                "home": {
                    "xg": 1.45,
                    "xg_estimate": 0.98,
                    "shots": 12,
                    "shots_on_target": 4,
                    "corners": 5,
                    "fouls": 9,
                    "yellow_cards": 0,
                    "red_cards": 0,
                    "possession_pct": 55
                },
                "away": {
                    "xg": 1.07,
                    "xg_estimate": 0.87,
                    "shots": 9,
                    "shots_on_target": 4,
                    "corners": 2,
                    "fouls": 7,
                    "yellow_cards": 0,
                    "red_cards": 0,
                    "possession_pct": 45
                }
            }
        }
    ],
    "meta": {
        "count": 20,
        "request_id": "req_ff8af3f34d4da95f"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Rescheduled

`GET /v1/fixtures/rescheduled`  
Complimentary key: this season's Premier League.

Matches whose kickoff has moved, in the days you ask about, with the new kickoff.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |
| `days` | integer | no | How many days to look at. Default 7. From 1 to 30. |

```bash
curl "https://api.footballapi.org/v1/fixtures/rescheduled?days=30" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": [],
    "meta": {
        "count": 0,
        "request_id": "req_1dc1150726b3f408"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

### Live

#### Live

`GET /v1/live`  
Membership only.

Every match being played now, with the score and the minute. Answers refresh every 5 seconds.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |

| Field | Type | What it is |
|---|---|---|
| `match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `competition` | string | The competition's name in the collection, such as premier-league |
| `country_name` | string | The country, or World or Europe for a tournament |
| `competition_name` | string | The competition as people write it |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `kickoff_utc` | string | Kickoff in UTC, ISO 8601 |
| `kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `kickoff_local_date` | string | The day of kickoff where the match is played |
| `kickoff_local_time` | string | The time of kickoff where the match is played |
| `match_status` | string | Where the match stands, such as finished or not started |
| `home_club_id` | string | Our id for the home club |
| `home_club_name` | string | The home club |
| `away_club_id` | string | Our id for the away club |
| `away_club_name` | string | The away club |
| `home_goals` | integer | Home goals at full time |
| `away_goals` | integer | Away goals at full time |
| `full_time_result` | null or more | home, away or draw, at full time |
| `half_time_home_goals` | integer | Home goals at half time |
| `half_time_away_goals` | integer | Away goals at half time |
| `half_time_result` | null or more | home, away or draw, at half time |
| `stoppage_minutes` | null or more | Minutes of added time; null when not recorded |
| `is_kickoff_rescheduled` | boolean | Whether kickoff moved from its first date or time |
| `elapsed_minutes` | integer | Minutes played so far while the match is on; null otherwise |
| `home_league_position` | null or more | The home side's place in its league before kickoff |
| `away_league_position` | integer | The away side's place in its league before kickoff |
| `away_travel_km` | integer | How far the away side came, ground to ground, in kilometres |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `latitude` | number | Where the ground is, north to south |
| `longitude` | number | Where the ground is, east to west |
| `location_precision` | string | How exact latitude and longitude are: ground, or city |
| `daylight_minutes` | integer | Minutes of daylight that day at the ground |
| `sun_elevation_deg` | number | The sun's height at kickoff, in degrees; below 0 after dark |
| `public_holiday` | null or more | The public holiday that day where the match is played; null when none |
| `kickoff_temperature_c` | null or more | The temperature at kickoff, in degrees C; null when not recorded |
| `kickoff_rain_mm` | null or more | Rain in the hour of kickoff, in millimetres; null when not recorded |
| `kickoff_wind_ms` | null or more | Wind at kickoff, in metres a second; null when not recorded |
| `attendance` | null or more | The crowd; null when not recorded |
| `referee_name` | null or more | The referee |
| `regular_time_home_goals` | null or more | Home goals after 90 minutes and added time |
| `regular_time_away_goals` | null or more | Away goals after 90 minutes and added time |
| `regular_time_result` | null or more | home, away or draw, after 90 minutes and added time |
| `extra_time_home_goals` | null or more | Home goals after extra time; null when there was none |
| `extra_time_away_goals` | null or more | Away goals after extra time; null when there was none |
| `shootout_home_goals` | null or more | Home penalties scored in a shootout; null when there was none |
| `shootout_away_goals` | null or more | Away penalties scored in a shootout; null when there was none |
| `club_figures` | null or more | Each side's figures for the match |

```bash
curl "https://api.footballapi.org/v1/live" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": [
        {
            "match_id": "mt_4gfmswg7x",
            "competition": "veikkausliiga",
            "country_name": "Finland",
            "competition_name": "Veikkausliiga",
            "season_start_year": 2026,
            "kickoff_utc": "2026-10-21T15:30:00Z",
            "kickoff_date": "2026-10-21",
            "kickoff_local_date": "2026-10-21",
            "kickoff_local_time": "15:30",
            "match_status": "in_play_second_half",
            "home_club_id": "cl_9bkc78m1c",
            "home_club_name": "PK-35",
            "away_club_id": "cl_de2y39a71",
            "away_club_name": "FF Jaro",
            "home_goals": 1,
            "away_goals": 1,
            "full_time_result": null,
            "half_time_home_goals": 1,
            "half_time_away_goals": 1,
            "half_time_result": null,
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": 46,
            "home_league_position": null,
            "away_league_position": 11,
            "away_travel_km": 407,
            "ground_name": "Mustapekka Areena",
            "city_name": "Helsinki",
            "latitude": 60.170833333333,
            "longitude": 24.9375,
            "location_precision": "city",
            "daylight_minutes": 584,
            "sun_elevation_deg": -4.8,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": null,
            "referee_name": null,
            "regular_time_home_goals": null,
            "regular_time_away_goals": null,
            "regular_time_result": null,
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": null
        },
        {
            "match_id": "mt_echn2jdhh",
            "competition": "segunda-federacion",
            "country_name": "Spain",
            "competition_name": "Segunda División RFEF - Group 2",
            "season_start_year": 2026,
            "kickoff_utc": "2026-10-21T16:00:00Z",
            "kickoff_date": "2026-10-21",
            "kickoff_local_date": "2026-10-21",
            "kickoff_local_time": "16:00",
            "match_status": "half_time",
            "home_club_id": "cl_58s3ery1z",
            "home_club_name": "Terrassa",
            "away_club_id": "cl_e60y5srh1",
            "away_club_name": "Girona II",
            "home_goals": 0,
            "away_goals": 0,
            "full_time_result": null,
            "half_time_home_goals": 0,
            "half_time_away_goals": 0,
            "half_time_result": null,
            "stoppage_minutes": null,
            "is_kickoff_rescheduled": false,
            "elapsed_minutes": 45,
            "home_league_position": 7,
            "away_league_position": 8,
            "away_travel_km": 68,
            "ground_name": null,
            "city_name": null,
            "latitude": null,
            "longitude": null,
            "location_precision": null,
            "daylight_minutes": null,
            "sun_elevation_deg": null,
            "public_holiday": null,
            "kickoff_temperature_c": null,
            "kickoff_rain_mm": null,
            "kickoff_wind_ms": null,
            "attendance": null,
            "referee_name": null,
            "regular_time_home_goals": null,
            "regular_time_away_goals": null,
            "regular_time_result": null,
            "extra_time_home_goals": null,
            "extra_time_away_goals": null,
            "shootout_home_goals": null,
            "shootout_away_goals": null,
            "club_figures": null
        }
    ],
    "meta": {
        "count": 4,
        "refreshed_seconds": 5,
        "request_id": "req_e212f09ea00ca0bd"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Live match

`GET /v1/live/{match_id}`  
Membership only.

The score, the minute and the events so far of a match being played now. Answers refresh every 5 seconds.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `match_id` | string | yes | A match id from any result, fixture or match list, such as mt_e2hk79mn5. In the path. |

| Field | Type | What it is |
|---|---|---|
| `match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `competition` | string | The competition's name in the collection, such as premier-league |
| `country_name` | string | The country, or World or Europe for a tournament |
| `competition_name` | string | The competition as people write it |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `kickoff_utc` | string | Kickoff in UTC, ISO 8601 |
| `kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `kickoff_local_date` | string | The day of kickoff where the match is played |
| `kickoff_local_time` | string | The time of kickoff where the match is played |
| `match_status` | string | Where the match stands, such as finished or not started |
| `home_club_id` | string | Our id for the home club |
| `home_club_name` | string | The home club |
| `away_club_id` | string | Our id for the away club |
| `away_club_name` | string | The away club |
| `home_goals` | integer | Home goals at full time |
| `away_goals` | integer | Away goals at full time |
| `full_time_result` | null or more | home, away or draw, at full time |
| `half_time_home_goals` | integer | Home goals at half time |
| `half_time_away_goals` | integer | Away goals at half time |
| `half_time_result` | null or more | home, away or draw, at half time |
| `stoppage_minutes` | null or more | Minutes of added time; null when not recorded |
| `is_kickoff_rescheduled` | boolean | Whether kickoff moved from its first date or time |
| `elapsed_minutes` | integer | Minutes played so far while the match is on; null otherwise |
| `home_league_position` | null or more | The home side's place in its league before kickoff |
| `away_league_position` | integer | The away side's place in its league before kickoff |
| `away_travel_km` | integer | How far the away side came, ground to ground, in kilometres |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `latitude` | number | Where the ground is, north to south |
| `longitude` | number | Where the ground is, east to west |
| `location_precision` | string | How exact latitude and longitude are: ground, or city |
| `daylight_minutes` | integer | Minutes of daylight that day at the ground |
| `sun_elevation_deg` | number | The sun's height at kickoff, in degrees; below 0 after dark |
| `public_holiday` | null or more | The public holiday that day where the match is played; null when none |
| `kickoff_temperature_c` | null or more | The temperature at kickoff, in degrees C; null when not recorded |
| `kickoff_rain_mm` | null or more | Rain in the hour of kickoff, in millimetres; null when not recorded |
| `kickoff_wind_ms` | null or more | Wind at kickoff, in metres a second; null when not recorded |
| `attendance` | null or more | The crowd; null when not recorded |
| `referee_name` | null or more | The referee |
| `regular_time_home_goals` | null or more | Home goals after 90 minutes and added time |
| `regular_time_away_goals` | null or more | Away goals after 90 minutes and added time |
| `regular_time_result` | null or more | home, away or draw, after 90 minutes and added time |
| `extra_time_home_goals` | null or more | Home goals after extra time; null when there was none |
| `extra_time_away_goals` | null or more | Away goals after extra time; null when there was none |
| `shootout_home_goals` | null or more | Home penalties scored in a shootout; null when there was none |
| `shootout_away_goals` | null or more | Away penalties scored in a shootout; null when there was none |
| `club_figures` | null or more | Each side's figures for the match |

```bash
curl "https://api.footballapi.org/v1/live/mt_4gfmswg7x" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": {
        "match_id": "mt_4gfmswg7x",
        "competition": "veikkausliiga",
        "country_name": "Finland",
        "competition_name": "Veikkausliiga",
        "season_start_year": 2026,
        "kickoff_utc": "2026-10-21T15:30:00Z",
        "kickoff_date": "2026-10-21",
        "kickoff_local_date": "2026-10-21",
        "kickoff_local_time": "15:30",
        "match_status": "in_play_second_half",
        "home_club_id": "cl_9bkc78m1c",
        "home_club_name": "PK-35",
        "away_club_id": "cl_de2y39a71",
        "away_club_name": "FF Jaro",
        "home_goals": 1,
        "away_goals": 1,
        "full_time_result": null,
        "half_time_home_goals": 1,
        "half_time_away_goals": 1,
        "half_time_result": null,
        "stoppage_minutes": null,
        "is_kickoff_rescheduled": false,
        "elapsed_minutes": 46,
        "home_league_position": null,
        "away_league_position": 11,
        "away_travel_km": 407,
        "ground_name": "Mustapekka Areena",
        "city_name": "Helsinki",
        "latitude": 60.170833333333,
        "longitude": 24.9375,
        "location_precision": "city",
        "daylight_minutes": 584,
        "sun_elevation_deg": -4.8,
        "public_holiday": null,
        "kickoff_temperature_c": null,
        "kickoff_rain_mm": null,
        "kickoff_wind_ms": null,
        "attendance": null,
        "referee_name": null,
        "regular_time_home_goals": null,
        "regular_time_away_goals": null,
        "regular_time_result": null,
        "extra_time_home_goals": null,
        "extra_time_away_goals": null,
        "shootout_home_goals": null,
        "shootout_away_goals": null,
        "club_figures": null
    },
    "meta": {
        "refreshed_seconds": 5,
        "request_id": "req_f8f3c7dff5841146"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

### Clubs

#### Clubs

`GET /v1/clubs`  
Complimentary key: this season's Premier League.

Every club in the collection with its ground and city, by competition and season, or by country, paged.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |
| `season` | integer | no | With a competition: the clubs of that season, by its first year. From 2015, or the competition's first season. |
| `country` | string | no | Only this country's clubs, such as England. |
| `page` | integer | no | Which page, from 1. From 1 to 100,000. |
| `per_page` | integer | no | Rows on a page. Default 100. From 1 to 1,000. |

| Field | Type | What it is |
|---|---|---|
| `club_id` | string | Our id for the club, cl_ and 9 characters, the same in every answer and for good |
| `club_name` | string | The club |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `matches` | integer | Matches counted |

```bash
curl "https://api.footballapi.org/v1/clubs?competition=premier-league" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": [
        {
            "club_id": "cl_3rhba3739",
            "club_name": "Everton",
            "ground_name": "Hill Dickinson Stadium",
            "city_name": "Liverpool",
            "matches": 1503
        },
        {
            "club_id": "cl_3pekhsfp3",
            "club_name": "Manchester United",
            "ground_name": "Old Trafford",
            "city_name": "Manchester",
            "matches": 1413
        }
    ],
    "meta": {
        "count": 56,
        "competition": "premier-league",
        "request_id": "req_eda612c4cb344c79"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Club

`GET /v1/clubs/{club_id}`  
Complimentary key: this season's Premier League.

A club: its ground, its city, where the ground is and how many of its matches the collection holds.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `club_id` | string | yes | A club id from any match, table or club list, such as cl_a7vhnxhhh. In the path. |

| Field | Type | What it is |
|---|---|---|
| `club_id` | string | Our id for the club, cl_ and 9 characters, the same in every answer and for good |
| `club_name` | string | The club |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `latitude` | number | Where the ground is, north to south |
| `longitude` | number | Where the ground is, east to west |
| `match_count` | integer | Matches the collection holds |

```bash
curl "https://api.footballapi.org/v1/clubs/cl_4x2bczxvv" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": {
        "club_id": "cl_4x2bczxvv",
        "club_name": "Tottenham",
        "ground_name": "Tottenham Hotspur Stadium",
        "city_name": "London",
        "latitude": 51.604444444444,
        "longitude": -0.066388888888889,
        "match_count": 1629
    },
    "meta": {
        "request_id": "req_af1e544332b7cd6d"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Club matches

`GET /v1/clubs/{club_id}/matches`  
Complimentary key: this season's Premier League.

Every match of a club, played and still to come, by season and home or away, paged.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `club_id` | string | yes | A club id from any match, table or club list, such as cl_a7vhnxhhh. In the path. |
| `season` | integer | no | The first year of the season: 2026 for 2026/27. From 2015, or the competition's first season. |
| `venue` | string | no | Home matches only, or away matches only. home or away. |
| `page` | integer | no | Which page, from 1. From 1 to 100,000. |
| `per_page` | integer | no | Rows on a page. Default 100. From 1 to 1,000. |
| `cursor` | string | no | meta.next_cursor from the page before, passed back unchanged. Faster than page for long walks. |

| Field | Type | What it is |
|---|---|---|
| `match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `kickoff_utc` | string | Kickoff in UTC, ISO 8601 |
| `kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `competition` | string | The competition's name in the collection, such as premier-league |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `match_status` | string | Where the match stands, such as finished or not started |
| `full_time_result` | null or more | home, away or draw, at full time |
| `half_time_result` | null or more | home, away or draw, at half time |
| `country_name` | string | The country, or World or Europe for a tournament |
| `competition_name` | string | The competition as people write it |
| `venue` | string | home or away when the table counts only those; null for both |
| `opponent_id` | string | Our id for the other club |
| `opponent_name` | string | The other club |
| `goals_for` | null or more | Goals scored |
| `goals_against` | null or more | Goals let in |
| `regular_goals_for` | null or more | Goals scored by the club in 90 minutes and added time |
| `regular_goals_against` | null or more | Goals let in by the club in 90 minutes and added time |
| `position` | integer | Place in the table |
| `travel_km` | integer | How far the club came for this match, in kilometres; 0 at home |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `outcome` | null or more | won, drawn or lost, for the club the answer is about |

```bash
curl "https://api.footballapi.org/v1/clubs/cl_4x2bczxvv/matches?per_page=2" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": [
        {
            "match_id": "mt_bz20hr56m",
            "kickoff_utc": "2027-05-30T15:00:00Z",
            "kickoff_date": "2027-05-30",
            "competition": "premier-league",
            "season_start_year": 2026,
            "match_status": "scheduled",
            "full_time_result": null,
            "half_time_result": null,
            "country_name": "England",
            "competition_name": "Premier League",
            "venue": "away",
            "opponent_id": "cl_7me91q2ds",
            "opponent_name": "Aston Villa",
            "goals_for": null,
            "goals_against": null,
            "regular_goals_for": null,
            "regular_goals_against": null,
            "position": 16,
            "travel_km": 160,
            "ground_name": "Villa Park",
            "city_name": "Birmingham",
            "outcome": null
        },
        {
            "match_id": "mt_7e6n522jz",
            "kickoff_utc": "2027-05-23T14:00:00Z",
            "kickoff_date": "2027-05-23",
            "competition": "premier-league",
            "season_start_year": 2026,
            "match_status": "scheduled",
            "full_time_result": null,
            "half_time_result": null,
            "country_name": "England",
            "competition_name": "Premier League",
            "venue": "home",
            "opponent_id": "cl_3pekhsfp3",
            "opponent_name": "Manchester United",
            "goals_for": null,
            "goals_against": null,
            "regular_goals_for": null,
            "regular_goals_against": null,
            "position": 16,
            "travel_km": null,
            "ground_name": "Tottenham Hotspur Stadium",
            "city_name": "London",
            "outcome": null
        }
    ],
    "meta": {
        "count": 2,
        "page": 1,
        "per_page": 2,
        "total": 1629,
        "total_pages": 815,
        "next_page": 2,
        "prev_page": null,
        "next_cursor": null,
        "request_id": "req_6bb9d249889b7e02"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Form

`GET /v1/clubs/{club_id}/form`  
Complimentary key: this season's Premier League.

The last results of a club, newest first, with a summary of goals, clean sheets and points.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `club_id` | string | yes | A club id from any match, table or club list, such as cl_a7vhnxhhh. In the path. |
| `last` | integer | no | How many matches, newest first. Default 5. From 1 to 50. |

| Field | Type | What it is |
|---|---|---|
| `club_id` | string | Our id for the club, cl_ and 9 characters, the same in every answer and for good |
| `club_name` | string | The club |
| `last` | integer | How many matches the form covers |
| `form` | string | The results, newest first: W, D or L for each match |
| `summary` | object | The matches counted, in figures |
| `summary.played` | integer | Matches counted |
| `summary.won` | integer | Matches won |
| `summary.drawn` | integer | Matches drawn |
| `summary.lost` | integer | Matches lost |
| `summary.goals_for` | integer | Goals scored |
| `summary.goals_against` | integer | Goals let in |
| `summary.clean_sheets` | integer | Matches without letting one in |
| `summary.failed_to_score` | integer | Matches without scoring |
| `summary.goal_difference` | integer | Goals scored less goals let in |
| `summary.points` | integer | Three for a win, one for a draw |
| `summary.win_pct` | integer | Share of the matches won, as a percentage |
| `summary.goals_per_game` | number | Goals scored a match, on average |
| `summary.conceded_per_game` | number | Goals let in a match, on average |
| `home` | object | The home side |
| `home.played` | integer | Matches counted |
| `home.won` | integer | Matches won |
| `home.drawn` | integer | Matches drawn |
| `home.lost` | integer | Matches lost |
| `home.goals_for` | integer | Goals scored |
| `home.goals_against` | integer | Goals let in |
| `home.clean_sheets` | integer | Matches without letting one in |
| `home.failed_to_score` | integer | Matches without scoring |
| `home.goal_difference` | integer | Goals scored less goals let in |
| `home.points` | integer | Three for a win, one for a draw |
| `home.win_pct` | number | Share of the matches won, as a percentage |
| `home.goals_per_game` | number | Goals scored a match, on average |
| `home.conceded_per_game` | number | Goals let in a match, on average |
| `away` | object | The away side |
| `away.played` | integer | Matches counted |
| `away.won` | integer | Matches won |
| `away.drawn` | integer | Matches drawn |
| `away.lost` | integer | Matches lost |
| `away.goals_for` | integer | Goals scored |
| `away.goals_against` | integer | Goals let in |
| `away.clean_sheets` | integer | Matches without letting one in |
| `away.failed_to_score` | integer | Matches without scoring |
| `away.goal_difference` | integer | Goals scored less goals let in |
| `away.points` | integer | Three for a win, one for a draw |
| `away.win_pct` | integer | Share of the matches won, as a percentage |
| `away.goals_per_game` | integer | Goals scored a match, on average |
| `away.conceded_per_game` | integer | Goals let in a match, on average |
| `matches` | list | Matches counted |
| `matches[].match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `matches[].kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `matches[].competition_name` | string | The competition as people write it |
| `matches[].venue` | string | home or away when the table counts only those; null for both |
| `matches[].opponent_id` | string | Our id for the other club |
| `matches[].opponent_name` | string | The other club |
| `matches[].goals_for` | integer | Goals scored |
| `matches[].goals_against` | integer | Goals let in |
| `matches[].outcome` | string | won, drawn or lost, for the club the answer is about |

```bash
curl "https://api.footballapi.org/v1/clubs/cl_4x2bczxvv/form?last=5" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": {
        "club_id": "cl_4x2bczxvv",
        "club_name": "Tottenham",
        "last": 5,
        "form": "WDLLD",
        "summary": {
            "played": 5,
            "won": 1,
            "drawn": 2,
            "lost": 2,
            "goals_for": 7,
            "goals_against": 8,
            "clean_sheets": 1,
            "failed_to_score": 1,
            "goal_difference": -1,
            "points": 5,
            "win_pct": 20,
            "goals_per_game": 1.4,
            "conceded_per_game": 1.6
        },
        "home": {
            "played": 3,
            "won": 1,
            "drawn": 1,
            "lost": 1,
            "goals_for": 5,
            "goals_against": 4,
            "clean_sheets": 1,
            "failed_to_score": 1,
            "goal_difference": 1,
            "points": 4,
            "win_pct": 33.3,
            "goals_per_game": 1.67,
            "conceded_per_game": 1.33
        },
        "away": {
            "played": 2,
            "won": 0,
            "drawn": 1,
            "lost": 1,
            "goals_for": 2,
            "goals_against": 4,
            "clean_sheets": 0,
            "failed_to_score": 0,
            "goal_difference": -2,
            "points": 1,
            "win_pct": 0,
            "goals_per_game": 1,
            "conceded_per_game": 2
        },
        "matches": [
            {
                "match_id": "mt_95kf4jw9a",
                "kickoff_date": "2026-10-19",
                "competition_name": "Premier League",
                "venue": "home",
                "opponent_id": "cl_frt0n2e46",
                "opponent_name": "Coventry",
                "goals_for": 3,
                "goals_against": 1,
                "outcome": "won"
            },
            {
                "match_id": "mt_9g56fvmwj",
                "kickoff_date": "2026-10-10",
                "competition_name": "Premier League",
                "venue": "away",
                "opponent_id": "cl_3pekhsfp3",
                "opponent_name": "Manchester United",
                "goals_for": 1,
                "goals_against": 1,
                "outcome": "drawn"
            },
            {
                "match_id": "mt_74kh014pt",
                "kickoff_date": "2026-09-19",
                "competition_name": "Premier League",
                "venue": "home",
                "opponent_id": "cl_7me91q2ds",
                "opponent_name": "Aston Villa",
                "goals_for": 2,
                "goals_against": 3,
                "outcome": "lost"
            }
        ]
    },
    "meta": {
        "request_id": "req_9b43d0b398031906"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Club stats

`GET /v1/clubs/{club_id}/stats`  
Complimentary key: this season's Premier League.

A club in figures for a season: goals, clean sheets, half-time record and results, home and away.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `club_id` | string | yes | A club id from any match, table or club list, such as cl_a7vhnxhhh. In the path. |
| `season` | integer | no | The first year of the season: 2026 for 2026/27. From 2015, or the competition's first season. |
| `venue` | string | no | Home matches only, or away matches only. home or away. |

| Field | Type | What it is |
|---|---|---|
| `club_id` | string | Our id for the club, cl_ and 9 characters, the same in every answer and for good |
| `club_name` | string | The club |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `venue` | null or more | home or away when the table counts only those; null for both |
| `overall` | object | Every match, home and away together |
| `overall.played` | integer | Matches counted |
| `overall.won` | integer | Matches won |
| `overall.drawn` | integer | Matches drawn |
| `overall.lost` | integer | Matches lost |
| `overall.goals_for` | integer | Goals scored |
| `overall.goals_against` | integer | Goals let in |
| `overall.clean_sheets` | integer | Matches without letting one in |
| `overall.failed_to_score` | integer | Matches without scoring |
| `overall.goal_difference` | integer | Goals scored less goals let in |
| `overall.points` | integer | Three for a win, one for a draw |
| `overall.win_pct` | integer | Share of the matches won, as a percentage |
| `overall.goals_per_game` | number | Goals scored a match, on average |
| `overall.conceded_per_game` | number | Goals let in a match, on average |
| `home` | object | The home side |
| `home.played` | integer | Matches counted |
| `home.won` | integer | Matches won |
| `home.drawn` | integer | Matches drawn |
| `home.lost` | integer | Matches lost |
| `home.goals_for` | integer | Goals scored |
| `home.goals_against` | integer | Goals let in |
| `home.clean_sheets` | integer | Matches without letting one in |
| `home.failed_to_score` | integer | Matches without scoring |
| `home.goal_difference` | integer | Goals scored less goals let in |
| `home.points` | integer | Three for a win, one for a draw |
| `home.win_pct` | number | Share of the matches won, as a percentage |
| `home.goals_per_game` | number | Goals scored a match, on average |
| `home.conceded_per_game` | number | Goals let in a match, on average |
| `away` | object | The away side |
| `away.played` | integer | Matches counted |
| `away.won` | integer | Matches won |
| `away.drawn` | integer | Matches drawn |
| `away.lost` | integer | Matches lost |
| `away.goals_for` | integer | Goals scored |
| `away.goals_against` | integer | Goals let in |
| `away.clean_sheets` | integer | Matches without letting one in |
| `away.failed_to_score` | integer | Matches without scoring |
| `away.goal_difference` | integer | Goals scored less goals let in |
| `away.points` | integer | Three for a win, one for a draw |
| `away.win_pct` | number | Share of the matches won, as a percentage |
| `away.goals_per_game` | integer | Goals scored a match, on average |
| `away.conceded_per_game` | number | Goals let in a match, on average |
| `half_time` | object | The score at half time |
| `half_time.recorded` | integer | Matches with a half-time score |
| `half_time.led` | integer | Matches the club led at half time |
| `half_time.led_and_won` | integer | Of those, matches it went on to win |
| `half_time.conversion_pct` | number | Share of half-time leads turned into wins, as a percentage |

```bash
curl "https://api.footballapi.org/v1/clubs/cl_4x2bczxvv/stats?season=2026" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": {
        "club_id": "cl_4x2bczxvv",
        "club_name": "Tottenham",
        "season_start_year": 2026,
        "venue": null,
        "overall": {
            "played": 15,
            "won": 6,
            "drawn": 5,
            "lost": 4,
            "goals_for": 23,
            "goals_against": 18,
            "clean_sheets": 5,
            "failed_to_score": 4,
            "goal_difference": 5,
            "points": 23,
            "win_pct": 40,
            "goals_per_game": 1.53,
            "conceded_per_game": 1.2
        },
        "home": {
            "played": 9,
            "won": 4,
            "drawn": 3,
            "lost": 2,
            "goals_for": 17,
            "goals_against": 10,
            "clean_sheets": 3,
            "failed_to_score": 2,
            "goal_difference": 7,
            "points": 15,
            "win_pct": 44.4,
            "goals_per_game": 1.89,
            "conceded_per_game": 1.11
        },
        "away": {
            "played": 6,
            "won": 2,
            "drawn": 2,
            "lost": 2,
            "goals_for": 6,
            "goals_against": 8,
            "clean_sheets": 2,
            "failed_to_score": 2,
            "goal_difference": -2,
            "points": 8,
            "win_pct": 33.3,
            "goals_per_game": 1,
            "conceded_per_game": 1.33
        },
        "half_time": {
            "recorded": 15,
            "led": 6,
            "led_and_won": 5,
            "conversion_pct": 83.3
        }
    },
    "meta": {
        "season": "2026/27",
        "request_id": "req_11d675c7cdac55f6"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Streaks

`GET /v1/clubs/{club_id}/streaks`  
Complimentary key: this season's Premier League.

A club's current and longest runs: wins, unbeaten, clean sheets, scoring and failing to score.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `club_id` | string | yes | A club id from any match, table or club list, such as cl_a7vhnxhhh. In the path. |
| `season` | integer | no | The first year of the season: 2026 for 2026/27. From 2015, or the competition's first season. |

| Field | Type | What it is |
|---|---|---|
| `club_id` | string | Our id for the club, cl_ and 9 characters, the same in every answer and for good |
| `club_name` | string | The club |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `matches_considered` | integer | Matches counted |
| `current` | object | The runs going on now |
| `current.won` | integer | Matches won |
| `current.unbeaten` | integer | Matches without losing |
| `current.lost` | integer | Matches lost |
| `current.without_win` | integer | Matches without winning |
| `current.clean_sheet` | integer | Matches without letting one in |
| `current.scored` | integer | Matches with a goal |
| `current.failed_to_score` | integer | Matches without scoring |
| `longest` | object | The longest runs in the matches counted |
| `longest.won` | integer | Matches won |
| `longest.unbeaten` | integer | Matches without losing |
| `longest.lost` | integer | Matches lost |
| `longest.without_win` | integer | Matches without winning |
| `longest.clean_sheet` | integer | Matches without letting one in |
| `longest.scored` | integer | Matches with a goal |
| `longest.failed_to_score` | integer | Matches without scoring |
| `as_at` | object | The match the runs are counted to |
| `as_at.match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `as_at.kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |

```bash
curl "https://api.footballapi.org/v1/clubs/cl_4x2bczxvv/streaks?season=2026" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": {
        "club_id": "cl_4x2bczxvv",
        "club_name": "Tottenham",
        "season_start_year": 2026,
        "matches_considered": 15,
        "current": {
            "won": 1,
            "unbeaten": 2,
            "lost": 0,
            "without_win": 0,
            "clean_sheet": 0,
            "scored": 4,
            "failed_to_score": 0
        },
        "longest": {
            "won": 3,
            "unbeaten": 6,
            "lost": 2,
            "without_win": 6,
            "clean_sheet": 2,
            "scored": 6,
            "failed_to_score": 3
        },
        "as_at": {
            "match_id": "mt_95kf4jw9a",
            "kickoff_date": "2026-10-19"
        }
    },
    "meta": {
        "season": "2026/27",
        "request_id": "req_0abc417450e4bf4c"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Travel

`GET /v1/clubs/{club_id}/travel`  
Complimentary key: this season's Premier League.

How far a club travels to away matches in a season, and its record at each distance.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `club_id` | string | yes | A club id from any match, table or club list, such as cl_a7vhnxhhh. In the path. |
| `season` | integer | no | The first year of the season: 2026 for 2026/27. From 2015, or the competition's first season. |

| Field | Type | What it is |
|---|---|---|
| `club_id` | string | Our id for the club, cl_ and 9 characters, the same in every answer and for good |
| `club_name` | string | The club |
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `away_matches` | integer | Away matches counted |
| `total_km` | integer | Kilometres travelled to away matches in all |
| `average_km` | integer | Kilometres to an away match, on average |
| `furthest_km` | integer | The furthest away trip, in kilometres |
| `by_distance` | list | The record at each distance |
| `by_distance[].band` | string | The distance, in words |
| `by_distance[].min_km` | integer | The shortest trip in the band, in kilometres |
| `by_distance[].played` | integer | Matches counted |
| `by_distance[].won` | integer | Matches won |
| `by_distance[].drawn` | integer | Matches drawn |
| `by_distance[].lost` | integer | Matches lost |
| `by_distance[].win_pct` | integer | Share of the matches won, as a percentage |
| `by_distance[].goals_for` | integer | Goals scored |
| `by_distance[].goals_against` | integer | Goals let in |

```bash
curl "https://api.footballapi.org/v1/clubs/cl_4x2bczxvv/travel?season=2026" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": {
        "club_id": "cl_4x2bczxvv",
        "club_name": "Tottenham",
        "season_start_year": 2026,
        "away_matches": 6,
        "total_km": 19072,
        "average_km": 3179,
        "furthest_km": 18333,
        "by_distance": [
            {
                "band": "under 100 km",
                "min_km": 0,
                "played": 2,
                "won": 1,
                "drawn": 0,
                "lost": 1,
                "win_pct": 50,
                "goals_for": 2,
                "goals_against": 4
            },
            {
                "band": "100–300 km",
                "min_km": 100,
                "played": 3,
                "won": 0,
                "drawn": 2,
                "lost": 1,
                "win_pct": 0,
                "goals_for": 2,
                "goals_against": 4
            },
            {
                "band": "300–600 km",
                "min_km": 300,
                "played": 0,
                "won": 0,
                "drawn": 0,
                "lost": 0,
                "win_pct": null,
                "goals_for": 0,
                "goals_against": 0
            }
        ]
    },
    "meta": {
        "season": "2026/27",
        "request_id": "req_45f3206327038e3c"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Head to head

`GET /v1/clubs/{club_id}/head-to-head/{opponent_id}`  
Complimentary key: this season's Premier League.

Every meeting between two clubs since 2015/16, newest first, with the record of each side.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `club_id` | string | yes | A club id from any match, table or club list, such as cl_a7vhnxhhh. In the path. |
| `opponent_id` | string | yes | The other club's id. In the path. |
| `limit` | integer | no | How many meetings to list, newest first. Default 20. From 1 to 100. |

| Field | Type | What it is |
|---|---|---|
| `club` | object | The club the answer is about |
| `club.club_id` | string | Our id for the club, cl_ and 9 characters, the same in every answer and for good |
| `club.club_name` | string | The club |
| `opponent` | object | The other club |
| `opponent.club_id` | string | Our id for the club, cl_ and 9 characters, the same in every answer and for good |
| `opponent.club_name` | string | The club |
| `record` | object | How the meetings ended, from the first club's side |
| `record.played` | integer | Matches counted |
| `record.won` | integer | Matches won |
| `record.drawn` | integer | Matches drawn |
| `record.lost` | integer | Matches lost |
| `record.goals_for` | integer | Goals scored |
| `record.goals_against` | integer | Goals let in |
| `record.clean_sheets` | integer | Matches without letting one in |
| `record.failed_to_score` | integer | Matches without scoring |
| `record.goal_difference` | integer | Goals scored less goals let in |
| `record.points` | integer | Three for a win, one for a draw |
| `record.win_pct` | integer | Share of the matches won, as a percentage |
| `record.goals_per_game` | number | Goals scored a match, on average |
| `record.conceded_per_game` | number | Goals let in a match, on average |
| `matches` | list | Matches counted |
| `matches[].match_id` | string | Our id for the match, mt_ and 9 characters, the same in every answer and for good |
| `matches[].kickoff_date` | string | The day of kickoff in UTC, YYYY-MM-DD |
| `matches[].competition_name` | string | The competition as people write it |
| `matches[].venue` | string | home or away when the table counts only those; null for both |
| `matches[].goals_for` | integer | Goals scored |
| `matches[].goals_against` | integer | Goals let in |
| `matches[].outcome` | string | won, drawn or lost, for the club the answer is about |

```bash
curl "https://api.footballapi.org/v1/clubs/cl_4x2bczxvv/head-to-head/cl_frt0n2e46" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": {
        "club": {
            "club_id": "cl_4x2bczxvv",
            "club_name": "Tottenham"
        },
        "opponent": {
            "club_id": "cl_frt0n2e46",
            "club_name": "Coventry"
        },
        "record": {
            "played": 20,
            "won": 12,
            "drawn": 3,
            "lost": 5,
            "goals_for": 36,
            "goals_against": 24,
            "clean_sheets": 6,
            "failed_to_score": 3,
            "goal_difference": 12,
            "points": 39,
            "win_pct": 60,
            "goals_per_game": 1.8,
            "conceded_per_game": 1.2
        },
        "matches": [
            {
                "match_id": "mt_95kf4jw9a",
                "kickoff_date": "2026-10-19",
                "competition_name": "Premier League",
                "venue": "home",
                "goals_for": 3,
                "goals_against": 1,
                "outcome": "won"
            },
            {
                "match_id": "mt_fesgtwmrd",
                "kickoff_date": "2024-09-18",
                "competition_name": "League Cup",
                "venue": "away",
                "goals_for": 2,
                "goals_against": 1,
                "outcome": "won"
            },
            {
                "match_id": "mt_73qs7zd2d",
                "kickoff_date": "2013-01-05",
                "competition_name": "FA Cup",
                "venue": "home",
                "goals_for": 3,
                "goals_against": 0,
                "outcome": "won"
            }
        ]
    },
    "meta": {
        "count": 20,
        "request_id": "req_2448c5285e24cf6f"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

### Grounds

#### Grounds

`GET /v1/grounds`  
Every key.

Every ground in the collection with its city, capacity and surface, by country, surface or size, paged.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `country` | string | no | Only this country's grounds, such as England. |
| `surface` | string | no | The pitch. grass or artificial_turf. |
| `min_capacity` | integer | no | Grounds holding at least this many. From 0 to 200,000. |
| `page` | integer | no | Which page, from 1. From 1 to 100,000. |
| `per_page` | integer | no | Rows on a page. Default 100. From 1 to 1,000. |

| Field | Type | What it is |
|---|---|---|
| `ground_id` | string | Our id for the ground, gd_ and 9 characters |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `country_name` | string | The country, or World or Europe for a tournament |
| `capacity` | integer | How many the ground holds |
| `surface` | string | The pitch, such as grass |
| `match_count` | integer | Matches the collection holds |

```bash
curl "https://api.footballapi.org/v1/grounds?per_page=2" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": [
        {
            "ground_id": "gd_bdv848ber",
            "ground_name": "MFA Centenary Stadium",
            "city_name": "Ta&apos;Qali",
            "country_name": "Malta",
            "capacity": 2000,
            "surface": "artificial_turf",
            "match_count": 1034
        },
        {
            "ground_id": "gd_bbba0v2dp",
            "ground_name": "Estadio Nacional de Fútbol",
            "city_name": "Managua",
            "country_name": "Nicaragua",
            "capacity": 20000,
            "surface": "artificial_turf",
            "match_count": 777
        }
    ],
    "meta": {
        "count": 2,
        "total": 11849,
        "next_cursor": null,
        "request_id": "req_ffb51683d404f799"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Ground

`GET /v1/grounds/{ground_id}`  
Every key.

A ground: its city, its country, how many it holds, its surface and how many matches the collection holds there.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `ground_id` | string | yes | A ground id from the ground list. In the path. |

| Field | Type | What it is |
|---|---|---|
| `ground_id` | string | Our id for the ground, gd_ and 9 characters |
| `ground_name` | string | The ground |
| `city_name` | string | The city of the ground |
| `country_name` | string | The country, or World or Europe for a tournament |
| `capacity` | integer | How many the ground holds |
| `surface` | string | The pitch, such as grass |
| `match_count` | integer | Matches the collection holds |

```bash
curl "https://api.footballapi.org/v1/grounds/gd_bdv848ber" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": {
        "ground_id": "gd_bdv848ber",
        "ground_name": "MFA Centenary Stadium",
        "city_name": "Ta&apos;Qali",
        "country_name": "Malta",
        "capacity": 2000,
        "surface": "artificial_turf",
        "match_count": 1034
    },
    "meta": {
        "request_id": "req_7b97a5e270a00608"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

### Stats

#### Goals

`GET /v1/stats/goals`  
Complimentary key: this season's Premier League.

Goals a game, how often matches go over or under each line, and how often both sides score, by competition and season.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |
| `country` | string | no | Only this country, such as England. |
| `season` | integer | no | The first year of the season: 2026 for 2026/27. From 2015, or the competition's first season. |
| `group_by` | string | no | How the figures are split: by competition, season, country, or competition and season. competition or season or country or competition_season. |

| Field | Type | What it is |
|---|---|---|
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `matches` | integer | Matches counted |
| `goals_per_game` | number | Goals scored a match, on average |
| `home_goals_per_game` | number | Home goals a match, on average |
| `away_goals_per_game` | number | Away goals a match, on average |
| `over_1_5_pct` | number | Share of matches with two goals or more, as a percentage |
| `over_2_5_pct` | number | Share of matches with three goals or more, as a percentage |
| `over_3_5_pct` | number | Share of matches with four goals or more, as a percentage |
| `both_scored_pct` | number | Share of matches where both sides scored, as a percentage |
| `goalless_pct` | number | Share of matches with no goals, as a percentage |

```bash
curl "https://api.footballapi.org/v1/stats/goals?competition=premier-league&group_by=season" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": [
        {
            "season_start_year": 2023,
            "matches": 380,
            "goals_per_game": 3.279,
            "home_goals_per_game": 1.8,
            "away_goals_per_game": 1.479,
            "over_1_5_pct": 86.05,
            "over_2_5_pct": 64.74,
            "over_3_5_pct": 43.68,
            "both_scored_pct": 61.58,
            "goalless_pct": 2.89
        },
        {
            "season_start_year": 2024,
            "matches": 380,
            "goals_per_game": 2.934,
            "home_goals_per_game": 1.513,
            "away_goals_per_game": 1.421,
            "over_1_5_pct": 81.32,
            "over_2_5_pct": 56.58,
            "over_3_5_pct": 34.21,
            "both_scored_pct": 57.37,
            "goalless_pct": 4.21
        }
    ],
    "meta": {
        "count": 12,
        "group_by": "season",
        "request_id": "req_4dd04703c55ff5ce"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Scorelines

`GET /v1/stats/scorelines`  
Complimentary key: this season's Premier League.

How often each exact scoreline happens, by competition and season.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |
| `season` | integer | no | The first year of the season: 2026 for 2026/27. From 2015, or the competition's first season. |
| `group_by` | string | no | How the figures are split: by competition, season, country, or competition and season. competition or season or country or competition_season. |

| Field | Type | What it is |
|---|---|---|
| `scoreline` | string | The scoreline, home first |
| `matches` | integer | Matches counted |
| `share_pct` | number | Share of matches with it, as a percentage |
| `result` | string | How it ended, from the home side: home, draw or away |

```bash
curl "https://api.footballapi.org/v1/stats/scorelines?competition=premier-league&group_by=season" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": [
        {
            "scoreline": "1-1",
            "matches": 1619,
            "share_pct": 11.207,
            "result": "draw"
        },
        {
            "scoreline": "1-0",
            "matches": 1440,
            "share_pct": 9.968,
            "result": "home"
        }
    ],
    "meta": {
        "count": 37,
        "group_by": "season",
        "request_id": "req_9b6b4f123b583708"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Home advantage

`GET /v1/stats/home-advantage`  
Complimentary key: this season's Premier League.

How often the home side wins, draws and loses, by competition and season.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |
| `country` | string | no | Only this country, such as England. |
| `season` | integer | no | The first year of the season: 2026 for 2026/27. From 2015, or the competition's first season. |
| `group_by` | string | no | How the figures are split: by competition, season, country, or competition and season. competition or season or country or competition_season. |

| Field | Type | What it is |
|---|---|---|
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `matches` | integer | Matches counted |
| `home_win_pct` | number | Share of matches the home side won, as a percentage |
| `draw_pct` | number | Share of matches drawn, as a percentage |
| `away_win_pct` | number | Share of matches the away side won, as a percentage |
| `goal_advantage` | number | Home goals less away goals, a match, on average |
| `home_points_per_game` | number | Points a match for the home side, on average |
| `away_points_per_game` | number | Points a match for the away side, on average |

```bash
curl "https://api.footballapi.org/v1/stats/home-advantage?competition=premier-league&group_by=season" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": [
        {
            "season_start_year": 2016,
            "matches": 380,
            "home_win_pct": 49.21,
            "draw_pct": 22.11,
            "away_win_pct": 28.68,
            "goal_advantage": 0.395,
            "home_points_per_game": 1.697,
            "away_points_per_game": 1.082
        },
        {
            "season_start_year": 2022,
            "matches": 380,
            "home_win_pct": 48.42,
            "draw_pct": 22.89,
            "away_win_pct": 28.68,
            "goal_advantage": 0.416,
            "home_points_per_game": 1.682,
            "away_points_per_game": 1.089
        }
    ],
    "meta": {
        "count": 12,
        "group_by": "season",
        "request_id": "req_d30a20f3a24c6dd2"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Half time

`GET /v1/stats/half-time`  
Complimentary key: this season's Premier League.

How often a side ahead at half time goes on to win, draw or lose, by competition and season.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |
| `season` | integer | no | The first year of the season: 2026 for 2026/27. From 2015, or the competition's first season. |
| `group_by` | string | no | How the figures are split: by competition, season, country, or competition and season. competition or season or country or competition_season. |

| Field | Type | What it is |
|---|---|---|
| `season_start_year` | integer | The first year of the season: 2026 for 2026/27 |
| `matches` | integer | Matches counted |
| `led_at_half` | integer | Matches where a side led at half time |
| `lead_held_pct` | integer | Share of those the leader won, as a percentage |
| `lead_lost_pct` | number | Share of those the leader lost, as a percentage |
| `home` | object | The home side |
| `home.led` | integer | Matches the club led at half time |
| `home.won_pct` | integer | Share won, as a percentage |
| `home.lost_pct` | number | Share lost, as a percentage |
| `away` | object | The away side |
| `away.led` | integer | Matches the club led at half time |
| `away.won_pct` | number | Share won, as a percentage |
| `away.lost_pct` | number | Share lost, as a percentage |
| `level_at_half` | integer | Matches level at half time |
| `level_stayed_pct` | number | Share of those that ended level, as a percentage |

```bash
curl "https://api.footballapi.org/v1/stats/half-time?competition=premier-league&group_by=season" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": [
        {
            "season_start_year": 2015,
            "matches": 380,
            "led_at_half": 212,
            "lead_held_pct": 75,
            "lead_lost_pct": 8.02,
            "home": {
                "led": 125,
                "won_pct": 76,
                "lost_pct": 7.2
            },
            "away": {
                "led": 87,
                "won_pct": 73.56,
                "lost_pct": 9.2
            },
            "level_at_half": 168,
            "level_stayed_pct": 42.26
        },
        {
            "season_start_year": 2016,
            "matches": 380,
            "led_at_half": 227,
            "lead_held_pct": 79.74,
            "lead_lost_pct": 5.29,
            "home": {
                "led": 135,
                "won_pct": 86.67,
                "lost_pct": 3.7
            },
            "away": {
                "led": 92,
                "won_pct": 69.57,
                "lost_pct": 7.61
            },
            "level_at_half": 153,
            "level_stayed_pct": 32.68
        }
    ],
    "meta": {
        "count": 12,
        "group_by": "season",
        "request_id": "req_ab487a7ad8635a4c"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Kickoff times

`GET /v1/stats/kickoff`  
Complimentary key: this season's Premier League.

Results by local kickoff time and by day of the week, by competition and season.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |
| `season` | integer | no | The first year of the season: 2026 for 2026/27. From 2015, or the competition's first season. |
| `group_by` | string | no | How the figures are split: by competition, season, country, or competition and season. competition or season or country or competition_season. |

| Field | Type | What it is |
|---|---|---|
| `hour` | string | Kickoff hour, local time |
| `matches` | integer | Matches counted |
| `goals_per_game` | number | Goals scored a match, on average |
| `home_win_pct` | number | Share of matches the home side won, as a percentage |
| `draw_pct` | number | Share of matches drawn, as a percentage |
| `away_win_pct` | number | Share of matches the away side won, as a percentage |

```bash
curl "https://api.footballapi.org/v1/stats/kickoff?competition=premier-league&group_by=season" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": [
        {
            "hour": "11:00",
            "matches": 92,
            "goals_per_game": 3.087,
            "home_win_pct": 47.83,
            "draw_pct": 23.91,
            "away_win_pct": 28.26
        },
        {
            "hour": "12:00",
            "matches": 799,
            "goals_per_game": 2.755,
            "home_win_pct": 42.3,
            "draw_pct": 23.65,
            "away_win_pct": 34.04
        }
    ],
    "meta": {
        "count": 10,
        "group_by": "season",
        "request_id": "req_9acc972fd115c02c"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Referee stats

`GET /v1/stats/referees`  
Complimentary key: this season's Premier League.

Results and cards by referee, by competition and season.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |
| `season` | integer | no | The first year of the season: 2026 for 2026/27. From 2015, or the competition's first season. |

```bash
curl "https://api.footballapi.org/v1/stats/referees?competition=premier-league&season=2026" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": [],
    "meta": {
        "count": 0,
        "request_id": "req_5b05151fa528a052"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

#### Positions and results

`GET /v1/stats/positions`  
Complimentary key: this season's Premier League.

How the gap between two clubs in the table at kickoff tracks the result, by competition and season.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `competition` | string | no | A competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads. |
| `season` | integer | no | The first year of the season: 2026 for 2026/27. From 2015, or the competition's first season. |
| `group_by` | string | no | How the figures are split: by competition, season, country, or competition and season. competition or season or country or competition_season. |

| Field | Type | What it is |
|---|---|---|
| `position_gap` | integer | Places between the two clubs in the table at kickoff; below 0 when the away side stood higher |
| `meaning` | string | What the gap means, in words |
| `matches` | integer | Matches counted |
| `goals_per_game` | number | Goals scored a match, on average |
| `home_win_pct` | number | Share of matches the home side won, as a percentage |
| `draw_pct` | number | Share of matches drawn, as a percentage |
| `away_win_pct` | number | Share of matches the away side won, as a percentage |

```bash
curl "https://api.footballapi.org/v1/stats/positions?competition=premier-league&group_by=season" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer, first rows shown:

```json
{
    "data": [
        {
            "position_gap": -15,
            "meaning": "away side 15+ places higher",
            "matches": 514,
            "goals_per_game": 2.844,
            "home_win_pct": 19.65,
            "draw_pct": 21.6,
            "away_win_pct": 58.75
        },
        {
            "position_gap": -12,
            "meaning": "away side 12+ places higher",
            "matches": 749,
            "goals_per_game": 2.738,
            "home_win_pct": 28.04,
            "draw_pct": 23.9,
            "away_win_pct": 48.06
        }
    ],
    "meta": {
        "count": 11,
        "group_by": "season",
        "request_id": "req_b3dcdfbe499f39cb"
    }
}
```

Errors: 401 `unauthorized`, 400 `bad_request`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `quota_exceeded`.

### Your key

#### Usage

`GET /v1/usage`  
Every key.

Your plan, your calls today, your limits and when they reset. Calling it never counts against your allowance.

| Field | Type | What it is |
|---|---|---|
| `plan` | string | Your plan |
| `reads` | string | What your key reads |
| `live` | boolean | Whether your key reads live scores |
| `calls_today` | integer | Calls counted today, UTC |
| `limit_per_day` | integer | Calls a day; null for no ceiling |
| `limit_per_minute` | integer | Calls a minute |
| `resets_at` | string | When the day's count goes back to nought, UTC |
| `key` | string | The start of the key you called with |
| `key_status` | string | active, or when a replaced key stops working |

```bash
curl "https://api.footballapi.org/v1/usage" -H "X-API-Key: $FOOTBALLAPI_KEY"
```

Example answer:

```json
{
    "data": {
        "plan": "Complimentary key",
        "reads": "This season's Premier League",
        "live": false,
        "calls_today": 0,
        "limit_per_day": 50,
        "limit_per_minute": 10,
        "resets_at": "2026-10-22T00:00:00Z",
        "key": "fa_live_7Q2M...",
        "key_status": "active"
    },
    "meta": {
        "request_id": "req_bb839cb2a75ca9bf"
    }
}
```

Errors: 401 `unauthorized`, 422 `unknown_parameter`, 429 `rate_limited`.

## MCP server

`https://footballapi.org/mcp` speaks MCP over Streamable HTTP. Send the key in `X-API-Key` or `Authorization: Bearer`; Claude and ChatGPT connectors sign the member in with OAuth instead (discovery at `https://footballapi.org/.well-known/oauth-protected-resource`). Each tool calls one endpoint with the same plan and limits; a refusal comes back as a tool result marked as an error.

| Tool | Endpoint |
|---|---|
| `list_competitions` | `GET /v1/competitions` |
| `league_table` | `GET /v1/competitions/{competition}/seasons/{season}/table` |
| `season_stats` | `GET /v1/competitions/{competition}/seasons/{season}/stats` |
| `find_matches` | `GET /v1/matches` |
| `get_match` | `GET /v1/matches/{match_id}` |
| `find_results` | `GET /v1/results` |
| `upcoming_fixtures` | `GET /v1/fixtures` |
| `live_scores` | `GET /v1/live` |
| `find_clubs` | `GET /v1/clubs` |
| `get_club` | `GET /v1/clubs/{club_id}` |
| `club_form` | `GET /v1/clubs/{club_id}/form` |
| `head_to_head` | `GET /v1/clubs/{club_id}/head-to-head/{opponent_id}` |
| `check_usage` | `GET /v1/usage` |

The agent skill: https://footballapi.org/skill.md

## Competitions

| Competition | Name | First season |
|---|---|---|
| `champions-league` | Champions League | 2015/16 |
| `europa-league` | Europa League | 2015/16 |
| `conference-league` | Conference League | 2021/22 |
| `nations-league` | Nations League | 2018/19 |
| `world-cup` | World Cup | 2015 |
| `world-cup-qualifiers` | World Cup qualifiers | 2015 |
| `euro` | European Championship | 2015 |
| `euro-qualifiers` | Euro qualifiers | 2015 |
| `premier-league` | England, Premier League | 2015/16 |
| `championship` | England, Championship | 2015/16 |
| `league-one` | England, League One | 2015/16 |
| `league-two` | England, League Two | 2015/16 |
| `national-league` | England, National League | 2015/16 |
| `national-league-north` | England, National League North | 2019/20 |
| `national-league-south` | England, National League South | 2019/20 |
| `la-liga` | Spain, La Liga | 2015/16 |
| `segunda-division` | Spain, Segunda División | 2015/16 |
| `primera-federacion` | Spain, Primera Federación | 2019/20 |
| `segunda-federacion` | Spain, Segunda Federación | 2021/22 |
| `bundesliga` | Germany, Bundesliga | 2015/16 |
| `2-bundesliga` | Germany, 2. Bundesliga | 2015/16 |
| `3-liga` | Germany, 3. Liga | 2015/16 |
| `serie-a` | Italy, Serie A | 2015/16 |
| `serie-b` | Italy, Serie B | 2015/16 |
| `ligue-1` | France, Ligue 1 | 2015/16 |
| `ligue-2` | France, Ligue 2 | 2015/16 |
| `national-1` | France, National 1 | 2015/16 |
| `scottish-premiership` | Scotland, Premiership | 2015/16 |
| `scottish-championship` | Scotland, Championship | 2015/16 |
| `scottish-league-one` | Scotland, League One | 2015/16 |
| `scottish-league-two` | Scotland, League Two | 2015/16 |
| `highland-league` | Scotland, Highland League | 2020/21 |
| `lowland-league` | Scotland, Lowland League | 2020/21 |
| `primeira-liga` | Portugal, Primeira Liga | 2015/16 |
| `liga-portugal-2` | Portugal, Liga Portugal 2 | 2016/17 |
| `liga-3` | Portugal, Liga 3 | 2021/22 |
| `eredivisie` | Netherlands, Eredivisie | 2015/16 |
| `belgian-pro-league` | Belgium, Pro League | 2015/16 |
| `challenger-pro-league` | Belgium, Challenger Pro League | 2016/17 |
| `belgian-national-1` | Belgium, National 1 | 2019/20 |
| `super-lig` | Turkey, Süper Lig | 2015/16 |
| `1-lig` | Turkey, 1. Lig | 2015/16 |
| `2-lig` | Turkey, 2. Lig | 2015/16 |
| `austrian-bundesliga` | Austria, Bundesliga | 2015/16 |
| `austrian-2-liga` | Austria, 2. Liga | 2015/16 |
| `swiss-super-league` | Switzerland, Super League | 2016/17 |
| `challenge-league` | Switzerland, Challenge League | 2016/17 |
| `greek-super-league` | Greece, Super League | 2015/16 |
| `greek-super-league-2` | Greece, Super League 2 | 2015/16 |
| `superliga` | Denmark, Superliga | 2015/16 |
| `danish-1st-division` | Denmark, 1st Division | 2015/16 |
| `danish-2nd-division` | Denmark, 2nd Division | 2015/16 |
| `allsvenskan` | Sweden, Allsvenskan | 2016 |
| `eliteserien` | Norway, Eliteserien | 2016 |
| `veikkausliiga` | Finland, Veikkausliiga | 2015 |
| `league-of-ireland` | Ireland, Premier Division | 2019 |
| `nifl-premiership` | Northern Ireland, Premiership | 2017/18 |
| `cymru-premier` | Wales, Cymru Premier | 2015/16 |
| `czech-first-league` | Czech Republic, First League | 2018/19 |
| `slovak-first-league` | Slovakia, First League | 2018/19 |
| `prvaliga` | Slovenia, PrvaLiga | 2018/19 |
| `ukrainian-premier-league` | Ukraine, Premier League | 2015/16 |
| `liga-1` | Romania, Liga I | 2016/17 |
| `bulgarian-first-league` | Bulgaria, First League | 2018/19 |
| `virsliga` | Latvia, Virsliga | 2015 |
| `brasileirao` | Brazil, Série A | 2015 |
| `liga-mx` | Mexico, Liga MX | 2016/17 |
| `mls` | USA, MLS | 2015 |

## Changes

- 2026-10-21: The API opens with 40 endpoints: competitions, seasons and tables, matches, results, fixtures, live scores, clubs, grounds and stats.
- 2026-10-21: The MCP server, the agent skill and the manual, all built from the same list of endpoints.