> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sportsapipro.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Top Competitors
> Get top teams/clubs sorted by popularity
## 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 based on 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
```bash cURL theme={null}
curl -X GET "https://v1.football.sportsapipro.com/competitors/top?limit=10&sports=1" \
-H "x-api-key: YOUR_API_KEY"
```
```javascript JavaScript theme={null}
const response = await fetch(
"https://v1.football.sportsapipro.com/competitors/top?limit=10&sports=1",
{
headers: { "x-api-key": "YOUR_API_KEY" }
}
);
const data = await response.json();
```
```python Python theme={null}
import requests
response = requests.get(
"https://v1.football.sportsapipro.com/competitors/top",
params={"limit": 10, "sports": 1, "withSeasons": "true"},
headers={"x-api-key": "YOUR_API_KEY"}
)
data = response.json()
```
## Response
```json theme={null}
{
"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
```
## OpenAPI
````yaml GET /competitors/top
openapi: 3.1.0
info:
title: SportsAPI Pro - Basketball API
description: >-
Professional basketball data API providing live scores, standings, player
statistics, betting odds, and more for NBA, EuroLeague, and 50+ leagues
worldwide.
version: 1.0.0
contact:
name: SportsAPI Pro Support
email: support@sportsapipro.com
servers:
- url: https://v1.basketball.sportsapipro.com
description: Production API Server
security:
- ApiKeyAuth: []
tags:
- name: Games
description: Live scores, fixtures, and game data
- name: Competitions
description: Leagues and tournaments
- name: Standings
description: League standings and rankings
- name: Athletes
description: Player statistics and data
- name: Betting
description: Betting lines, props, and predictions
- name: Search
description: Search entities
- name: Account
description: Account status and usage
paths:
/competitors/top:
get:
tags:
- Competitions
summary: Top Teams
description: Get top basketball teams
operationId: getTopCompetitors
responses:
'200':
description: Top teams retrieved successfully
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: Your SportsAPI Pro API key
````