Skip to main content
GET
/
competitions
/
top
Top Competitions
curl --request GET \
  --url https://v1.basketball.sportsapipro.com/competitions/top \
  --header 'x-api-key: <api-key>'

​
Endpoint

GET https://v1.football.sportsapipro.com/competitions/top

​
Description

Returns the top competitions sorted by popularity, along with related sports and countries data. Use the limit parameter to control how many competitions are returned.

​
Parameters

ParameterTypeDescription
limitnumberNumber of top competitions to return (e.g., 10, 20, 50). Default: 100
sportsnumberFilter by sport ID (e.g., 1 for Football, 2 for Basketball)
appTypeIdnumberClient application type identifier (auto-resolved)
langIdnumberLanguage identifier (auto-resolved)
timezoneNamestringTimezone for date/time values (auto-resolved, or specify e.g., America/New_York)
userCountryIdnumberUser’s country for localization (auto-resolved)
Parameters marked as “auto-resolved” are automatically determined by the upstream service based on the request context. You don’t need to provide default values.

​
Request

curl -X GET "https://v1.football.sportsapipro.com/competitions/top?limit=10&sports=1" \
  -H "x-api-key: YOUR_API_KEY"

​
Response

{
  "lastUpdateId": 5494749399,
  "requestedUpdateId": -1,
  "ttl": 300,
  "sports": [
    {
      "id": 1,
      "name": "Football",
      "nameForURL": "football",
      "drawSupport": true,
      "imageVersion": 1
    },
    {
      "id": 2,
      "name": "Basketball",
      "nameForURL": "basketball",
      "imageVersion": 1
    }
  ],
  "countries": [
    {
      "id": 1,
      "name": "England",
      "nameForURL": "england",
      "sportTypes": [1, 9, 11],
      "imageVersion": 1,
      "isInternational": false
    },
    {
      "id": 19,
      "name": "Europe",
      "nameForURL": "europe",
      "sportTypes": [1, 2, 4, 5, 6, 7, 8, 9],
      "imageVersion": 1,
      "isInternational": true
    }
  ],
  "competitions": [
    {
      "id": 7,
      "countryId": 1,
      "sportId": 1,
      "name": "Premier League",
      "shortName": "EPL",
      "hasStandings": true,
      "hasBrackets": false,
      "hasStats": true,
      "hasTransfers": true,
      "hasLiveStandings": false,
      "hasStandingsGroups": false,
      "hasBets": false,
      "nameForURL": "premier-league",
      "popularityRank": 92856977,
      "tableName": "Standings",
      "currentSeasonNum": 131,
      "currentStageNum": 1,
      "color": "#075C9C",
      "competitorsType": 1,
      "imageVersion": 12,
      "hideOnCatalog": false,
      "hideOnSearch": false,
      "hasCurrentStageStandings": true,
      "hasHistory": true,
      "isActive": true
    },
    {
      "id": 572,
      "countryId": 19,
      "sportId": 1,
      "name": "UEFA Champions League",
      "shortName": "UCL",
      "hasStandings": true,
      "hasBrackets": true,
      "hasStats": true,
      "hasTransfers": false,
      "nameForURL": "uefa-champions-league",
      "popularityRank": 115687338,
      "tableName": "Standings",
      "bracketsName": "Bracket",
      "currentSeasonNum": 73,
      "currentStageNum": 1,
      "color": "#09123E",
      "imageVersion": 5,
      "hasHistory": true,
      "isActive": true
    }
  ]
}

​
Response Fields

​
Root Level

FieldTypeDescription
lastUpdateIdnumberInternal versioning ID for incremental updates
requestedUpdateIdnumberThe update ID requested (-1 means latest)
ttlnumberCache time-to-live in seconds (typically 300)
sportsarrayList of sports referenced by competitions
countriesarrayList of countries referenced by competitions
competitionsarrayList of top competitions sorted by popularity

​
Sport Object

FieldTypeDescription
idnumberUnique sport identifier
namestringSport display name
nameForURLstringURL-friendly sport name
drawSupportbooleanWhether the sport supports draw results
imageVersionnumberVersion number for sport image assets

​
Country Object

FieldTypeDescription
idnumberUnique country identifier
namestringCountry display name
nameForURLstringURL-friendly country name
sportTypesarrayArray of sport IDs available in this country
imageVersionnumberVersion number for country flag assets
isInternationalbooleanWhether this is an international/continental region

​
Competition Object

FieldTypeDescription
idnumberUnique competition identifier
countryIdnumberID of the country hosting the competition
sportIdnumberID of the sport (1 = Football)
namestringCompetition display name
shortNamestringAbbreviated name (e.g., “EPL”, “UCL”)
longNamestringFull competition name
nameForURLstringURL-friendly competition name
popularityRanknumberPopularity score (higher = more popular)
colorstringBrand color in hex format
imageVersionnumberVersion number for competition logo
currentSeasonNumnumberCurrent season number
currentStageNumnumberCurrent stage number
currentPhaseNamestringName of current phase (e.g., “Regular Season”)
hasStandingsbooleanWhether standings/table data is available
hasBracketsbooleanWhether bracket/knockout data is available
hasStatsbooleanWhether statistics are available
hasTransfersbooleanWhether transfer data is available
hasLiveStandingsbooleanWhether live standings updates are available
hasStandingsGroupsbooleanWhether standings have group stages
hasBetsbooleanWhether betting data is available
hasCurrentStageStandingsbooleanWhether current stage has standings
hasHistorybooleanWhether historical data is available
tableNamestringDisplay name for standings table
bracketsNamestringDisplay name for brackets view
competitorsTypenumberType of competitors (1 = clubs)
hideOnCatalogbooleanWhether hidden from main catalog
hideOnSearchbooleanWhether hidden from search
isActivebooleanWhether competition is currently active
createdAtstringISO timestamp when competition was added

​
Typical Top Football Competitions

CompetitionCountryID
Premier LeagueEngland7
LaLigaSpain11
Serie AItaly17
BundesligaGermany25
UEFA Champions LeagueEurope572
UEFA Conference LeagueEurope7685
Copa del ReySpain13
EFL CupEngland9
CONMEBOL LibertadoresSouth America102

​
Incremental Updates

Use lastUpdateId for efficient polling: 
// Store the lastUpdateId from previous response
let lastUpdateId = null;

async function fetchTopCompetitions() {
  const params = new URLSearchParams({ limit: '10', sports: '1' });
  if (lastUpdateId) {
    params.append('lastUpdateId', lastUpdateId);
  }
  
  const response = await fetch(
    `https://v1.football.sportsapipro.com/competitions/top?${params}`,
    { headers: { "x-api-key": "YOUR_API_KEY" } }
  );
  const data = await response.json();
  
  // Update stored ID for next request
  lastUpdateId = data.lastUpdateId;
  return data;
}

Authorizations

​
x-api-key
string
header
required

Your SportsAPI Pro API key

Response

200

Top competitions retrieved successfully