Club rankings

GET /v1/rankings/clubs

Our club rankings over twelve months, by country or competition

Our own rankings, worked out every night over the twelve months to the day before. Results count, weighed by the strength of the opposition and of the competition, and newer matches count for more. Club football only: national-team matches, youth and women's sides and friendlies are left out. score runs from 0 to 100, the best at 100.

Every club with 10 matches or more in the twelve months is ranked, the latest within six months: about 8,000 of them. Narrow it to a country or a competition and position is the club's place in that list, while rank stays its place in the world. Each row says where the club stood a week and a year ago. On the Live & Archive plan. Our top 50 are on the Rankings page, free to read.

This is a different list from /v1/rankings, which orders teams by their rating from results alone.

Plan

This endpoint needs Live & Archive. Calling it on a lower plan returns a 403 naming the plan it needs and a link to pricing, never a bare refusal.

Parameters

country string query

Only the clubs (or the players at clubs) of one country, by name as returned from /v1/countries. A club belongs to the country of the league it plays most of its matches in. e.g. Spain

league_id string query

Only the clubs (or the players at clubs) whose main competition this is. e.g. lg_24T9Z0G

page integer query

Page number, 1-based. The response carries total, total_pages, next_page and prev_page, so a UI pager has everything it needs from one call. If you send both page and cursor, page wins. e.g. 2

limit integer query

Rows per page, 1 to 500. Defaults to 50. e.g. 100

Returns

data[].position integer

Its place in the list as asked: within the country, competition, club or role you narrowed it to.

data[].rank integer

Its place in the list, 1 being the best; in our rankings, its place across the world.

data[].team_id string

Our id for the club.

data[].team_name string

The club's name.

data[].country_name string

The country the competition belongs to.

data[].league_id string

Our id for the competition.

data[].league_name string

The competition's name.

data[].score integer

Our score, 0 to 100: the best ranked at 100.

data[].rank_week_ago empty in this example

Its rank a week ago; empty when it was not ranked then.

data[].places_moved_week empty in this example

Places gained over the week; negative for places lost.

data[].rank_year_ago empty in this example

Its rank a year ago; empty when it was not ranked then.

data[].matches integer

Matches counted.

data[].wins integer

Matches won.

data[].draws integer

Matches drawn.

data[].losses integer

Matches lost.

data[].goals_for integer

Goals scored.

data[].goals_against integer

Goals conceded.

data[].form string

The last five results, oldest first: W, D or L.

data[].last_played string

The latest match played, as a UTC timestamp.

meta.data_as_of string

When the data behind this answer was last brought up to date.

meta.request_id string

This request's id, to quote to support.

meta.count integer

How many items are in this answer.

meta.page integer

This page's number.

meta.per_page integer

How many items a page holds.

meta.total integer

How many items match in all.

meta.ranked_at string

When the rankings were worked out, as a UTC timestamp.

meta.window_from string

The first day of the twelve months counted.

meta.window_to string

The last day of the twelve months counted.

Request

curl "https://api.footballsoccerapi.com/v1/rankings/clubs?country=Spain&league_id=lg_24T9Z0G&page=2" \
  -H "X-API-Key: $FSAPI_KEY"

const res = await fetch("https://api.footballsoccerapi.com/v1/rankings/clubs?country=Spain&league_id=lg_24T9Z0G&page=2", {
  headers: { "X-API-Key": process.env.FSAPI_KEY }
});
const { data, meta } = await res.json();

import os, requests

r = requests.get(
    "https://api.footballsoccerapi.com/v1/rankings/clubs?country=Spain&league_id=lg_24T9Z0G&page=2",
    headers={"X-API-Key": os.environ["FSAPI_KEY"]},
)
data = r.json()["data"]

$ch = curl_init("https://api.footballsoccerapi.com/v1/rankings/clubs?country=Spain&league_id=lg_24T9Z0G&page=2");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: {$key}"],
]);
$data = json_decode(curl_exec($ch), true)["data"];

Example response

A real row from the archive, fetched when this page rendered. Run it against your own key below.

200 OK application/json

{
    "data": [
        {
            "position": 1,
            "rank": 1,
            "team_id": "tm_234PN5V",
            "team_name": "Bayern München",
            "country_name": "Germany",
            "league_id": "lg_0S9M0P4",
            "league_name": "Bundesliga",
            "score": 100,
            "rank_week_ago": null,
            "places_moved_week": null,
            "rank_year_ago": null,
            "matches": 55,
            "wins": 42,
            "draws": 10,
            "losses": 3,
            "goals_for": 184,
            "goals_against": 67,
            "form": "DWDWW",
            "last_played": "2026-10-28T19:45:00Z"
        },
        {
            "position": 2,
            "rank": 2,
            "team_id": "tm_3C40GEH",
            "team_name": "Arsenal",
            "country_name": "England",
            "league_id": "lg_24T9Z0G",
            "league_name": "Premier League",
            "score": 94.7,
            "rank_week_ago": null,
            "places_moved_week": null,
            "rank_year_ago": null,
            "matches": 65,
            "wins": 44,
            "draws": 13,
            "losses": 8,
            "goals_for": 124,
            "goals_against": 53,
            "form": "WWDWD",
            "last_played": "2026-10-27T20:00:00Z"
        }
    ],
    "meta": {
        "data_as_of": "2026-10-29T04:32:57Z",
        "request_id": "01J9QW3C7M4KX2VB",
        "count": 2,
        "page": 1,
        "per_page": 50,
        "total": 7939,
        "ranked_at": "2026-10-29T10:18:53Z",
        "window_from": "2025-10-29",
        "window_to": "2026-10-29"
    }
}

Run it live

Paste your key and fire the real request. The key is kept in this browser only and never sent anywhere but the API.

Your API key Get a key

country league_id page limit

GET

← All endpoints Get a free key →