openapi: 3.1.0
info:
  title: TheSports Football API
  description: >-
    TheSports Football API provides real-time football data feeds covering
    competitions, teams, players, matches, live scores, lineups, statistics,
    standings, and match analysis worldwide. Supports football and soccer
    leagues including major domestic competitions and international tournaments.
  version: '1.0'
  contact:
    url: https://www.thesports.com/
  termsOfService: https://www.thesports.com/
  license:
    name: Commercial
    url: https://www.thesports.com/api
externalDocs:
  description: TheSports Data API Documentation
  url: https://www.thesports.com/docs
servers:
  - url: https://api.thesports.com/v1
    description: TheSports API v1
security:
  - ApiKeyAuth: []
tags:
  - name: Competitions
    description: Football competition and league data
  - name: Teams
    description: Football team information and statistics
  - name: Players
    description: Football player profiles and statistics
  - name: Matches
    description: Football match fixtures, results, and live data
  - name: Standings
    description: League tables and competition standings
  - name: Statistics
    description: Match and player statistics
paths:
  /football/country/list:
    get:
      operationId: listCountries
      summary: List Countries
      description: Returns a list of all countries covered by the API.
      tags:
        - Competitions
      parameters:
        - name: user_key
          in: query
          required: true
          schema:
            type: string
          description: Your API authentication key.
      responses:
        '200':
          description: List of countries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountryListResponse'
  /football/competition/list:
    get:
      operationId: listCompetitions
      summary: List Competitions
      description: Returns all football competitions and leagues.
      tags:
        - Competitions
      parameters:
        - name: user_key
          in: query
          required: true
          schema:
            type: string
          description: Your API authentication key.
        - name: country_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by country ID.
      responses:
        '200':
          description: List of competitions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompetitionListResponse'
  /football/competition/additional:
    get:
      operationId: getCompetitionDetails
      summary: Get Competition Details
      description: Returns detailed information about a specific competition.
      tags:
        - Competitions
      parameters:
        - name: user_key
          in: query
          required: true
          schema:
            type: string
          description: Your API authentication key.
        - name: competition_id
          in: query
          required: true
          schema:
            type: string
          description: The competition ID.
      responses:
        '200':
          description: Competition details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompetitionDetailsResponse'
  /football/team/list:
    get:
      operationId: listTeams
      summary: List Teams
      description: Returns a list of football teams, optionally filtered by competition.
      tags:
        - Teams
      parameters:
        - name: user_key
          in: query
          required: true
          schema:
            type: string
          description: Your API authentication key.
        - name: competition_id
          in: query
          required: false
          schema:
            type: string
          description: Filter teams by competition ID.
      responses:
        '200':
          description: List of teams
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamListResponse'
  /football/team/additional:
    get:
      operationId: getTeamDetails
      summary: Get Team Details
      description: Returns detailed information about a specific team.
      tags:
        - Teams
      parameters:
        - name: user_key
          in: query
          required: true
          schema:
            type: string
          description: Your API authentication key.
        - name: team_id
          in: query
          required: true
          schema:
            type: string
          description: The team ID.
      responses:
        '200':
          description: Team details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamDetailsResponse'
  /football/player/list:
    get:
      operationId: listPlayers
      summary: List Players
      description: Returns a list of players, optionally filtered by team.
      tags:
        - Players
      parameters:
        - name: user_key
          in: query
          required: true
          schema:
            type: string
          description: Your API authentication key.
        - name: team_id
          in: query
          required: false
          schema:
            type: string
          description: Filter players by team ID.
      responses:
        '200':
          description: List of players
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerListResponse'
  /football/player/additional:
    get:
      operationId: getPlayerDetails
      summary: Get Player Details
      description: Returns detailed information and statistics for a specific player.
      tags:
        - Players
      parameters:
        - name: user_key
          in: query
          required: true
          schema:
            type: string
          description: Your API authentication key.
        - name: player_id
          in: query
          required: true
          schema:
            type: string
          description: The player ID.
      responses:
        '200':
          description: Player details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerDetailsResponse'
  /football/match/list:
    get:
      operationId: listMatches
      summary: List Matches
      description: Returns a list of matches for a given date or competition.
      tags:
        - Matches
      parameters:
        - name: user_key
          in: query
          required: true
          schema:
            type: string
          description: Your API authentication key.
        - name: competition_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by competition ID.
        - name: date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filter matches by date (YYYY-MM-DD).
        - name: season_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by season ID.
      responses:
        '200':
          description: List of matches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchListResponse'
  /football/match/recent:
    get:
      operationId: listRecentMatches
      summary: List Recent Matches
      description: Returns recently completed matches.
      tags:
        - Matches
      parameters:
        - name: user_key
          in: query
          required: true
          schema:
            type: string
          description: Your API authentication key.
        - name: competition_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by competition ID.
      responses:
        '200':
          description: Recent matches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchListResponse'
  /football/match/detail:
    get:
      operationId: getMatchDetails
      summary: Get Match Details
      description: Returns detailed information about a specific match including lineups and events.
      tags:
        - Matches
      parameters:
        - name: user_key
          in: query
          required: true
          schema:
            type: string
          description: Your API authentication key.
        - name: match_id
          in: query
          required: true
          schema:
            type: string
          description: The match ID.
      responses:
        '200':
          description: Match details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchDetailsResponse'
  /football/match/lineup:
    get:
      operationId: getMatchLineup
      summary: Get Match Lineup
      description: Returns starting lineup and substitutes for a specific match.
      tags:
        - Matches
      parameters:
        - name: user_key
          in: query
          required: true
          schema:
            type: string
          description: Your API authentication key.
        - name: match_id
          in: query
          required: true
          schema:
            type: string
          description: The match ID.
      responses:
        '200':
          description: Match lineup
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchLineupResponse'
  /football/match/statistics:
    get:
      operationId: getMatchStatistics
      summary: Get Match Statistics
      description: Returns detailed match statistics including possession, shots, and passes.
      tags:
        - Statistics
      parameters:
        - name: user_key
          in: query
          required: true
          schema:
            type: string
          description: Your API authentication key.
        - name: match_id
          in: query
          required: true
          schema:
            type: string
          description: The match ID.
      responses:
        '200':
          description: Match statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchStatisticsResponse'
  /football/standings/list:
    get:
      operationId: getStandings
      summary: Get Standings
      description: Returns the league table/standings for a competition and season.
      tags:
        - Standings
      parameters:
        - name: user_key
          in: query
          required: true
          schema:
            type: string
          description: Your API authentication key.
        - name: competition_id
          in: query
          required: true
          schema:
            type: string
          description: The competition ID.
        - name: season_id
          in: query
          required: false
          schema:
            type: string
          description: The season ID.
      responses:
        '200':
          description: League standings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandingsResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: user_key
      description: API key for authentication, obtained from TheSports developer portal.
  schemas:
    CountryListResponse:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: ok
        results:
          type: object
          properties:
            total:
              type: integer
            data:
              type: array
              items:
                $ref: '#/components/schemas/Country'
    Country:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        logo:
          type: string
    CompetitionListResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        results:
          type: object
          properties:
            total:
              type: integer
            data:
              type: array
              items:
                $ref: '#/components/schemas/Competition'
    Competition:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        short_name:
          type: string
        logo:
          type: string
        country_id:
          type: string
        country_name:
          type: string
        type:
          type: integer
        cur_season_id:
          type: string
        cur_stage_id:
          type: string
    CompetitionDetailsResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        results:
          $ref: '#/components/schemas/Competition'
    TeamListResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        results:
          type: object
          properties:
            total:
              type: integer
            data:
              type: array
              items:
                $ref: '#/components/schemas/Team'
    Team:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        short_name:
          type: string
        logo:
          type: string
        country_id:
          type: string
        competition_id:
          type: string
        venue_id:
          type: string
        manager_id:
          type: string
    TeamDetailsResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        results:
          $ref: '#/components/schemas/Team'
    PlayerListResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        results:
          type: object
          properties:
            total:
              type: integer
            data:
              type: array
              items:
                $ref: '#/components/schemas/Player'
    Player:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        common_name:
          type: string
        logo:
          type: string
        team_id:
          type: string
        country_id:
          type: string
        position:
          type: string
        jersey_number:
          type: integer
        age:
          type: integer
        height:
          type: integer
        weight:
          type: integer
        market_value:
          type: string
    PlayerDetailsResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        results:
          $ref: '#/components/schemas/Player'
    MatchListResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        results:
          type: object
          properties:
            total:
              type: integer
            data:
              type: array
              items:
                $ref: '#/components/schemas/Match'
    Match:
      type: object
      properties:
        id:
          type: string
        competition_id:
          type: string
        season_id:
          type: string
        stage_id:
          type: string
        home_team_id:
          type: string
        away_team_id:
          type: string
        status:
          type: integer
          description: "0=not started, 1=first half, 2=half time, 3=second half, 4=extra time, 5=penalties, -1=finished, -2=postponed, -3=cancelled"
        home_score:
          type: integer
        away_score:
          type: integer
        scheduled:
          type: integer
          description: Unix timestamp of scheduled match time
        venue_id:
          type: string
        referee_id:
          type: string
    MatchDetailsResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        results:
          $ref: '#/components/schemas/Match'
    MatchLineupResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        results:
          type: object
          properties:
            home:
              $ref: '#/components/schemas/TeamLineup'
            away:
              $ref: '#/components/schemas/TeamLineup'
    TeamLineup:
      type: object
      properties:
        formation:
          type: string
        starting:
          type: array
          items:
            $ref: '#/components/schemas/LineupPlayer'
        substitutes:
          type: array
          items:
            $ref: '#/components/schemas/LineupPlayer'
    LineupPlayer:
      type: object
      properties:
        player_id:
          type: string
        player_name:
          type: string
        position:
          type: string
        jersey_number:
          type: integer
    MatchStatisticsResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        results:
          type: object
          properties:
            home:
              $ref: '#/components/schemas/MatchStats'
            away:
              $ref: '#/components/schemas/MatchStats'
    MatchStats:
      type: object
      properties:
        possession:
          type: integer
        shots:
          type: integer
        shots_on_target:
          type: integer
        corners:
          type: integer
        fouls:
          type: integer
        yellow_cards:
          type: integer
        red_cards:
          type: integer
        offsides:
          type: integer
        passes:
          type: integer
        pass_accuracy:
          type: integer
    StandingsResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/StandingEntry'
    StandingEntry:
      type: object
      properties:
        team_id:
          type: string
        team_name:
          type: string
        position:
          type: integer
        played:
          type: integer
        won:
          type: integer
        drawn:
          type: integer
        lost:
          type: integer
        goals_for:
          type: integer
        goals_against:
          type: integer
        goal_difference:
          type: integer
        points:
          type: integer