# Football API

> Results, fixtures, league tables on any date, club form, head to head, grounds and live scores for sixty leagues in thirty countries, the European club competitions, the World Cup and the Euros, every season back to 2015/16. JSON over HTTPS at https://api.footballapi.org/v1, with the key in the X-API-Key header.

A complimentary key reads this season's Premier League, 50 calls a day. Membership ($29 a month or $299 a year) reads all 68 competitions and live scores, with no daily ceiling.

## Start here

- [The manual](https://footballapi.org/documentation/manual.md): the whole API in one Markdown file
- [MCP server](https://footballapi.org/mcp): 13 tools for Claude, ChatGPT, Cursor and other MCP clients
- [OpenAPI](https://footballapi.org/documentation/openapi.json): every endpoint, parameter and answer, OpenAPI 3.1
- [Quick start](https://footballapi.org/documentation/quick-start): a key, a first call, the answer

## Endpoints

- [Competitions](https://footballapi.org/documentation/competitions): GET /v1/competitions. Every league and competition, and whether your key reads it
- [Competition](https://footballapi.org/documentation/competition): GET /v1/competitions/{competition}. A competition: its seasons and how many matches
- [Countries](https://footballapi.org/documentation/countries): GET /v1/countries. Every country with its competitions
- [Season](https://footballapi.org/documentation/season): GET /v1/competitions/{competition}/seasons/{season}. A season of a competition in figures
- [Table](https://footballapi.org/documentation/table): GET /v1/competitions/{competition}/seasons/{season}/table. The table now, or on any morning
- [Positions](https://footballapi.org/documentation/positions): GET /v1/competitions/{competition}/seasons/{season}/positions. Every club's place before every match
- [Season clubs](https://footballapi.org/documentation/season-clubs): GET /v1/competitions/{competition}/seasons/{season}/clubs. The clubs of a season, with their grounds
- [Season matches](https://footballapi.org/documentation/season-matches): GET /v1/competitions/{competition}/seasons/{season}/matches. Every match of a season, in kickoff order
- [Season stats](https://footballapi.org/documentation/season-stats): GET /v1/competitions/{competition}/seasons/{season}/stats. Goals, results and scorelines of a season
- [Matches](https://footballapi.org/documentation/matches): GET /v1/matches. Search every match by competition, club, season, date and more
- [Match](https://footballapi.org/documentation/match): GET /v1/matches/{match_id}. The score at every stage, positions before kickoff, the ground and the day
- [Events](https://footballapi.org/documentation/match-events): GET /v1/matches/{match_id}/events. Every goal and card, to the minute
- [Match stats](https://footballapi.org/documentation/match-stats): GET /v1/matches/{match_id}/stats. Shots, possession, corners and cards, side by side
- [Results](https://footballapi.org/documentation/results): GET /v1/results. Settled matches by date, competition or club, newest first
- [Today](https://footballapi.org/documentation/results-today): GET /v1/results/today. Every match settled today so far
- [Yesterday](https://footballapi.org/documentation/results-yesterday): GET /v1/results/yesterday. Every match settled yesterday
- [Latest](https://footballapi.org/documentation/results-latest): GET /v1/results/latest. The most recent results, newest first
- [Fixtures](https://footballapi.org/documentation/fixtures): GET /v1/fixtures. Matches still to come, kickoff in UTC
- [Today](https://footballapi.org/documentation/fixtures-today): GET /v1/fixtures/today. Every match kicking off today
- [Rescheduled](https://footballapi.org/documentation/fixtures-rescheduled): GET /v1/fixtures/rescheduled. Kickoffs that have moved
- [Live](https://footballapi.org/documentation/live): GET /v1/live. Every match being played now, with the minute (membership)
- [Live match](https://footballapi.org/documentation/live-match): GET /v1/live/{match_id}. The score and events of a match being played (membership)
- [Clubs](https://footballapi.org/documentation/clubs): GET /v1/clubs. Every club, by competition, season or country
- [Club](https://footballapi.org/documentation/club): GET /v1/clubs/{club_id}. A club, its ground and where it is
- [Club matches](https://footballapi.org/documentation/club-matches): GET /v1/clubs/{club_id}/matches. Every match of a club, by season, home or away
- [Form](https://footballapi.org/documentation/club-form): GET /v1/clubs/{club_id}/form. The last results of a club, with a summary
- [Club stats](https://footballapi.org/documentation/club-stats): GET /v1/clubs/{club_id}/stats. Goals, clean sheets and results, home and away
- [Streaks](https://footballapi.org/documentation/club-streaks): GET /v1/clubs/{club_id}/streaks. Current and longest runs
- [Travel](https://footballapi.org/documentation/club-travel): GET /v1/clubs/{club_id}/travel. How far a club travels, and how it does at each distance
- [Head to head](https://footballapi.org/documentation/head-to-head): GET /v1/clubs/{club_id}/head-to-head/{opponent_id}. Every meeting between two clubs
- [Grounds](https://footballapi.org/documentation/grounds): GET /v1/grounds. Every ground, by country, surface or size
- [Ground](https://footballapi.org/documentation/ground): GET /v1/grounds/{ground_id}. A ground: its city, capacity and surface
- [Goals](https://footballapi.org/documentation/stats-goals): GET /v1/stats/goals. Goals a game, over and under, both sides scoring
- [Scorelines](https://footballapi.org/documentation/stats-scorelines): GET /v1/stats/scorelines. How often each scoreline happens
- [Home advantage](https://footballapi.org/documentation/stats-home-advantage): GET /v1/stats/home-advantage. How often the home side wins
- [Half time](https://footballapi.org/documentation/stats-half-time): GET /v1/stats/half-time. How often a half-time lead holds
- [Kickoff times](https://footballapi.org/documentation/stats-kickoff): GET /v1/stats/kickoff. Results by kickoff time and weekday
- [Referee stats](https://footballapi.org/documentation/stats-referees): GET /v1/stats/referees. Results and cards by referee
- [Positions and results](https://footballapi.org/documentation/stats-positions): GET /v1/stats/positions. How the gap in the table tracks the result
- [Usage](https://footballapi.org/documentation/usage): GET /v1/usage. Your plan, calls today and limits; never counted

## Guides

- [Quick start](https://footballapi.org/documentation/quick-start): Three steps from no key to your first answer: get a key, make a call, read what comes back.
- [Authentication](https://footballapi.org/documentation/authentication): Every call carries your key in a header. This is how to send it, keep it safe and replace it.
- [Plans and limits](https://footballapi.org/documentation/plans-and-limits): What each plan reads, how many calls it makes, how to see what is left, and how fresh each answer is.
- [Pagination](https://footballapi.org/documentation/pagination): Long lists come a page at a time. Walk them by page number, or by the cursor each page hands you.
- [Errors](https://footballapi.org/documentation/errors): Every error has a fixed code, a message that says what to do, and a request id to quote to support.
- [Matches and results](https://footballapi.org/documentation/results-data): Every match since 2015/16, or the league's start: found by competition, club, season or date, with its score at every stage, its events and each side's figures.
- [Fixtures](https://footballapi.org/documentation/fixtures-data): Every match still to come in the competitions your key reads, soonest first, today's kickoffs and the ones that have moved.
- [Seasons and tables](https://footballapi.org/documentation/tables): Any league table as it stood on any morning since 2015/16, every club's place before every match, and each season's clubs, matches and figures.
- [Clubs](https://footballapi.org/documentation/clubs): Clubs by their ids: their matches, form, figures, runs and travel, every meeting between two of them, and every ground.
- [Stats](https://footballapi.org/documentation/stats-data): The collection in figures: goals, scorelines, home advantage, half-time leads, kickoff times, referees and league positions.
- [Live scores](https://footballapi.org/documentation/live-scores): Every match being played now, with the score, the minute and the events so far. Part of membership.
- [Changelog](https://footballapi.org/documentation/changelog): Every change to the API, newest first. Paths, fields and error codes never change their meaning; anything new is added alongside.

## Agent skill

- [Football API agent skill](https://footballapi.org/.well-known/agent-skills/footballapi/SKILL.md): how agents use Football API. Index: https://footballapi.org/.well-known/agent-skills/index.json

## Optional

- [Membership](https://footballapi.org/membership): plans and prices
- [The collection](https://footballapi.org/collection): every league and its first season