---
name: footballapi
description: Answer football questions from Football API (footballapi.org): results, fixtures, league tables on any date, club form, head to head, grounds and live scores for sixty leagues and the European and world competitions since 2015/16. Use for any question about a football match, season, table or club.
---

# Football API

Football results, fixtures, league tables on any date, club form, head to head, grounds and live scores, as JSON at `https://api.footballapi.org/v1`. Sixty leagues in thirty countries, the European club competitions, the World Cup and the Euros, every season back to 2015/16.

## When to use it

Use it for a fact about a match, a season, a table or a club in that collection: a score, a run of results, who plays next, where a club stood on a date, a club's form, a head to head. Do not use it for odds, betting prices, line-ups or player statistics: it does not serve them.

## Access

- A complimentary key comes from signing in with Google at https://footballapi.org/key. It reads this season's Premier League.
- Send it in the `X-API-Key` header (or `Authorization: Bearer`) on every GET, read from the `FOOTBALLAPI_KEY` environment variable. Never put it in the address.
- Membership ($29 a month) reads all 68 competitions and live scores.

## The calls

| Ask | Call |
|---|---|
| Every league and competition, and whether your key reads it | `GET /v1/competitions` |
| A competition: its seasons and how many matches | `GET /v1/competitions/premier-league` |
| Every country with its competitions | `GET /v1/countries` |
| A season of a competition in figures | `GET /v1/competitions/premier-league/seasons/2026` |
| The table now, or on any morning | `GET /v1/competitions/premier-league/seasons/2026/table` |
| Every club's place before every match | `GET /v1/competitions/premier-league/seasons/2026/positions` |
| The clubs of a season, with their grounds | `GET /v1/competitions/premier-league/seasons/2026/clubs` |
| Every match of a season, in kickoff order | `GET /v1/competitions/premier-league/seasons/2026/matches` |
| Goals, results and scorelines of a season | `GET /v1/competitions/premier-league/seasons/2026/stats` |
| Search every match by competition, club, season, date and more | `GET /v1/matches?competition=premier-league&season=2026` |
| The score at every stage, positions before kickoff, the ground and the day | `GET /v1/matches/mt_95kf4jw9a` |
| Every goal and card, to the minute | `GET /v1/matches/mt_95kf4jw9a/events` |
| Shots, possession, corners and cards, side by side | `GET /v1/matches/mt_95kf4jw9a/stats` |
| Settled matches by date, competition or club, newest first | `GET /v1/results?competition=premier-league` |
| Every match settled today so far | `GET /v1/results/today` |
| Every match settled yesterday | `GET /v1/results/yesterday` |
| The most recent results, newest first | `GET /v1/results/latest?competition=premier-league` |
| Matches still to come, kickoff in UTC | `GET /v1/fixtures?competition=premier-league` |
| Every match kicking off today | `GET /v1/fixtures/today` |
| Kickoffs that have moved | `GET /v1/fixtures/rescheduled?days=30` |
| Every match being played now, with the minute (membership) | `GET /v1/live` |
| The score and events of a match being played (membership) | `GET /v1/live/mt_4gfmswg7x` |
| Every club, by competition, season or country | `GET /v1/clubs?competition=premier-league` |
| A club, its ground and where it is | `GET /v1/clubs/cl_4x2bczxvv` |
| Every match of a club, by season, home or away | `GET /v1/clubs/cl_4x2bczxvv/matches` |
| The last results of a club, with a summary | `GET /v1/clubs/cl_4x2bczxvv/form?last=5` |
| Goals, clean sheets and results, home and away | `GET /v1/clubs/cl_4x2bczxvv/stats?season=2026` |
| Current and longest runs | `GET /v1/clubs/cl_4x2bczxvv/streaks?season=2026` |
| How far a club travels, and how it does at each distance | `GET /v1/clubs/cl_4x2bczxvv/travel?season=2026` |
| Every meeting between two clubs | `GET /v1/clubs/cl_4x2bczxvv/head-to-head/cl_frt0n2e46` |
| Every ground, by country, surface or size | `GET /v1/grounds` |
| A ground: its city, capacity and surface | `GET /v1/grounds/gd_bdv848ber` |
| Goals a game, over and under, both sides scoring | `GET /v1/stats/goals?competition=premier-league&group_by=season` |
| How often each scoreline happens | `GET /v1/stats/scorelines?competition=premier-league&group_by=season` |
| How often the home side wins | `GET /v1/stats/home-advantage?competition=premier-league&group_by=season` |
| How often a half-time lead holds | `GET /v1/stats/half-time?competition=premier-league&group_by=season` |
| Results by kickoff time and weekday | `GET /v1/stats/kickoff?competition=premier-league&group_by=season` |
| Results and cards by referee | `GET /v1/stats/referees?competition=premier-league&season=2026` |
| How the gap in the table tracks the result | `GET /v1/stats/positions?competition=premier-league&group_by=season` |
| Your plan, calls today and limits; never counted | `GET /v1/usage` |

For example, a club's form:

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

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

## MCP server

`https://footballapi.org/mcp`, Streamable HTTP. Send the key in `X-API-Key`; Claude and ChatGPT sign in with OAuth instead. Tools: `list_competitions`, `league_table`, `season_stats`, `find_matches`, `get_match`, `find_results`, `upcoming_fixtures`, `live_scores`, `find_clubs`, `get_club`, `club_form`, `head_to_head`, `check_usage`.

## Limits

- Complimentary key: 50 calls a day (reset 00:00 UTC) and 10 a minute. Membership: 120 a minute, no daily ceiling.
- `/v1/usage` shows what is left and never counts against the day. Every answer carries `X-RateLimit-Remaining`; the complimentary key also `X-Quota-Remaining`.
- History goes back to 2015/16, or the league's first season, as `/v1/competitions` gives it. Lists page at up to 1000 rows.

## Errors

An error is `{"error": {"code", "message", "docs"}, "meta": {"request_id"}}`; act on `error.code`.

- `403 upgrade_required`: past what the key reads, or live scores on the complimentary key. Tell the person membership opens it (https://footballapi.org/membership); do not retry.
- `429 rate_limited`: wait `Retry-After` seconds, then carry on. `429 quota_exceeded`: the day is used; stop and say it resets at 00:00 UTC.
- `404 not_found`: no such id, competition or season. `400 bad_request` and `422 unknown_parameter`: fix what the message names.

## How to work

1. Find the competition's name with `/v1/competitions` (it gives whether the key reads it and the first season). Names look like `premier-league`.
2. A season is its first year: `2026` means 2026/27. Calendar-year leagues use the year itself.
3. Take match ids (`mt_...`), club ids (`cl_...`), ground ids (`gd_...`) and referee ids (`rf_...`) from answers and pass them back; never guess them.
4. For a run of results use `/v1/results` with `date_from` and `date_to`, `per_page=1000`, following `meta.next_cursor` as `cursor` until it is null.
5. Before a long job, check `/v1/usage`.
6. Times are UTC; say so when answering.

Every field, parameter and example is in the manual: https://footballapi.org/documentation/manual.md