Top Competitors

Get top teams/clubs sorted by popularity

GET /competitors/top

Top Teams

cURL

curl --request GET \
  --url https://v1.basketball.sportsapipro.com/competitors/top \
  --header 'x-api-key: <api-key>'

Endpoint

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

Description

Returns the top competitors (teams/clubs) sorted by popularity, along with related sports and countries data. Useful for featuring popular teams on dashboards and navigation.

Parameters

Parameter	Type	Description
limit	number	Number of top competitors to return (e.g., 10, 20, 50)
sports	number	Filter by sport ID (e.g., 1 for Football)
withSeasons	boolean	Include season information for each competitor
isDashboard	boolean	Optimize response for dashboard display
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 by the upstream service based on the request context. You can override timezoneName with a specific timezone (e.g., America/New_York). All date/time fields use ISO 8601 format with a dynamic timezone offset.

Request

cURL

curl -X GET "https://v1.football.sportsapipro.com/competitors/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
    }
  ],
  "countries": [
    {
      "id": 1,
      "name": "England",
      "nameForURL": "england",
      "sportTypes": [1, 9, 11],
      "imageVersion": 1,
      "isInternational": false
    },
    {
      "id": 2,
      "name": "Spain",
      "nameForURL": "spain",
      "sportTypes": [1, 2, 5, 8, 9],
      "imageVersion": 1,
      "isInternational": false
    }
  ],
  "competitors": [
    {
      "id": 132,
      "countryId": 2,
      "sportId": 1,
      "name": "FC Barcelona",
      "shortName": "Barcelona",
      "symbolicName": "BAR",
      "nameForURL": "fc-barcelona",
      "type": 1,
      "popularityRank": 77506,
      "imageVersion": 3,
      "color": "#282E60",
      "awayColor": "#E2CFA5",
      "mainCompetitionId": 11,
      "hasSquad": true,
      "hasTransfers": false,
      "competitorNum": 0,
      "hideOnSearch": false,
      "hideOnCatalog": false
    },
    {
      "id": 131,
      "countryId": 2,
      "sportId": 1,
      "name": "Real Madrid",
      "symbolicName": "RMA",
      "nameForURL": "real-madrid",
      "type": 1,
      "popularityRank": 82570,
      "imageVersion": 4,
      "color": "#FFFFFF",
      "awayColor": "#464E69",
      "mainCompetitionId": 11,
      "hasSquad": true,
      "hasTransfers": false,
      "competitorNum": 0,
      "hideOnSearch": false,
      "hideOnCatalog": false
    }
  ]
}

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 competitors
countries	array	List of countries referenced by competitors
competitors	array	List of top competitors sorted by popularity

Competitor Object

Field	Type	Description
id	number	Unique competitor identifier
countryId	number	ID of the country the competitor belongs to
sportId	number	ID of the sport (1 = Football)
name	string	Full competitor name
shortName	string	Abbreviated display name (e.g., “Barcelona”, “Man Utd”)
longName	string	Extended official name
symbolicName	string	3-letter code (e.g., “BAR”, “RMA”, “MUN”)
nameForURL	string	URL-friendly competitor name
type	number	Competitor type (1 = club, 2 = national team)
popularityRank	number	Popularity score (higher = more popular)
imageVersion	number	Version number for competitor logo assets
color	string	Primary brand color in hex format
awayColor	string	Away kit/secondary color in hex format
mainCompetitionId	number	Primary competition ID (e.g., domestic league)
hasSquad	boolean	Whether squad/roster data is available
hasTransfers	boolean	Whether transfer data is available
competitorNum	number	Internal competitor number
hideOnSearch	boolean	Whether hidden from search results
hideOnCatalog	boolean	Whether hidden from main catalog

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

Competitor Types

Type	Description
1	Club/Team (e.g., FC Barcelona, Manchester United)
2	National Team (e.g., Spain, England)

Top Football Clubs

Club	Country	ID	Competition
FC Barcelona	Spain	132	LaLiga
Real Madrid	Spain	131	LaLiga
Manchester United	England	105	Premier League
Chelsea	England	106	Premier League
Manchester City	England	110	Premier League
Liverpool	England	108	Premier League
Arsenal	England	104	Premier League
Bayern Munich	Germany	331	Bundesliga
Juventus	Italy	226	Serie A
PSG	France	480	Ligue 1

Competitor Images

Competitor logos can be accessed via the images proxy:

https://v1.football.sportsapipro.com/images/competitors/{id}?version={imageVersion}

Example:

https://v1.football.sportsapipro.com/images/competitors/132?version=3

Authorizations

x-api-key · string · header · required

Your SportsAPI Pro API key

Response

200

Top teams retrieved successfully