TheSportsDB Search API

openapi: 3.0.1
info:
  title: TheSportsDB API
  description: >-
    REST API for TheSportsDB, an open, crowd-sourced database of sports artwork
    and metadata. The V1 API returns JSON for searches, lookups, leagues, players,
    teams, events, schedules, and video highlights, with the API key supplied as
    a path segment. The free test key is "3" (also documented as "123"). Premium
    V2 endpoints (livescores) authenticate with an API key in the X-API-KEY header.
  termsOfService: https://www.thesportsdb.com/
  contact:
    name: TheSportsDB
    url: https://www.thesportsdb.com/documentation
  version: '1.0'
servers:
  - url: https://www.thesportsdb.com/api/v1/json
    description: V1 REST API; append the API key as the next path segment (e.g. /3/).
paths:
  /{apiKey}/searchteams.php:
    get:
      operationId: searchTeams
      tags:
        - Search
      summary: Search for teams by name.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: t
          in: query
          required: true
          description: Team name to search for.
          schema:
            type: string
            example: Arsenal
      responses:
        '200':
          description: Matching teams.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/searchplayers.php:
    get:
      operationId: searchPlayers
      tags:
        - Search
      summary: Search for players by name.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: p
          in: query
          required: true
          description: Player name to search for.
          schema:
            type: string
            example: Danny Welbeck
      responses:
        '200':
          description: Matching players.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/searchevents.php:
    get:
      operationId: searchEvents
      tags:
        - Search
      summary: Search for events by name.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: e
          in: query
          required: true
          description: Event name to search for.
          schema:
            type: string
            example: Arsenal_vs_Chelsea
        - name: s
          in: query
          required: false
          description: Season filter.
          schema:
            type: string
            example: '2016-2017'
      responses:
        '200':
          description: Matching events.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/searchvenues.php:
    get:
      operationId: searchVenues
      tags:
        - Search
      summary: Search for venues by name.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: v
          in: query
          required: true
          description: Venue name to search for.
          schema:
            type: string
            example: Wembley
      responses:
        '200':
          description: Matching venues.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/lookupleague.php:
    get:
      operationId: lookupLeague
      tags:
        - Lookup
      summary: Look up league details by league ID.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: id
          in: query
          required: true
          description: League ID (idLeague).
          schema:
            type: string
            example: '4328'
      responses:
        '200':
          description: League details.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/lookupteam.php:
    get:
      operationId: lookupTeam
      tags:
        - Lookup
      summary: Look up team details by team ID.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: id
          in: query
          required: true
          description: Team ID (idTeam).
          schema:
            type: string
            example: '133604'
      responses:
        '200':
          description: Team details.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/lookupplayer.php:
    get:
      operationId: lookupPlayer
      tags:
        - Lookup
      summary: Look up player details by player ID.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: id
          in: query
          required: true
          description: Player ID (idPlayer).
          schema:
            type: string
            example: '34145937'
      responses:
        '200':
          description: Player details.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/lookupevent.php:
    get:
      operationId: lookupEvent
      tags:
        - Lookup
      summary: Look up event details by event ID.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: id
          in: query
          required: true
          description: Event ID (idEvent).
          schema:
            type: string
            example: '441613'
      responses:
        '200':
          description: Event details.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/lookupvenue.php:
    get:
      operationId: lookupVenue
      tags:
        - Lookup
      summary: Look up venue details by venue ID.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: id
          in: query
          required: true
          description: Venue ID (idVenue).
          schema:
            type: string
            example: '16163'
      responses:
        '200':
          description: Venue details.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/lookuptable.php:
    get:
      operationId: lookupTable
      tags:
        - Leagues
      summary: Look up the league table (standings) for a league and season.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: l
          in: query
          required: true
          description: League ID (idLeague).
          schema:
            type: string
            example: '4328'
        - name: s
          in: query
          required: true
          description: Season.
          schema:
            type: string
            example: '2020-2021'
      responses:
        '200':
          description: League standings.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/all_sports.php:
    get:
      operationId: allSports
      tags:
        - Leagues
      summary: List all sports.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: List of sports.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/all_countries.php:
    get:
      operationId: allCountries
      tags:
        - Leagues
      summary: List all countries.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: List of countries.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/all_leagues.php:
    get:
      operationId: allLeagues
      tags:
        - Leagues
      summary: List all leagues.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: List of leagues.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/search_all_seasons.php:
    get:
      operationId: searchAllSeasons
      tags:
        - Leagues
      summary: List all seasons for a league.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: id
          in: query
          required: true
          description: League ID (idLeague).
          schema:
            type: string
            example: '4328'
      responses:
        '200':
          description: List of seasons.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/search_all_teams.php:
    get:
      operationId: searchAllTeams
      tags:
        - Teams
      summary: List all teams in a league or by sport and country.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: l
          in: query
          required: false
          description: League name (strLeague).
          schema:
            type: string
            example: English Premier League
        - name: s
          in: query
          required: false
          description: Sport (strSport).
          schema:
            type: string
            example: Soccer
        - name: c
          in: query
          required: false
          description: Country (strCountry).
          schema:
            type: string
            example: Spain
      responses:
        '200':
          description: List of teams.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/lookup_all_players.php:
    get:
      operationId: lookupAllPlayers
      tags:
        - Players
      summary: List all players on a team.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: id
          in: query
          required: true
          description: Team ID (idTeam).
          schema:
            type: string
            example: '133604'
      responses:
        '200':
          description: List of players.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/eventsnext.php:
    get:
      operationId: eventsNext
      tags:
        - Events
      summary: Next five upcoming events for a team.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: id
          in: query
          required: true
          description: Team ID (idTeam).
          schema:
            type: string
            example: '133602'
      responses:
        '200':
          description: Upcoming events.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/eventslast.php:
    get:
      operationId: eventsLast
      tags:
        - Events
      summary: Last five results for a team.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: id
          in: query
          required: true
          description: Team ID (idTeam).
          schema:
            type: string
            example: '133602'
      responses:
        '200':
          description: Recent results.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/eventsday.php:
    get:
      operationId: eventsDay
      tags:
        - Events
      summary: Events on a specific date.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: d
          in: query
          required: true
          description: Date of events (YYYY-MM-DD).
          schema:
            type: string
            format: date
            example: '2014-10-10'
        - name: s
          in: query
          required: false
          description: Sport filter (strSport).
          schema:
            type: string
            example: Soccer
        - name: l
          in: query
          required: false
          description: League ID filter (idLeague).
          schema:
            type: string
            example: '4328'
      responses:
        '200':
          description: Events on the date.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/eventsseason.php:
    get:
      operationId: eventsSeason
      tags:
        - Events
      summary: All events in a season for a league.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: id
          in: query
          required: true
          description: League ID (idLeague).
          schema:
            type: string
            example: '4328'
        - name: s
          in: query
          required: false
          description: Season.
          schema:
            type: string
            example: '2014-2015'
      responses:
        '200':
          description: Season events.
          content:
            application/json:
              schema:
                type: object
  /{apiKey}/eventshighlights.php:
    get:
      operationId: eventsHighlights
      tags:
        - Events
      summary: Video highlights of events by date, league, or sport.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: d
          in: query
          required: false
          description: Date of events (YYYY-MM-DD).
          schema:
            type: string
            format: date
            example: '2023-12-09'
        - name: l
          in: query
          required: false
          description: League ID (idLeague).
          schema:
            type: string
            example: '4328'
        - name: s
          in: query
          required: false
          description: Sport (strSport).
          schema:
            type: string
            example: Soccer
      responses:
        '200':
          description: Event highlights.
          content:
            application/json:
              schema:
                type: object
  /livescore/{strSport}:
    servers:
      - url: https://www.thesportsdb.com/api/v2/json
        description: Premium V2 API; authenticate with the X-API-KEY header.
    get:
      operationId: livescoreBySport
      tags:
        - Livescores
      summary: Premium V2 livescores for a sport, updated every 2 minutes.
      security:
        - ApiKeyHeader: []
      parameters:
        - name: strSport
          in: path
          required: true
          description: Sport name (e.g. Soccer, Basketball).
          schema:
            type: string
            example: Soccer
      responses:
        '200':
          description: Live scores for the sport.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Missing or invalid premium API key.
components:
  parameters:
    ApiKey:
      name: apiKey
      in: path
      required: true
      description: API key path segment. The free test key is "3" (also documented as "123").
      schema:
        type: string
        default: '3'
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Premium V2 API key supplied in the X-API-KEY request header.