football-data APIfootball-data.org ↗
Access football competitions, live match scores, standings, top scorers, team squads, and head-to-head history across major leagues via 16 endpoints.
What is the football-data API?
The football-data.org API covers 16 endpoints spanning competitions, matches, teams, players, and geographic areas. get_competition_standings returns full league tables with position, points, wins, draws, losses, and goal data. get_match_head2head delivers aggregate win/draw/loss counts and full match history between two clubs. Data spans major European leagues, cup competitions, and continental tournaments.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/fc8fa4d3-21c5-48eb-8805-dab2c13907f5/list_areas' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace football-data-org-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Football Data API - Walkthrough: competitions, standings, matches, teams, and scorers."""
from parse_apis.football_data_api import FootballData, MatchStatus, Venue, ResourceNotFound
client = FootballData()
# List all competitions and print the first few
for comp in client.competitions.list(limit=3):
print(comp.name, comp.code, comp.type)
# Construct a competition by ID and get its standings
pl = client.competition(id=2021)
for standing in pl.standings.list(limit=1):
for entry in standing.table[:3]:
print(entry.position, entry.team.name, entry.points, entry.goal_difference)
# Get finished matches from a competition, drill into one
match = pl.matches.list(status=MatchStatus.FINISHED, limit=1).first()
if match:
print(match.home_team.name, "vs", match.away_team.name, match.score.winner)
# Head-to-head history for that match
for h2h in match.head2head.list(limit=3):
print(h2h.utc_date, h2h.home_team.name, h2h.score.full_time.home, "-", h2h.score.full_time.away, h2h.away_team.name)
# Get a team's full details from a summary
if match:
team = match.home_team.details()
print(team.name, team.venue, team.coach.name)
# Team's recent home matches
for m in team.matches.list(venue=Venue.HOME, status=MatchStatus.FINISHED, limit=3):
print(m.utc_date, m.home_team.name, m.score.full_time.home, "-", m.score.full_time.away, m.away_team.name)
# Typed error handling - request a non-existent resource
try:
client.teams.list(offset=99999, limit=1).first()
except ResourceNotFound as exc:
print(f"Resource not found: {exc}")
print("exercised: competitions.list / standings.list / matches.list / head2head.list / team.details / team.matches.list")
Retrieve all available geographic areas/regions (countries, continents, sub-regions). Returns a flat list of all areas with their parent hierarchy. Each area carries an id, name, countryCode, optional flag URL, and parent relationship.
No input parameters required.
{
"type": "object",
"fields": {
"areas": "array of area objects with id, name, countryCode, flag, parentAreaId, parentArea",
"count": "integer total number of areas"
},
"sample": {
"data": {
"areas": [
{
"id": 2000,
"flag": null,
"name": "Afghanistan",
"parentArea": "Asia",
"countryCode": "AFG",
"parentAreaId": 2014
},
{
"id": 2077,
"flag": "https://crests.football-data.org/EUR.svg",
"name": "Europe",
"parentArea": "World",
"countryCode": "EUR",
"parentAreaId": 2267
}
],
"count": 272,
"filters": {}
},
"status": "success"
}
}About the football-data API
Competitions and Standings
The API identifies competitions by either numeric ID or string code — 2021 and 'PL' both resolve to the Premier League. get_competition returns the competition type (LEAGUE or CUP), its area, and current season dates. get_competition_standings accepts optional season, matchday, and date parameters to retrieve historical snapshots; the response includes a standings array with one or more groups, each containing a table array with per-team position, points, wins, draws, losses, and goals scored/conceded. get_competition_scorers lists top scorers with goals, assists, penalties, and playedMatches per player.
Matches
get_competition_matches filters by season, matchday, status, stage, group, and a date range up to 10 days. The status field accepts SCHEDULED, LIVE, IN_PLAY, PAUSED, FINISHED, POSTPONED, or CANCELLED. The cross-competition list_matches endpoint accepts comma-separated competition codes (competitions) and specific match IDs (ids), returning a resultSet with count, first/last dates, and number of matches played. Individual match detail via get_match includes full-time and half-time scores plus referee data. get_match_head2head builds on a match ID to return aggregate totals — numberOfMatches, totalGoals, and home/away win counts — alongside the raw list of historical fixtures.
Teams and People
get_team returns the full squad as an array of player objects with position, dateOfBirth, and nationality, plus the current coach with contract dates and a crest URL. get_team_matches supports filtering by venue (HOME or AWAY), season, status, and up to multiple competition codes, with the resultSet including aggregate wins, draws, and losses. get_person and get_person_matches cover individual players and coaches by numeric ID; get_person_matches benefits from providing both a competition code and date range to ensure results are returned reliably.
Geographic Coverage
list_areas returns all regions — countries, continents, and sub-regions — each with a parentAreaId linking to the hierarchy. get_area distinguishes continent-level areas (which populate childAreas) from country-level areas (which return an empty childAreas array). Area IDs can be passed to list_competitions to filter competitions by region.
The football-data API is a managed, monitored endpoint for football-data.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when football-data.org changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official football-data.org API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Display live and upcoming fixture lists for a specific competition using
get_competition_matchesfiltered by status - Build a league table widget pulling position, points, and goal difference from
get_competition_standings - Show head-to-head records between two clubs before a match using
get_match_head2headaggregates - Render a team profile page with squad list, coach details, and crest from
get_team - Track a player's recent appearances across competitions with
get_person_matchesfiltered by date range - List top scorers with goal and assist totals for a season using
get_competition_scorers - Build a cross-league match ticker covering multiple competitions simultaneously via
list_matcheswith comma-separated competition codes
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does football-data.org have an official developer API?+
What does `get_competition_standings` return and how do I get historical data?+
get_competition_standings returns a standings array containing one or more groups, each with a table array covering team position, points, wins, draws, losses, goals for, and goals against for the current season by default. Pass the season parameter as a start year (e.g. 2022) to retrieve a past season, or use matchday to get the table as it stood on a specific round.Are match events like goals, cards, and substitutions included in match responses?+
get_match and get_competition_matches cover score, status, teams, and referee data, but individual in-match events (goal scorers, booking details, substitutions) are not exposed as discrete fields. You can fork the API on Parse and revise it to add an endpoint targeting that event-level detail.What is the date range limit for match queries, and what happens if I exceed it?+
get_competition_matches and list_matches must not span more than 10 days. Exceeding this window is a stated constraint of those endpoints, so queries should be split into multiple calls when broader coverage is needed.