> ## 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.

# List Competitions

> Get all competitions and countries

## Endpoint

```
GET https://api.sportsapipro.com/v1/football/competitions
```

## Description

Returns a comprehensive list of all available competitions (leagues, cups, tournaments) along with all countries. This is the primary endpoint for discovering available football data.

<Warning>
  When filtering by `competitionIds`, the response may include additional related competitions beyond those requested. Always filter the `competitions` array by the specific ID you need:

  ```javascript theme={null}
  const targetCompetition = data.competitions.find(c => c.id === competitionId);
  ```
</Warning>

## Parameters

| Parameter      | Type   | Required | Default | Description                                                                        |
| -------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------- |
| `sports`       | number | No       | 1       | Sport ID (1 = Football)                                                            |
| `timezoneName` | string | No       | Auto    | Timezone for date/time values (auto-resolved, or specify e.g., `America/New_York`) |

<Note>
  Parameters like `appTypeId`, `langId`, `timezoneName`, and `userCountryId` are automatically resolved. You can override `timezoneName` to receive date/time values in a specific timezone.
</Note>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.sportsapipro.com/v1/football/competitions?sports=1" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.sportsapipro.com/v1/football/competitions?sports=1",
    {
      headers: { "x-api-key": "YOUR_API_KEY" }
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.sportsapipro.com/v1/football/competitions",
      params={"sports": 1},
      headers={"x-api-key": "YOUR_API_KEY"}
  )
  data = response.json()
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "lastUpdateId": 5493716652,
  "requestedUpdateId": -1,
  "ttl": 300,
  "sports": [
    {
      "id": 1,
      "name": "Football",
      "nameForURL": "football",
      "drawSupport": true,
      "imageVersion": 1
    }
  ],
  "countries": [
    {
      "id": 1,
      "name": "England",
      "totalGames": 23,
      "liveGames": 0,
      "nameForURL": "england",
      "imageVersion": 1
    },
    {
      "id": 2,
      "name": "Spain",
      "totalGames": 12,
      "liveGames": 0,
      "nameForURL": "spain",
      "imageVersion": 1
    }
  ],
  "competitions": [
    {
      "id": 7,
      "countryId": 1,
      "sportId": 1,
      "name": "Premier League",
      "longName": "English Premier League",
      "hasStandings": true,
      "hasBrackets": false,
      "hasStats": true,
      "hasTransfers": true,
      "totalGames": 10,
      "liveGames": 0,
      "nameForURL": "premier-league",
      "popularityRank": 500000000,
      "currentSeasonNum": 35,
      "currentStageNum": 1,
      "color": "#3D195B",
      "imageVersion": 5,
      "isActive": true
    }
  ]
}
```

## Country Object

| Field             | Type    | Description                             |
| ----------------- | ------- | --------------------------------------- |
| `id`              | number  | Unique country identifier               |
| `name`            | string  | Country name                            |
| `totalGames`      | number  | Total games today in this country       |
| `liveGames`       | number  | Currently live games                    |
| `nameForURL`      | string  | URL-friendly name                       |
| `imageVersion`    | number  | Image version for cache busting         |
| `isInternational` | boolean | Whether this is an international entity |

## Competition Object

| Field              | Type    | Description                             |
| ------------------ | ------- | --------------------------------------- |
| `id`               | number  | Unique competition identifier           |
| `countryId`        | number  | Associated country ID                   |
| `sportId`          | number  | Sport ID (1 = Football)                 |
| `name`             | string  | Competition name                        |
| `longName`         | string  | Full competition name                   |
| `hasStandings`     | boolean | Whether standings are available         |
| `hasBrackets`      | boolean | Whether brackets are available (cups)   |
| `hasStats`         | boolean | Whether statistics are available        |
| `totalGames`       | number  | Total games today                       |
| `liveGames`        | number  | Currently live games                    |
| `currentSeasonNum` | number  | Current season number                   |
| `color`            | string  | Brand color (hex)                       |
| `imageVersion`     | number  | Image version for logos                 |
| `isActive`         | boolean | Whether competition is currently active |

## Images

### Country Flag

```
https://api.sportsapipro.com/v1/football/images/countries/{countryId}?imageVersion={imageVersion}
```

### Competition Logo

```
https://api.sportsapipro.com/v1/football/images/competitions/{competitionId}?imageVersion={imageVersion}
```


## OpenAPI

````yaml GET /competitions
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://api.sportsapipro.com/v1/basketball
    description: Path-based front door (recommended)
  - url: https://v1.basketball.sportsapipro.com
    description: Classic per-sport vanity host
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:
    get:
      tags:
        - Competitions
      summary: List Competitions
      description: Get all basketball competitions (leagues, cups, tournaments)
      operationId: listCompetitions
      parameters:
        - name: countryId
          in: query
          description: Filter by country ID
          schema:
            type: integer
      responses:
        '200':
          description: Competitions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  competitions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Competition'
components:
  schemas:
    Competition:
      type: object
      properties:
        id:
          type: integer
          description: Competition ID
        name:
          type: string
          description: Competition name
        country:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
        hasStandings:
          type: boolean
        hasBrackets:
          type: boolean
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your SportsAPI Pro API key

````