football-data.org 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.
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'
Retrieve all available geographic areas/regions (countries, continents, sub-regions). Returns a flat list of all areas with their parent hierarchy.
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
}
],
"count": 272,
"filters": {}
},
"status": "success"
}
}About the football-data.org 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.
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.
- 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 | 250 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.