> ## 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 Competitions
> Get top competitions sorted by popularity with related sports and countries
## 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
```bash cURL theme={null}
curl -X GET "https://v1.football.sportsapipro.com/competitions/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/competitions/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/competitions/top",
params={"limit": 10, "sports": 1},
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
},
{
"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:
```javascript theme={null}
// 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;
}
```
## OpenAPI
````yaml GET /competitions/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:
/competitions/top:
get:
tags:
- Competitions
summary: Top Competitions
description: Get the most popular basketball competitions
operationId: getTopCompetitions
responses:
'200':
description: Top competitions retrieved successfully
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: Your SportsAPI Pro API key
````