The free key reads yesterday again: our one-month trial of today on the free key has finished. Read the changelog
Free API key Register free
Documentation

Football data API documentation

Results, fixtures, live scores, standings and Betfair exchange prices for 1,693,122 matches across 1,381 competitions in 171 countries, with national teams back to 1872.

Every match carries what most feeds leave out: the half-time score, the score after 90 minutes and after extra time, stoppage time, league positions on the day, the ground and its weather at kickoff, how far the away side travelled, and the exchange price at kickoff and at half-time. Results settle as matches finish, and the live feed polls every five seconds while matches are in play.

People build prediction models, backtests, betting tools, fantasy and tipping sites, club and league pages, and assistants that answer football questions. Every sample on these pages is a live row from the archive, so an example never drifts from what the API returns.

75endpoints
1,693,122matches
171countries
1,381competitions

Start here

1Get a free key Sign in with Google and the key is made for you, then kept in this browser for every docs page. Get a free key
2Make the first call Yesterday's settled results, every league, one call. Run it below or copy the code. Run it here
3Read the answer Every answer is data plus meta: the rows, then paging, limits and when the data was built. Getting started
curl "https://api.footballsoccerapi.com/v1/results/yesterday?limit=1" \
  -H "X-API-Key: $FSAPI_KEY"
Get a key
GET

The key you paste here is kept in this browser under footballsoccerapi.com.api_key and fills in on every docs page. A key made at sign-up or rotated in your account lands here by itself.

Every subject 6

What the data covers, how the records link, and the jobs people do with each part, every one with its calls.

Matches and results

Every settled match with its score at half-time, after 90 minutes and after extra time, stoppage time, ground, weather and travel. Filter by league, season, club, date or result, or take a whole season as one file.

/v1/matches /v1/matches/{id} /v1/results/yesterday /v1/results /v1/export/{league}/{season}
Read the guide
Fixtures and live

What is coming, what has moved, and what is in play, with live prices, polled every five seconds while a match is on.

/v1/fixtures/today /v1/fixtures/upcoming /v1/live /v1/live/{id} /v1/live/odds
Read the guide
Odds and markets

Betfair exchange prices at kickoff and at half-time, the volume matched, and a backtest that runs your rules at those prices net of commission, settled on 90 minutes as the exchange settles them.

/v1/matches/{id}/odds /v1/odds/kickoff /v1/odds/half-time /v1/backtest
Read the guide
Teams and form

A club's last results with home and away split, goals by half, streaks, meetings with any opponent, and how far it travels.

/v1/teams/{id}/form /v1/teams/{id}/stats /v1/teams/{id}/head-to-head/{opp} /v1/teams/{id}/distance/{opponent_id}
Read the guide
Standings

The table on any date in any season, rebuilt from the results, so a model can see exactly what was known before kickoff.

/v1/standings/{league}/{season} /v1/standings/{league}/{season}/positions
Read the guide
Players and lineups

Starting elevens, formations, absences and each player's seasons, for the leagues that publish them.

/v1/players/{id} /v1/matches/{id}/lineups /v1/matches/{id}/absences
Read the guide

Guides 14

The things worth knowing once rather than per endpoint: how authentication, paging, limits, errors, scores and dates work, what is in the archive, and how to pull the whole surface as a spec.

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

Every endpoint 75

Every group, every endpoint linked, its plan on the right. Nothing in the API is more than one click from here.

Reference & discovery 13

The lookups every integration starts from: countries with their league and match counts, all competitions, every club with its ground and coordinates, and the enums the API uses.

GET /v1/reference Every enum, code and lookup the API uses F GET /v1/countries Every country, with league and match counts F GET /v1/leagues Every league, filterable by country F GET /v1/leagues/{id} One league, its seasons and coverage F GET /v1/coverage What every competition-season holds, in one list F GET /v1/leagues/{id}/seasons/{season} One league-season, its clubs and dates A GET /v1/leagues/{id}/seasons/{season}/stats A competition-season summarised in one call A GET /v1/leagues/{id}/teams The clubs in a league, by season A GET /v1/teams Search every club by name or country F GET /v1/teams/{id} One club, its ids, ground and leagues F GET /v1/venues Grounds with city and coordinates A GET /v1/referees Officials with match counts A GET /v1/referees/{id} One official and the matches they took A

Matches & results 19

Search and retrieve individual football matches: the full row with score, half-time score, league positions at kickoff, travel distance, venue, and the exchange market recorded at kickoff.

GET /v1/matches The workhorse list, filter on anything on the row F GET /v1/matches/{id} One match, every field it carries F GET /v1/matches/{id}/events Goals and cards, minute by minute A GET /v1/matches/{id}/odds Both price snapshots, volume and overround A GET /v1/matches/{id}/statistics Shots, possession, corners and cards for one match A GET /v1/matches/{id}/lineups Formation, starting eleven, substitutions and minutes played A GET /v1/matches/{id}/players Every player's figures for one match: minutes, rating, goals, shots, passes, tackles, cards A GET /v1/matches/{id}/absences Players out or doubtful for one match: injuries and suspensions A GET /v1/teams/{id}/distance/{opponent_id} How far one club travels to another F GET /v1/grounds Every ground, with capacity and surface F GET /v1/grounds/{id} One ground and how much we hold on it F GET /v1/matches/{id}/preview An upcoming fixture with form and market L GET /v1/results/today Everything settled today L GET /v1/results/yesterday Everything settled yesterday F GET /v1/results/latest The most recent settled results F GET /v1/results Settled results over any date range A GET /v1/upsets The results nobody expected, with the reasons L GET /v1/seasons/{league}/{season} A whole season in one call A GET /v1/export/{league}/{season} A whole season as one file, CSV or JSON A

Team form & stats 11

Club-level analysis across ten seasons: recent form with a home and away split, goals and clean sheets, current and longest runs, head-to-head history and how the market has priced them.

GET /v1/teams/{id}/matches Every match a club has played A GET /v1/teams/{id}/form Last N results, home and away split A GET /v1/teams/{id}/stats Goals, clean sheets, half-time record A GET /v1/teams/{id}/streaks Current and longest runs A GET /v1/teams/{id}/match-stats Shots, possession, corners, cards and formations used A GET /v1/teams/{id}/head-to-head/{opp} The full meeting history between two clubs A GET /v1/teams/{id}/market How the market has priced them over time A GET /v1/teams/{id}/travel Distance travelled and how they fare on the road A GET /v1/teams/compare Two or more clubs side by side A GET /v1/teams/{id}/rating A team rated from results alone, its peak and recent moves A GET /v1/rankings Every active team by rating, or one competition's A

Players 2

Season totals for every player we hold match figures for: appearances, starts, minutes, goals, assists, shots, passes, tackles, cards, saves and the average rating, one row a competition, season and club.

GET /v1/players/{id} One player, every season: appearances, minutes, goals, assists and more A GET /v1/leagues/{id}/seasons/{season}/players Every player in a competition-season, ranked A

Standings 2

League tables computed from the same match rows, as they stood on any date in any season, plus the position of every club at every kickoff.

GET /v1/standings/{league}/{season} The table as it stood on any date A GET /v1/standings/{league}/{season}/positions Every club position at every kickoff A

Odds & markets 9

Exchange match-odds prices: kickoff and half-time snapshots, implied probability, overround, matched volume, price bands and backtesting over the whole archive.

GET /v1/odds/kickoff Kickoff prices across matches A GET /v1/odds/half-time Half-time prices and the drift from kickoff A GET /v1/odds/favourites Matches grouped by favourite strength A GET /v1/odds/bands How results fall by price band A GET /v1/odds/overround Market tightness by league and season A GET /v1/odds/volume Matched volume, pre-match and at kickoff A GET /v1/betfair/markets/{id} Look a match up by its market id A GET /v1/betfair/events/{id} Look a match up by its event id A POST /v1/backtest Your rules, P&L at exchange prices net of commission A

League & global stats 7

Aggregates across leagues and seasons: goals per game, scoreline distribution, home advantage, half-time conversion, kickoff time effects and how league position tracks the result.

GET /v1/stats/goals Goals per game by league and season A GET /v1/stats/scorelines The scoreline distribution A GET /v1/stats/home-advantage Home win rate, by league and season A GET /v1/stats/half-time How often half-time leads convert A GET /v1/stats/kickoff Results by kickoff time and weekday A GET /v1/stats/referees Cards and results by official A GET /v1/stats/positions How league position tracks the result A

Fixtures & live 6

What has not been played yet and what is being played now: the day's card, upcoming fixtures, rescheduled kickoffs, in-play scores and current prices.

GET /v1/fixtures/today Today's card across every league L GET /v1/fixtures/upcoming The fixtures coming up L GET /v1/fixtures/rescheduled Kickoffs that have moved L GET /v1/live Everything in play right now L GET /v1/live/{id} One match, live L GET /v1/live/odds Current prices on in-play matches L

Platform 2

Your own usage against your plan limits, and the health and freshness of the service.

GET /v1/usage Your calls, limits and reset window F GET /v1/status Service health and data_as_of F

Push & assistant 2

Get data pushed to you instead of polling for it: webhooks on kickoff, goals, red cards, lineups and results, and the same registry exposed as assistant tools over MCP.

POST /webhooks Fire on match start, price move or result L POST /mcp The registry as assistant tools A

For assistants and agents

Four ways in, all generated from the same registry as these pages, so none of them can fall behind the API.

MCP server

Connect Claude, ChatGPT, Cursor or Claude Code directly. Send your key as Authorization: Bearer or X-API-Key.

https://footballsoccerapi.com/mcp
Agent skill

One file that teaches an agent the key, the calls for common questions, the limits and the errors. Save it as a skill in Claude or Claude Code.

https://footballsoccerapi.com/skill.md
The manual

The whole API in one Markdown file: every guide, endpoint, parameter and field. Hand it to a model that writes code against the API.

https://footballsoccerapi.com/documentation/manual.md
llms.txt

The short map for crawlers and assistants that look for it at the root of the site.

https://footballsoccerapi.com/llms.txt

Plans in short

Every refusal names the plan it needs. Going over a limit is a wait, never a bill.

FFree key $0

Yesterday, as one whole day. 60 calls a minute, 50 a day.

AArchive $49 a month

Every settled match up to yesterday, with prices, form, standings and player figures. 120 a minute, 250,000 a month.

LLive $99 a month

Everything in Archive, plus today, live scores, fixtures ahead and webhooks. 180 a minute, 600,000 a month.

Compare the plans

What is new

30 October 2026Measured xG back to 2014/15 in six top divisions 30 October 2026Duplicate matches removed from the archive 29 October 2026Every match says why it has no statistics 29 October 2026Our own club and player rankings
The full changelog

The rest

AuthenticationOne key, sent as X-API-Key or Authorization: Bearer. Rotate it any time from your account. ErrorsEvery refusal has a code, a plain message and a link to what to do. PaginationPage numbers for pagers, cursors for exports, on the same endpoints. Rate limitsTwo ceilings, printed on every answer in the headers. WebhooksA push on kickoff, a price move or a result, to an address of yours. StatusSite, API, MCP and webhooks, checked every minute, with their uptime. SupportOpen a ticket and follow it from your account. ClientsA PHP client with no dependencies, and a Python client.

Questions people ask

How far back does the data go?

National teams go back to 1872, and each club competition as far as its seasons are held. Historical data shows the coverage of every field by season.

Can the free key read today's matches?

No. The free key reads yesterday, as one whole day. Today, live scores and the fixtures ahead are on Live. See the plans.

Is the score after 90 minutes or after extra time?

home_goals and away_goals are the final score, after extra time where it was played, never with shootout kicks. The 90-minute score, the extra-time goals and the shootout each have their own fields. Scores and results.

Where do the prices come from?

Betfair exchange prices at kickoff and at half-time, with the volume matched, settled on 90 minutes as the exchange settles them. Live odds explains what each price means.

What happens if I go over my limit?

You get a 429 with the seconds until it resets. There is no overage charge and no automatic upgrade. Rate limits.

Can I use it with Claude or ChatGPT?

Yes. Add the MCP server with your key and the assistant can search matches, read form and pull prices itself. The MCP server.

Are times in UTC?

Every time is UTC, and each match also carries its local date and time. Timezones and dates.

F Free key A Archive L Live Every refusal names the plan it needs, never a bare 403. See the plans.