# 5DollarFootballAPI

> The affordable football API — the same data, from $5/mo. A read-only REST API for football (soccer) data: live scores, fixtures, standings, team statistics, match events, corner and card statistics, and bookmaker odds including tick-level price history. Responses are JSON; authenticate with an API key in an Authorization: Bearer header.

Match events are included: the timeline of goals, corners, yellow and red cards, substitutions (with the players coming on and off) and missed penalties, each with its minute and side. Not covered: player-level and venue data — no lineups or formations, squads, player statistics, goal-scorer names, injuries, transfers or venues.

Plans: Free — 60 requests / hour, explore real football odds. The five big leagues, every Bet365 market, no credit card. Pro — $5/month, 10 requests / min, 130+ competitions, odds for a whole fixture list in one call, 12 months of history. Ultra — $25/month, 40 requests / min, all leagues, 20 bookmakers, full odds tick history back to 2014 for supported competitions (depth per league and season is published on the data quality page); the same plan at a higher rate is 60 requests / min for $35, 80 for $45, 100 for $55 and 120 for $65 a month. Community — $0 for students, researchers, early-career developers and anyone for whom $5 a month is a real decision: the free plan plus one country's leagues, 12 months of history, 300 requests / hour, switched on at https://5dollarfootballapi.com/community. Business — custom rate limits.

## API description

- [OpenAPI description](https://5dollarfootballapi.com/openapi.json): machine-readable description of every /v1 endpoint.
- [APIs.json manifest](https://5dollarfootballapi.com/apis.json): discovery manifest for API directories.
- [API catalog](https://5dollarfootballapi.com/.well-known/api-catalog): RFC 9727 linkset — the API, its description, documentation and status, and the MCP server.
- [Documentation](https://5dollarfootballapi.com/docs): endpoint reference, authentication, rate limits, pagination and errors.
- [MCP server](https://5dollarfootballapi.com/docs#mcp-server): hosted Model Context Protocol server at https://mcp.5dollarfootballapi.com/mcp — no install; Claude, ChatGPT, Cursor and other MCP clients query the API directly with your API key (Authorization: Bearer header, or the key as the last path segment for custom connectors). Source on GitHub and npm as football-api-mcp.
- [Client libraries](https://5dollarfootballapi.com/docs#client-libraries): official SDKs — Python (pip install fivedollarfootball) and Node.js (npm install fivedollarfootball).
- [Examples](https://5dollarfootballapi.com/examples): worked projects with code that runs as pasted, listed one by one under Examples below.
- [Switch from API-Football](https://5dollarfootballapi.com/docs/migrate-from-api-football): the API-Football v3 compatible host — same endpoints, parameters and JSON; change the base URL and key, fetch new ids once; coverage, differences and cutover checklist.
- [Football API overview](https://5dollarfootballapi.com/football-api): every data type — live scores, fixtures, standings, statistics, odds, corners, cards — with the endpoint behind each and the plan that reaches it.
- [Changelog](https://5dollarfootballapi.com/docs/changelog): what changed in the API and when.
- [Pro league coverage](https://5dollarfootballapi.com/docs/league-coverage): the competitions in the $5 Pro plan, with ids.
- [Ultra league coverage](https://5dollarfootballapi.com/docs/ultra-league-coverage): every competition we carry with a fixture in the last 12 months, by country, with ids and last-fixture dates.
- [Data quality](https://5dollarfootballapi.com/docs/data-quality): measured, per competition: the share of finished matches in the last 12 months with corner counts, a corner line, pre-match odds, an event timeline and live statistics, plus season-by-season history back to the first season on record. Check a competition here before relying on it. JSON twin at https://5dollarfootballapi.com/docs/data-quality.json; per competition at /docs/data-quality/{league_id}.json. Recount any league yourself with https://github.com/5dollarfootball-api/football-api-verify (Python, no dependencies, works with a free key): it pulls the same fixtures through /v1 and prints its count beside ours.

## Endpoints

- [GET /v1/fixtures](https://5dollarfootballapi.com/docs/fixtures): List fixtures. The window view: fixtures and results for a time window of up to 24 hours (default: today UTC), or every in-play match with ?status=live. For a whole season or one team's matches, see /v1/leagues/{id}/fixtures and /v1/teams/{id}/fixtures. Add ?include=odds,events,stats to expand every row in place — one call per screen, not one call per match. How far back you can query follows your plan: 3 months on Free, 12 months on Pro, back to 2014 on Ultra.
- [GET /v1/fixtures/{id}](https://5dollarfootballapi.com/docs/fixture): Get a fixture. A single fixture with goals, corners, cards and odds lines. Add ?include=events,stats to fold the event timeline and in-play statistics into the same call.
- [GET /v1/fixtures/{id}/odds](https://5dollarfootballapi.com/docs/odds): Fixture odds. Full prices for every market, one entry per requested bookmaker — each of opening, closing and in-play carries the line and both prices. Bet365 (the default) serves twelve markets: 1X2 plus Asian handicap, goal, corner, corner-Asian and card lines — full-time and half-time — both-teams-to-score, and the fixed goal lines ladder (goal_line_fixed: Over/Under 0.5, 1.5, 2.5 … 9.5 quoted side by side, one entry per line with its own opening, closing and in-play prices; null when the book withdrew that line, [] before the ladder feed began on 26 September 2026 or where Bet365 quotes no alternatives). Add more books with ?bookmakers=bet365,pinnacle,… (GET /v1/bookmakers) — they carry 1X2, Asian handicap, goal line and corner line where recorded. Bookmakers beyond bet365 require the Ultra plan.
- [GET /v1/bookmakers](https://5dollarfootballapi.com/docs/bookmakers): List bookmakers. The bookmakers accepted by ?bookmakers= on /v1/fixtures/{id}/odds, in display order. Bet365 carries every market and comes with every plan; the rest require Ultra — the coverage table on the docs index shows what each carries.
- [GET /v1/fixtures/{id}/odds/history](https://5dollarfootballapi.com/docs/odds-history): Odds movement history. The full pre-match and in-play tick history for one market — every recorded price/line change with the score at that moment. Bet365 (the default) carries thirteen markets: 1X2, Asian handicap, goal line and corner line (each full-time and half-time), plus corner Asian handicap, card line, card Asian handicap, both-teams-to-score and the fixed goal lines ladder (goalline_fixed — the response groups the page's ticks per line under lines instead of ticks; ?line=2.5 narrows to one line). Any other bookmaker (?bookmaker=, one at a time) carries 1x2, asian, goalline and corner. The whole endpoint requires the Ultra plan or above — Free and Pro keys get a 403 insufficient_plan.
- [GET /v1/fixtures/{id}/events](https://5dollarfootballapi.com/docs/events): Fixture events. The chronological match timeline: goals, corners, yellow and red cards, substitutions, missed penalties, and half-time / full-time period scores — corners included, which most football APIs leave out.
- [GET /v1/fixtures/{id}/statistics](https://5dollarfootballapi.com/docs/statistics): Fixture statistics. Live match statistics: attacks, shots and possession — with first-half splits.
- [GET /v1/standings](https://5dollarfootballapi.com/docs/standings): Standings. League tables by season, plus corner and card tables via ?type. Corner tables include first-half splits; card tables split yellows and reds. Every response names its "source": "feed" is the table as the data feed carries it; where the feed tracks none, the current table is computed from finished results and marked "computed" (administrative point adjustments excluded). Leagues whose format a computed table cannot represent faithfully return an explicit standings_not_available error — fixtures, results and odds for those leagues are unaffected.
- [GET /v1/countries](https://5dollarfootballapi.com/docs/countries): List countries. The countries leagues belong to, each with its code — the value /v1/leagues?country= takes. Codes are ISO 3166-1 alpha-2 (DE, BR, JP); the football home nations use their ISO 3166-2 subdivision (GB-ENG, GB-SCT, GB-WLS, GB-NIR); continental and international competitions sit under region codes — EUROPE, ASIA, AFRICA, AMERICAS, OCEANIA and WORLD (e.g. the UEFA Champions League is EUROPE, the World Cup is WORLD). The region rows are listed first, then countries alphabetically by English name.
- [GET /v1/leagues](https://5dollarfootballapi.com/docs/leagues): List leagues. Competitions, filterable by popularity, country, search or recent activity. Each carries the kickoff of its latest fixture on record (last_fixture_utc / last_fixture_ts), so a client can tell a live competition from a dormant one.
- [GET /v1/leagues/{id}](https://5dollarfootballapi.com/docs/league): Get a league. A single competition, with its seasons newest first — the valid ?season= values for /v1/leagues/{id}/fixtures and /v1/standings. Exactly one season is marked current. Not every covered league lists seasons: where the feed defines none, seasons is empty and fixtures are queried by start_time/end_time instead.
- [GET /v1/leagues/{id}/fixtures](https://5dollarfootballapi.com/docs/league-fixtures): League fixtures. One league's fixtures and results, newest kickoff first — the bulk entry point for historical data and backtesting. Defaults to your plan's whole history window plus the upcoming schedule, so page 1 is the current season; narrow it with start_time/end_time (no 24h span cap here), pass ?season where the league lists seasons, or ?order=asc to walk the same set chronologically. Supports the same include, status and lang options as /v1/fixtures.
- [GET /v1/teams/{id}](https://5dollarfootballapi.com/docs/team): Get a team. A single team.
- [GET /v1/teams/{id}/fixtures](https://5dollarfootballapi.com/docs/team-fixtures): Team fixtures. One team's matches, home and away, most recent first — recent form, head-to-head material and upcoming games in one list. Supports the same include, status and lang options as /v1/fixtures.
- [GET /v1/chinasportslottery](https://5dollarfootballapi.com/docs/china-sports-lottery): China Sports Lottery. The /v1/fixtures window narrowed to matches on sale in China's state football lotteries, each with its official lottery numbers and the official China Sports Lottery Jingcai (竞彩) 1X2 prices. China Sports Lottery Jingcai (竞彩) is the fixed-odds football lottery with a published price per match; Beijing Single Match (北单) is the Beijing lottery's single-match pool; the Traditional football lottery (传统足球) is the 14-match pool. Same parameters, order and pagination as /v1/fixtures, plus types. Ultra plan and above.
- [GET /v1/status](https://5dollarfootballapi.com/docs/status): Account status. Your plan, limits and today's usage.

## Examples

- [Live scores, rendered from the API](https://5dollarfootballapi.com/scores): the first-party example — today's fixtures, live scores, finished results, corners and cards for every competition we carry, rendered server-side from the same /v1 calls a customer makes. Open it to see what the JSON looks like as a page; each match links to its statistics, head-to-head and odds.
- [Build a live score app](https://5dollarfootballapi.com/examples/live-score-app): Minute, score and corners for every match in play. One call fills the screen; the key stays on your server. Node.js. Runs on the free plan. Calls: GET /v1/fixtures?status=live&per_page=500. Code: https://github.com/5dollarfootball-api/football-live-score-app
- [Build a goal alert bot](https://5dollarfootballapi.com/examples/goal-alert-bot): A message in Telegram or Discord the moment a goal goes in, for every match in play. One call a minute. Python. Runs on the free plan. Calls: GET /v1/fixtures?status=live&per_page=500. Code: https://github.com/5dollarfootball-api/football-goal-alert-bot
- [Backtest opening vs closing odds](https://5dollarfootballapi.com/examples/odds-backtest): Four simple bets over a season, settled at the opening price and again at the closing price. See what each returned. Python. Needs the Pro plan. Calls: GET /v1/leagues?search=Premier League&country=GB-ENG; GET /v1/leagues/{id}/fixtures?season=25/26&status=finished&include=odds&per_page=50. Code: https://github.com/5dollarfootball-api/football-odds-backtest
- [Plot an odds movement chart](https://5dollarfootballapi.com/examples/odds-movement-chart): Every recorded 1X2 price for a match, from the opening quote to the final whistle, as one chart. Python. Needs the Ultra plan. Calls: GET /v1/leagues?search=Premier League&country=GB-ENG; GET /v1/leagues/{id}/fixtures?status=finished&per_page=1; GET /v1/fixtures/{id}/odds/history?market=1x2&per_page=500. Code: https://github.com/5dollarfootball-api/football-odds-movement-chart
- [Build a corner stats table](https://5dollarfootballapi.com/examples/corner-stats-table): Corners for and against, per-match averages and first-half splits for every team in a league. One call. Python. Runs on the free plan. Calls: GET /v1/leagues?search=Premier League&country=GB-ENG; GET /v1/standings?league={id}&type=corner. Code: https://github.com/5dollarfootball-api/football-corner-stats-table
- [Build an AI football assistant](https://5dollarfootballapi.com/examples/ai-football-assistant): Connect Claude, ChatGPT or Cursor to live football data and ask in plain language. No code, no install. Runs on the free plan. Calls: search_leagues; get_standings; get_fixtures; get_fixture_odds. Code: https://github.com/5dollarfootball-api/football-api-mcp

## About

- [Pricing](https://5dollarfootballapi.com/pricing): plan limits and prices.
- [Trust center](https://5dollarfootballapi.com/trust): every measured claim in one place with its method and source — independently monitored uptime, per-match freshness, event capture delay, per-league coverage, known limitations; JSON twin at https://5dollarfootballapi.com/trust/evidence.json for citing figures.
- [Status & data freshness](https://5dollarfootballapi.com/status): measured live-data delay, results completeness, standings age and availability; JSON twin at https://5dollarfootballapi.com/status.json.
- [Usage rights](https://5dollarfootballapi.com/terms): commercial use, end-user display and caching are allowed. Public-facing products on Free and Community Access must display “Football data by 5DollarFootballAPI” with a link to the site; attribution is optional on paid plans and for private or internal use. Reselling or redistributing the raw feed is not permitted.
- [How to evaluate a football API](https://5dollarfootballapi.com/how-to-evaluate-a-football-api): seven checks and a five-minute test plan to run against any provider, us included.
- [Free tier](https://5dollarfootballapi.com/free-football-api): what a free key reaches, and how to get one.
- [Get an API key](https://5dollarfootballapi.com/signup): sign up and receive a free key immediately.
- [Coverage](https://5dollarfootballapi.com/coverage): competition counts by region.
- [Contact](https://5dollarfootballapi.com/contact): support and sales.