# footballsoccerapi.com

> Football and soccer data API. 77 REST endpoints over 1,693,122 matches in 1,138 competitions across 171 countries, back to 2012: fixtures, results, lineups, match statistics, grounds, referees, standings and exchange prices at kickoff and half-time.

## Complete reference

- [Full manual, one file](https://footballsoccerapi.com/documentation/manual.md): every endpoint, parameter, sample response and guide in a single markdown document.
- [OpenAPI](https://footballsoccerapi.com/v1/openapi.json): machine-readable API description.
- [MCP server](https://footballsoccerapi.com/mcp-server): connect an assistant directly.

## Agent skill

- [footballsoccerapi.com agent skill](https://footballsoccerapi.com/.well-known/agent-skills/footballsoccerapi/SKILL.md): how agents use footballsoccerapi.com. Index: https://footballsoccerapi.com/.well-known/agent-skills/index.json

## Guides

- [Getting started](https://footballsoccerapi.com/documentation/getting-started): From nothing to a priced match in four calls.
- [Authentication](https://footballsoccerapi.com/documentation/authentication): One header. No tokens to refresh, no OAuth dance.
- [Pagination](https://footballsoccerapi.com/documentation/pagination): Page numbers for pagers, cursors for exports. Same endpoints, either style.
- [Rate limits](https://footballsoccerapi.com/documentation/rate-limits): Two ceilings, printed on every response. Going over is never a bill.
- [Errors](https://footballsoccerapi.com/documentation/errors): Every refusal tells you what to do about it.
- [Timezones & dates](https://footballsoccerapi.com/documentation/timezones): Kickoff in UTC and in local time, because both matter.
- [Scores and results](https://footballsoccerapi.com/documentation/scores-and-results): What each score means: 90 minutes, extra time, the shootout, awarded and unplayed matches.
- [Historical data](https://footballsoccerapi.com/documentation/historical-data): What is in the archive, and how to read the coverage figures.
- [Live odds](https://footballsoccerapi.com/documentation/live-odds): What the market snapshots are, and what Live adds.
- [The whole API in one file](https://footballsoccerapi.com/documentation/openapi): The manual in Markdown, OpenAPI, Postman and MCP, all generated from the same registry.
- [Batch requests](https://footballsoccerapi.com/documentation/batch-requests): One call for fifty matches instead of fifty calls.
- [The PHP client](https://footballsoccerapi.com/documentation/php-client): No dependencies, no Composer, and a one-file version.
- [The Python client](https://footballsoccerapi.com/documentation/python-client): Standard library only, and it goes straight into pandas.
- [Changelog](https://footballsoccerapi.com/documentation/changelog): Every change, dated. v1 only ever gains fields.

## Endpoints

- [GET /v1/reference](https://footballsoccerapi.com/documentation/reference): Reference data
- [GET /v1/countries](https://footballsoccerapi.com/documentation/countries): Countries
- [GET /v1/leagues](https://footballsoccerapi.com/documentation/leagues): Competitions
- [GET /v1/leagues/{id}](https://footballsoccerapi.com/documentation/league): Competition profile
- [GET /v1/coverage](https://footballsoccerapi.com/documentation/coverage): Coverage
- [GET /v1/leagues/{id}/seasons/{season}](https://footballsoccerapi.com/documentation/league-season): Season detail
- [GET /v1/leagues/{id}/seasons/{season}/stats](https://footballsoccerapi.com/documentation/league-season-stats): Competition season summary
- [GET /v1/leagues/{id}/teams](https://footballsoccerapi.com/documentation/league-teams): Clubs in a competition
- [GET /v1/teams](https://footballsoccerapi.com/documentation/teams): Search clubs
- [GET /v1/teams/{id}](https://footballsoccerapi.com/documentation/team): Club profile
- [GET /v1/venues](https://footballsoccerapi.com/documentation/venues): Grounds
- [GET /v1/referees](https://footballsoccerapi.com/documentation/referees): Officials
- [GET /v1/referees/{id}](https://footballsoccerapi.com/documentation/referee): Official profile
- [GET /v1/matches](https://footballsoccerapi.com/documentation/matches): Search matches
- [GET /v1/matches/{id}](https://footballsoccerapi.com/documentation/match): Match detail
- [GET /v1/matches/{id}/events](https://footballsoccerapi.com/documentation/match-events): Match events
- [GET /v1/matches/{id}/odds](https://footballsoccerapi.com/documentation/match-odds): Match odds
- [GET /v1/matches/{id}/statistics](https://footballsoccerapi.com/documentation/match-statistics): Match statistics
- [GET /v1/matches/{id}/lineups](https://footballsoccerapi.com/documentation/match-lineups): Match lineups
- [GET /v1/matches/{id}/players](https://footballsoccerapi.com/documentation/match-players): Player statistics
- [GET /v1/matches/{id}/absences](https://footballsoccerapi.com/documentation/match-absences): Absences
- [GET /v1/teams/{id}/distance/{opponent_id}](https://footballsoccerapi.com/documentation/team-distance): Distance between clubs
- [GET /v1/grounds](https://footballsoccerapi.com/documentation/grounds): Grounds
- [GET /v1/grounds/{id}](https://footballsoccerapi.com/documentation/ground): Ground profile
- [GET /v1/matches/{id}/preview](https://footballsoccerapi.com/documentation/match-preview): Fixture preview
- [GET /v1/results/today](https://footballsoccerapi.com/documentation/results-today): Today's results
- [GET /v1/results/yesterday](https://footballsoccerapi.com/documentation/results-yesterday): Yesterday's results
- [GET /v1/results/latest](https://footballsoccerapi.com/documentation/results-latest): Latest results
- [GET /v1/results](https://footballsoccerapi.com/documentation/results): Results by date
- [GET /v1/upsets](https://footballsoccerapi.com/documentation/upsets): Upsets
- [GET /v1/seasons/{league}/{season}](https://footballsoccerapi.com/documentation/season): A whole season
- [GET /v1/export/{league}/{season}](https://footballsoccerapi.com/documentation/season-export): Season export
- [GET /v1/teams/{id}/matches](https://footballsoccerapi.com/documentation/team-matches): A club's matches
- [GET /v1/teams/{id}/form](https://footballsoccerapi.com/documentation/team-form): Recent form
- [GET /v1/teams/{id}/stats](https://footballsoccerapi.com/documentation/team-stats): Club statistics
- [GET /v1/teams/{id}/streaks](https://footballsoccerapi.com/documentation/team-streaks): Runs and streaks
- [GET /v1/teams/{id}/match-stats](https://footballsoccerapi.com/documentation/team-match-stats): Team match statistics
- [GET /v1/teams/{id}/head-to-head/{opp}](https://footballsoccerapi.com/documentation/head-to-head): Head to head
- [GET /v1/teams/{id}/market](https://footballsoccerapi.com/documentation/team-market): How the market prices a club
- [GET /v1/teams/{id}/travel](https://footballsoccerapi.com/documentation/team-travel): Travel
- [GET /v1/teams/compare](https://footballsoccerapi.com/documentation/teams-compare): Compare clubs
- [GET /v1/teams/{id}/rating](https://footballsoccerapi.com/documentation/team-rating): Team rating
- [GET /v1/rankings](https://footballsoccerapi.com/documentation/rankings): Rankings
- [GET /v1/rankings/clubs](https://footballsoccerapi.com/documentation/rankings-clubs): Club rankings
- [GET /v1/rankings/players](https://footballsoccerapi.com/documentation/rankings-players): Player rankings
- [GET /v1/teams/{id}/ranking](https://footballsoccerapi.com/documentation/team-ranking): Club ranking
- [GET /v1/players/{id}/ranking](https://footballsoccerapi.com/documentation/player-ranking): Player ranking
- [GET /v1/players/{id}](https://footballsoccerapi.com/documentation/player): Player seasons
- [GET /v1/leagues/{id}/seasons/{season}/players](https://footballsoccerapi.com/documentation/league-season-players): Competition players
- [GET /v1/standings/{league}/{season}](https://footballsoccerapi.com/documentation/standings): League table
- [GET /v1/standings/{league}/{season}/positions](https://footballsoccerapi.com/documentation/standings-positions): Positions at every kickoff
- [GET /v1/fixtures/today](https://footballsoccerapi.com/documentation/fixtures-today): Today's fixtures
- [GET /v1/fixtures/upcoming](https://footballsoccerapi.com/documentation/fixtures-upcoming): Upcoming fixtures
- [GET /v1/fixtures/rescheduled](https://footballsoccerapi.com/documentation/fixtures-rescheduled): Rescheduled kickoffs
- [GET /v1/live](https://footballsoccerapi.com/documentation/live): In play now
- [GET /v1/live/{id}](https://footballsoccerapi.com/documentation/live-match): Live match detail
- [GET /v1/live/odds](https://footballsoccerapi.com/documentation/live-odds): Live prices
- [GET /v1/odds/kickoff](https://footballsoccerapi.com/documentation/odds-kickoff): Kickoff prices
- [GET /v1/odds/half-time](https://footballsoccerapi.com/documentation/odds-halftime): Half-time prices
- [GET /v1/odds/favourites](https://footballsoccerapi.com/documentation/odds-favourites): Favourites
- [GET /v1/odds/bands](https://footballsoccerapi.com/documentation/odds-bands): Price bands
- [GET /v1/odds/overround](https://footballsoccerapi.com/documentation/odds-overround): Market tightness
- [GET /v1/odds/volume](https://footballsoccerapi.com/documentation/odds-volume): Matched volume
- [GET /v1/betfair/markets/{id}](https://footballsoccerapi.com/documentation/betfair-market): Look up by market id
- [GET /v1/betfair/events/{id}](https://footballsoccerapi.com/documentation/betfair-event): Look up by event id
- [POST /v1/backtest](https://footballsoccerapi.com/documentation/backtest): Backtest your rules
- [GET /v1/stats/goals](https://footballsoccerapi.com/documentation/stats-goals): Goals
- [GET /v1/stats/scorelines](https://footballsoccerapi.com/documentation/stats-scorelines): Scorelines
- [GET /v1/stats/home-advantage](https://footballsoccerapi.com/documentation/stats-home-advantage): Home advantage
- [GET /v1/stats/half-time](https://footballsoccerapi.com/documentation/stats-half-time): Half-time conversion
- [GET /v1/stats/kickoff](https://footballsoccerapi.com/documentation/stats-kickoff): Kickoff time
- [GET /v1/stats/referees](https://footballsoccerapi.com/documentation/stats-referees): Officials
- [GET /v1/stats/positions](https://footballsoccerapi.com/documentation/stats-positions): Position and result
- [GET /v1/usage](https://footballsoccerapi.com/documentation/usage): Your usage
- [GET /v1/status](https://footballsoccerapi.com/documentation/status): Service status
- [POST /webhooks](https://footballsoccerapi.com/documentation/webhooks): Webhooks
- [POST /mcp](https://footballsoccerapi.com/documentation/mcp): Assistant tools