Rankings

GET /v1/rankings

Every active team by rating, or one competition's

Every team that played in the last year, strongest first, by the same rating as /v1/teams/{id}/rating. With league_id, only the teams that played in that competition in the last year, so a league's pecking order is one call.

Plan

This endpoint needs 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

league_id string query

Restrict to one competition. Ids come from /v1/leagues: 39 is the English Premier League, 62 is Ligue 2. e.g. lg_24T9Z0G

min_matches integer query

Leave out teams rated on fewer matches than this. Defaults to 20. e.g. 50

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–1000. Defaults to 100. e.g. 100

Returns

data.match_id string

Our id for the match. Stable: what you store today still resolves later.

data.league_id string

Our id for the competition.

data.country_name string

The country the competition belongs to.

data.league_name string

The competition's name.

data.season_start_year integer

The year the season starts in: 2026 for 2026/27.

data.kickoff_utc integer

Kickoff, as a UTC timestamp.

data.kickoff_date string

The kickoff date in UTC, YYYY-MM-DD.

data.kickoff_local_time string

The kickoff time where the match is played, HH:MM.

data.match_status string

Where the match stands: scheduled, in play by half, half time, finished, postponed, cancelled, abandoned, awarded or walkover.

data.home_team_id string

Our id for the home side.

data.home_team_name string

The home side's name.

data.away_team_id string

Our id for the away side.

data.away_team_name string

The away side's name.

data.home_goals integer

The home side's goals: the final score, after extra time where played.

data.away_goals integer

The away side's goals: the final score, after extra time where played.

data.full_time_result empty in this example

home, draw or away, on the final score.

data.half_time_home_goals integer

The home side's goals at half time.

data.half_time_away_goals integer

The away side's goals at half time.

data.half_time_result string

home, draw or away at half time.

data.half_time_source string

Half time source.

data.stoppage_minutes empty in this example

Stoppage time added, in minutes.

data.is_kickoff_rescheduled boolean

Whether the kickoff was moved from its first date or time.

data.home_league_position integer

The home side's place in the table before the match.

data.away_league_position integer

The away side's place in the table before the match.

data.away_travel_km integer

How far the away side travelled, in kilometres.

data.venue_name string

The ground the match was played at.

data.city_name string

The town or city of the ground.

data.latitude number

The ground's latitude.

data.longitude number

The ground's longitude.

data.location_precision string

How exact the ground's position is: the ground itself, or only its town.

data.daylight_minutes integer

Minutes of daylight left at kickoff; negative after dark.

data.sun_elevation_deg number

The sun's height above the horizon at kickoff, in degrees.

data.public_holiday empty in this example

Public holiday.

data.referee_name string

The referee.

data.regular_time_home_goals empty in this example

The home side's goals after 90 minutes.

data.regular_time_away_goals empty in this example

The away side's goals after 90 minutes.

data.regular_time_result empty in this example

home, draw or away after 90 minutes: the result prices settle on.

data.extra_time_home_goals empty in this example

The home side's goals in extra time alone.

data.extra_time_away_goals empty in this example

The away side's goals in extra time alone.

data.shootout_home_goals empty in this example

The home side's penalties scored in the shootout.

data.shootout_away_goals empty in this example

The away side's penalties scored in the shootout.

data.betfair object

Betfair.

data.betfair.home_kickoff_price number

The price for a home win at kickoff, as decimal odds.

data.betfair.draw_kickoff_price number

The price for the draw at kickoff, as decimal odds.

data.betfair.away_kickoff_price number

The price for an away win at kickoff, as decimal odds.

data.betfair.home_half_time_price empty in this example

Home half time price.

data.betfair.matched_kickoff_volume empty in this example

Matched kickoff volume.

data.betfair.market_id empty in this example

Market: our id, stable.

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.

Request

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

const res = await fetch("https://api.footballsoccerapi.com/v1/rankings?league_id=lg_24T9Z0G&min_matches=50&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?league_id=lg_24T9Z0G&min_matches=50&page=2",
    headers={"X-API-Key": os.environ["FSAPI_KEY"]},
)
data = r.json()["data"]

$ch = curl_init("https://api.footballsoccerapi.com/v1/rankings?league_id=lg_24T9Z0G&min_matches=50&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": {
        "match_id": "mt_28QVFGW",
        "league_id": "lg_3JZKJSZ",
        "country_name": "Colombia",
        "league_name": "Primera A",
        "season_start_year": 2026,
        "kickoff_utc": 1793228400,
        "kickoff_date": "2026-10-28",
        "kickoff_local_time": "23:00",
        "match_status": "finished",
        "home_team_id": "tm_1HXBKY8",
        "home_team_name": "Once Caldas",
        "away_team_id": "tm_2DNYS20",
        "away_team_name": "Alianza Valledupar",
        "home_goals": 1,
        "away_goals": 0,
        "full_time_result": null,
        "half_time_home_goals": 0,
        "half_time_away_goals": 0,
        "half_time_result": "draw",
        "half_time_source": "feed",
        "stoppage_minutes": null,
        "is_kickoff_rescheduled": false,
        "home_league_position": 7,
        "away_league_position": 16,
        "away_travel_km": 650,
        "venue_name": "Estadio Palogrande",
        "city_name": "Manizales",
        "latitude": 5.056233,
        "longitude": -75.489807,
        "location_precision": "ground",
        "daylight_minutes": 717,
        "sun_elevation_deg": -4.6,
        "public_holiday": null,
        "referee_name": "Carlos Alberto Diaz Vargas",
        "regular_time_home_goals": null,
        "regular_time_away_goals": null,
        "regular_time_result": null,
        "extra_time_home_goals": null,
        "extra_time_away_goals": null,
        "shootout_home_goals": null,
        "shootout_away_goals": null,
        "betfair": {
            "home_kickoff_price": 1.58,
            "draw_kickoff_price": 3.7,
            "away_kickoff_price": 6.25,
            "home_half_time_price": null,
            "matched_kickoff_volume": null,
            "market_id": null
        }
    },
    "meta": {
        "data_as_of": "2026-10-29T04:32:57Z",
        "request_id": "01J9QW3C7M4KX2VB"
    }
}

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

league_id min_matches page limit

GET

← All endpoints Get a free key →