Standings :: Football API

On this football API reference page, we break down how our competition table API endpoint works.

The competition standings football API endpoint handles team names in a range of languages. To learn more, read through our documentation on language support.

Competition table standings are a vital slice of the football data people care about. It is no longer just live scores, fixtures or history data that matter. With this dedicated football API endpoint, subscribers can pull the current standings of any competition. It returns all standings for every group in a given competition and season. If you only need the standings for one specific group, reach for the group standings API endpoint instead.

Seasons

Before you can fetch data for a specific competition you need the season_id you want standings for. Every season brings a fresh table with fresh standings. Below we outline the seasons we cover, their respective ids and a few example competitions that may not have standings for each season. In our football API there are 2 kinds of seasons. A whole calendar year season, for example 2020, or an autumn/spring season, for example 2018/2019. Which one a competition uses depends on the period it runs. Take the English Premier League (ID 2). It kicks off in autumn and wraps up in spring, so it uses the second format (2021/2022). Competitions like the Swedish Allsvenskan (ID 14) and the Brazileiro (ID 24), which start at the beginning of the calendar year and finish towards the end of the same year, use the first format (2022). When it comes to qualifiers for international competitions involving national teams, the season for the qualification group standings matches the season in which the final tournament takes place. For example, the season for the UEFA EURO Qualifiers Groups is (2020)!

You can read more about our seasons and their ids on the seasons list documentation page.

Endpoint

To get the standings table for a football competition from our football API, all you have to do is call the URL below. We serve table standings data for 400+ competitions from around the globe.

GET:

Check this Football API endpoint in our postman collection. Download it now!

Leave the season parameter out and our football API will work out the current season on its own and return the standings for that season.

The standings table football API endpoint supports a set of parameters you can use to filter the football data and navigate it as you like. They are listed in the table below. Parameters work both together and on their own. This football API endpoint returns standings for all groups across all stages for a given season. If you need the standings for one specific group, use our dedicated group standings API endpoint instead.

For example, the English Premier League has a single stage (Regular Season) with one group inside it. The UEFA Euro has one group stage containing multiple groups. The Bulgarian First Professional League has several stages (regular season, promotional round and relegation), each with one group. Calling this football API endpoint returns all standings for all groups in the given season.

Name	Type	Required	Example	Description
competition_id	Number	1	2	The `id` of the competition you need standings for.
include_form	integer		1	Adds the last 6 matches team form into the response data.
lang	String		ar	The ISO alpha2 code of the language you want the team names returned in.
season_id	Number		11	The `id` of the season you need standings for. Handy when you want standings from past seasons. Omit it and the football API endpoint falls back to the most current season of the competition. You can pull the full list of supported seasons from our season API endpoint.

Response

A response to a request returns every team in the table along with their standings and the relevant information. A JSON example is below. We are showing only a fraction of the teams competing in the English Premier League. A real response would contain all 20 teams, which is simply too big to fit on this page.

{
    "success": true,
    "data": {
        "competition": {
            "id": 2,
            "name": "Premier League",
            "is_league": true,
            "is_cup": false,
            "tier": 1,
            "has_groups": true,
            "active": true,
            "national_teams_only": false
        },
        "season": {
            "id": 57,
            "name": "2026\/2027",
            "start": "2026-07-01",
            "end": "2027-06-30"
        },
        "stages": [
            {
                "stage": {
                    "id": 4011,
                    "name": "Regular Season"
                },
                "groups": [
                    {
                        "id": 4762,
                        "name": "A",
                        "standings": [
                            {
                                "rank": 1,
                                "points": 18,
                                "matches": 6,
                                "goal_diff": 11,
                                "goals_scored": 16,
                                "goals_conceded": 5,
                                "lost": 0,
                                "drawn": 0,
                                "won": 6,
                                "team": {
                                    "id": 12,
                                    "name": "Manchester City",
                                    "stadium": "Etihad Stadium",
                                    "country_id": 19,
                                    "logo": "https:\/\/cdn.football-api.com\/teams\/12.png"
                                }
                            },
                            {
                                "rank": 2,
                                "points": 15,
                                "matches": 6,
                                "goal_diff": 5,
                                "goals_scored": 10,
                                "goals_conceded": 5,
                                "lost": 1,
                                "drawn": 0,
                                "won": 5,
                                "team": {
                                    "id": 18,
                                    "name": "Arsenal",
                                    "stadium": "Emirates Stadium",
                                    "country_id": 19,
                                    "logo": "https:\/\/cdn.football-api.com\/teams\/18.png"
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Name	Type	Example	Description
competition	object	{}	An object that carries the information about the competition you are fetching standings for. It follows the structure of our standard competition object.
drawn	Number	7	The count of matches the team has drawn.
form	Array	W, L, D	The form of the team across its last 6 matches in the competition.
goal_diff	Number	52	The team goal difference. When it is negative you will get a negative number, for example `-6`.
goals_conceded	Number	18	The count of goals the team has let in at their own end.
goals_scored	Number	70	The count of goals the team has put into the opponents net.
lost	Number	1	The count of games the team has lost.
matches	Number	31	The count of matches the team has played.
points	Number	76	The tally of points the team has accumulated.
rank	Number	1	The position the team occupies in the standings table.
season	object	{}	An object carrying information about the season you are fetching competition standings for. It follows the structure of our standard season object.
stages	array	[]	A list of every stage that contains groups with standings, each with its respective data.
stages.groups	array	[]	An array carrying information about every group in a stage along with their standings.
stages.groups.standings.team	object	{}	An object that carries the information about the team in the standings. It follows the structure of our standard team object.
stages.stage	object	{}	An object carrying information about the stage: its `id` and name.
won	Number	23	The count of matches the team has won.

Examples

cUrl:

curl -XGET "https://api.football-api.com/competitions/table.json?competition_id=2&key=demo_key&secret=demo_secret"

PHP:

file_get_contents('https://api.football-api.com/competitions/table.json?competition_id=2\&key=demo_key\&secret=demo_secret');

Python:

import urllib2
req = urllib2.Request('https://api.football-api.com/competitions/table.json?competition_id=2\&key=demo_key\&secret=demo_secret')
response = urllib2.urlopen(req)
print response.read()

In the examples below, you can see how to request a team form through your request. All you need to do is add the following query parameter to your football API request: &include_form=1. Here are a few examples: