Player rankings
L
GET
/v1/rankings/players
Our player rankings over twelve months, by role, country or club
Our own player rankings, worked out every night over the twelve months to the day before. A player is judged against others in the same role, on what he did with his minutes, the level of the clubs and competitions he did it against and how his side fared while he played. Newer matches count for more. Club football only.
It takes 900 minutes in the twelve months to be ranked, the latest within six months, in a competition we hold player figures for. role_rank is the player's place among his role; ask for one role and the list follows it. Each player is shown at the club of his latest match. On the Live & Archive plan.
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
role
string
query
goalkeeper, defender, midfielder or forward. The list is then in order of role_rank. e.g. goalkeeper
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
team_id
string
query
Only the players of one club. e.g.
tm_3C40GEH
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[].role_rank
integer
The player's place among players in the same role.
data[].player_id
string
Our id for the player. Stable: what you store today still resolves later.
data[].player_name
string
The player's name.
data[].role
string
goalkeeper, defender, midfielder or forward: where the player played most of his minutes.
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[].starts
integer
Matches started.
data[].minutes
integer
Minutes played.
data[].goals
integer
Goals scored.
data[].assists
integer
Goals set up.
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/players?role=goalkeeper&country=Spain&league_id=lg_24T9Z0G" \ -H "X-API-Key: $FSAPI_KEY"
const res = await fetch("https://api.footballsoccerapi.com/v1/rankings/players?role=goalkeeper&country=Spain&league_id=lg_24T9Z0G", { 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/players?role=goalkeeper&country=Spain&league_id=lg_24T9Z0G", headers={"X-API-Key": os.environ["FSAPI_KEY"]}, ) data = r.json()["data"]
$ch = curl_init("https://api.footballsoccerapi.com/v1/rankings/players?role=goalkeeper&country=Spain&league_id=lg_24T9Z0G"); 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,
"role_rank": 1,
"player_id": "pl_0BSP9DP",
"player_name": "H. Kane",
"role": "forward",
"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": 50,
"starts": 42,
"minutes": 3946,
"goals": 51,
"assists": 11,
"last_played": "2026-10-25T16:30:00Z"
},
{
"position": 2,
"rank": 2,
"role_rank": 1,
"player_id": "pl_051NQ4E",
"player_name": "M. Olise",
"role": "midfielder",
"team_id": "tm_234PN5V",
"team_name": "Bayern München",
"country_name": "Germany",
"league_id": "lg_0S9M0P4",
"league_name": "Bundesliga",
"score": 99.7,
"rank_week_ago": null,
"places_moved_week": null,
"rank_year_ago": null,
"matches": 51,
"starts": 41,
"minutes": 3903,
"goals": 28,
"assists": 27,
"last_played": "2026-10-28T19:45:00Z"
}
],
"meta": {
"data_as_of": "2026-10-29T04:32:57Z",
"request_id": "01J9QW3C7M4KX2VB",
"count": 2,
"page": 1,
"per_page": 50,
"total": 15832,
"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.