Top Competitions

Get top competitions sorted by popularity with related sports and countries

GET /competitions/top

Top Competitions

cURL

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

Parameter	Type	Description
limit	number	Number of top competitions to return (e.g., 10, 20, 50). Default: 100
sports	number	Filter by sport ID (e.g., 1 for Football, 2 for Basketball)
appTypeId	number	Client application type identifier (auto-resolved)
langId	number	Language identifier (auto-resolved)
timezoneName	string	Timezone for date/time values (auto-resolved, or specify e.g., America/New_York)
userCountryId	number	User’s country for localization (auto-resolved)

Parameters marked as “auto-resolved” are automatically determined based on request context. You don’t need to provide default values.

Request

cURL

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

Field	Type	Description
lastUpdateId	number	Internal versioning ID for incremental updates
requestedUpdateId	number	The update ID requested (-1 means latest)
ttl	number	Cache time-to-live in seconds (typically 300)
sports	array	List of sports referenced by competitions
countries	array	List of countries referenced by competitions
competitions	array	List of top competitions sorted by popularity

Sport Object

Field	Type	Description
id	number	Unique sport identifier
name	string	Sport display name
nameForURL	string	URL-friendly sport name
drawSupport	boolean	Whether the sport supports draw results
imageVersion	number	Version number for sport image assets

Country Object

Field	Type	Description
id	number	Unique country identifier
name	string	Country display name
nameForURL	string	URL-friendly country name
sportTypes	array	Array of sport IDs available in this country
imageVersion	number	Version number for country flag assets
isInternational	boolean	Whether this is an international/continental region

Competition Object

Field	Type	Description
id	number	Unique competition identifier
countryId	number	ID of the country hosting the competition
sportId	number	ID of the sport (1 = Football)
name	string	Competition display name
shortName	string	Abbreviated name (e.g., “EPL”, “UCL”)
longName	string	Full competition name
nameForURL	string	URL-friendly competition name
popularityRank	number	Popularity score (higher = more popular)
color	string	Brand color in hex format
imageVersion	number	Version number for competition logo
currentSeasonNum	number	Current season number
currentStageNum	number	Current stage number
currentPhaseName	string	Name of current phase (e.g., “Regular Season”)
hasStandings	boolean	Whether standings/table data is available
hasBrackets	boolean	Whether bracket/knockout data is available
hasStats	boolean	Whether statistics are available
hasTransfers	boolean	Whether transfer data is available
hasLiveStandings	boolean	Whether live standings updates are available
hasStandingsGroups	boolean	Whether standings have group stages
hasBets	boolean	Whether betting data is available
hasCurrentStageStandings	boolean	Whether current stage has standings
hasHistory	boolean	Whether historical data is available
tableName	string	Display name for standings table
bracketsName	string	Display name for brackets view
competitorsType	number	Type of competitors (1 = clubs)
hideOnCatalog	boolean	Whether hidden from main catalog
hideOnSearch	boolean	Whether hidden from search
isActive	boolean	Whether competition is currently active
createdAt	string	ISO timestamp when competition was added

Typical Top Football Competitions

Competition	Country	ID
Premier League	England	7
LaLiga	Spain	11
Serie A	Italy	17
Bundesliga	Germany	25
UEFA Champions League	Europe	572
UEFA Conference League	Europe	7685
Copa del Rey	Spain	13
EFL Cup	England	9
CONMEBOL Libertadores	South America	102

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