api-ninjas-com Sports API

openapi: 3.2.0
info:
  title: Ninjas Sports API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Sports
  description: 'All-sports endpoints: schedules, live and final scores, standings, teams and rosters for any league of any sport. Each sport also has its own API (Football (Soccer), American Football, Basketball, Hockey, Baseball) with the same fields. Leagues: the NFL, NBA, WNBA, NHL, MLB and soccer (Premier League, La Liga, Bundesliga, Serie A, Ligue 1, UEFA Champions League, UEFA Europa League and MLS). The free plan covers the current season and masks scores, period and clock of games in progress; paid plans get live data and the three previous seasons; the Business tier and above gets the full season archive.'
paths:
  /v1/sportsgames:
    get:
      summary: Get schedules, live scores and final scores
      description: Returns games (fixtures) for one day, a team's season, a season (50 games per page; use offset, or limit on paid plans) or one game id. With only league, returns today's games in the league's home time zone.
      operationId: getSportsGames
      parameters:
      - name: league
        in: query
        required: false
        description: nfl, nba, wnba, nhl, mlb, epl (Premier League), laliga, bundesliga, seriea, ligue1, ucl (UEFA Champions League), uel (UEFA Europa League) or mls. Required unless game_id or a team id is given.
        schema:
          type: string
          example: nba
          enum:
          - nfl
          - nba
          - wnba
          - nhl
          - mlb
          - epl
          - laliga
          - bundesliga
          - seriea
          - ligue1
          - ucl
          - uel
          - mls
      - name: date
        in: query
        required: false
        description: 'Game day in the league''s home time zone (YYYY-MM-DD): US Eastern for the US leagues and MLS, UK time for the Premier League, Central European time for the other European competitions.'
        schema:
          type: string
          example: '2026-10-22'
      - name: team
        in: query
        required: false
        description: 'Team id, abbreviation or name: that team''s games in the season.'
        schema:
          type: string
          example: BOS
      - name: season
        in: query
        required: false
        description: Season as the year it starts (2026 = 2026-27 for seasons that span two years). Defaults to the current season.
        schema:
          type: integer
          example: 2026
      - name: season_type
        in: query
        required: false
        description: Only this part of the season.
        schema:
          type: string
          enum:
          - preseason
          - regular
          - cup_final
          - play_in
          - postseason
          - group_stage
          - league_phase
          - knockout
      - name: status
        in: query
        required: false
        description: Only games with this status.
        schema:
          type: string
          enum:
          - scheduled
          - in_progress
          - final
          - postponed
          - canceled
          - suspended
          - delayed
      - name: game_id
        in: query
        required: false
        description: Return one game.
        schema:
          type: string
          example: nba-20261022-cle-phi
      - name: limit
        in: query
        required: false
        description: Results per page (1-500). Premium only. Default 50.
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        description: Results to skip, for paging.
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SportsGame'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SportsError'
      security:
      - ApiKeyAuth: []
      tags:
      - Sports
  /v1/sportsstandings:
    get:
      summary: Get league standings
      description: Returns the league table for a season, ordered by league rank, or by conference or division rank when filtered.
      operationId: getSportsStandings
      parameters:
      - name: league
        in: query
        required: true
        description: nfl, nba, wnba, nhl, mlb, epl (Premier League), laliga, bundesliga, seriea, ligue1, ucl (UEFA Champions League), uel (UEFA Europa League) or mls.
        schema:
          type: string
          example: nhl
          enum:
          - nfl
          - nba
          - wnba
          - nhl
          - mlb
          - epl
          - laliga
          - bundesliga
          - seriea
          - ligue1
          - ucl
          - uel
          - mls
      - name: season
        in: query
        required: false
        description: Season as the year it starts. Defaults to the current season.
        schema:
          type: integer
          example: 2026
      - name: conference
        in: query
        required: false
        description: Only this conference, e.g. AFC, Eastern or AL.
        schema:
          type: string
      - name: division
        in: query
        required: false
        description: Only this division, e.g. AFC East, Atlantic or NL West.
        schema:
          type: string
          example: Atlantic
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SportsStanding'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SportsError'
      security:
      - ApiKeyAuth: []
      tags:
      - Sports
  /v1/sportsteams:
    get:
      summary: List teams
      description: Lists teams and soccer clubs with league, sport and home venue, plus conference and division (US leagues) or country (soccer clubs).
      operationId: listSportsTeams
      parameters:
      - name: league
        in: query
        required: false
        description: Only this league; every league when absent.
        schema:
          type: string
          example: nba
          enum:
          - nfl
          - nba
          - wnba
          - nhl
          - mlb
          - epl
          - laliga
          - bundesliga
          - seriea
          - ligue1
          - ucl
          - uel
          - mls
      - name: sport
        in: query
        required: false
        description: Only teams of this sport.
        schema:
          type: string
          enum:
          - american_football
          - basketball
          - ice_hockey
          - baseball
          - soccer
      - name: team
        in: query
        required: false
        description: 'Team id, abbreviation or name: one team.'
        schema:
          type: string
          example: BOS
      - name: conference
        in: query
        required: false
        description: Only teams in this conference.
        schema:
          type: string
      - name: division
        in: query
        required: false
        description: Only teams in this division.
        schema:
          type: string
      - name: active
        in: query
        required: false
        description: false lists former teams that appear in past seasons.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SportsTeam'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SportsError'
      security:
      - ApiKeyAuth: []
      tags:
      - Sports
  /v1/sportsplayers:
    get:
      summary: Get rosters and player profiles
      description: Returns current rosters and player profiles. Provide league with team or name, or a player_id.
      operationId: getSportsPlayers
      parameters:
      - name: league
        in: query
        required: false
        description: nfl, nba, wnba, nhl, mlb, epl (Premier League), laliga, bundesliga, seriea, ligue1, ucl (UEFA Champions League), uel (UEFA Europa League) or mls.
        schema:
          type: string
          example: nba
          enum:
          - nfl
          - nba
          - wnba
          - nhl
          - mlb
          - epl
          - laliga
          - bundesliga
          - seriea
          - ligue1
          - ucl
          - uel
          - mls
      - name: team
        in: query
        required: false
        description: 'Team id, abbreviation or name: the team''s current roster.'
        schema:
          type: string
          example: BOS
      - name: name
        in: query
        required: false
        description: Full or partial player name (case and accent insensitive).
        schema:
          type: string
      - name: player_id
        in: query
        required: false
        description: Return one player.
        schema:
          type: string
      - name: position
        in: query
        required: false
        description: Only this position, e.g. QB, G, C, SS or F.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Results per page (1-500). Premium only. Default 50.
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        description: Results to skip, for paging.
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SportsPlayer'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SportsError'
      security:
      - ApiKeyAuth: []
      tags:
      - Sports
components:
  schemas:
    SportsError:
      type: object
      properties:
        error:
          type: string
    SportsPlayer:
      type: object
      properties:
        player_id:
          type: string
          example: nba-p-8f12176c56
          description: Permanent id; soccer player ids (soccer-p-...) are the same in every league.
        league:
          type: string
          enum:
          - nfl
          - nba
          - wnba
          - nhl
          - mlb
          - epl
          - laliga
          - bundesliga
          - seriea
          - ligue1
          - ucl
          - uel
          - mls
        team:
          allOf:
          - $ref: '#/components/schemas/SportsTeamRef'
        name:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        position:
          type: string
        jersey_number:
          type:
          - string
          - 'null'
        height_in:
          type:
          - integer
          - 'null'
        height_cm:
          type:
          - integer
          - 'null'
        weight_lb:
          type:
          - integer
          - 'null'
        weight_kg:
          type:
          - integer
          - 'null'
        birth_date:
          type:
          - string
          - 'null'
          format: date
        birth_place:
          type:
          - object
          - 'null'
          properties:
            city:
              type:
              - string
              - 'null'
            state:
              type:
              - string
              - 'null'
            country:
              type:
              - string
              - 'null'
        roster_status:
          type: string
          example: active
        college:
          type: string
          description: US leagues
        experience_years:
          type: integer
          description: US leagues
        shoots_catches:
          type: string
          description: NHL
          enum:
          - L
          - R
        nationality:
          type: string
          description: Soccer
    SportsTeam:
      type: object
      properties:
        team_id:
          type: string
          example: nba-bos
          description: nba-bos, or a soccer club id such as soccer-arsenal, the same in every competition.
        league:
          type:
          - string
          - 'null'
          enum:
          - nfl
          - nba
          - wnba
          - nhl
          - mlb
          - epl
          - laliga
          - bundesliga
          - seriea
          - ligue1
          - ucl
          - uel
          - mls
          - null
          description: The team's league; for a soccer club its domestic league, or null for a club from another country's league seen in the UEFA competitions.
        sport:
          type: string
          enum:
          - american_football
          - basketball
          - ice_hockey
          - baseball
          - soccer
        abbreviation:
          type: string
        name:
          type: string
        short_name:
          type:
          - string
          - 'null'
          description: Soccer clubs
        nickname:
          type: string
          description: US leagues
        city:
          type: string
        country:
          type:
          - string
          - 'null'
          description: 'Soccer clubs: ISO 3166-1 alpha-2'
        conference:
          type: string
          description: US leagues
        division:
          type: string
          description: US leagues
        venue:
          $ref: '#/components/schemas/SportsVenue'
        active:
          type: boolean
    SportsGame:
      type: object
      properties:
        game_id:
          type: string
          example: nba-20261022-cle-phi
          description: Unique, permanent id of the game.
        league:
          type: string
          enum:
          - nfl
          - nba
          - wnba
          - nhl
          - mlb
          - epl
          - laliga
          - bundesliga
          - seriea
          - ligue1
          - ucl
          - uel
          - mls
        sport:
          type: string
          enum:
          - american_football
          - basketball
          - ice_hockey
          - baseball
          - soccer
        season:
          type: integer
          example: 2026
          description: Year the season starts.
        season_label:
          type: string
          example: 2026-27
        season_type:
          type: string
          enum:
          - preseason
          - regular
          - cup_final
          - play_in
          - postseason
          - group_stage
          - league_phase
          - knockout
        week:
          type:
          - integer
          - 'null'
          description: NFL only.
        round:
          type:
          - string
          - 'null'
          description: 'Soccer only: the cup or playoff round, e.g. Round of 16, Quarterfinals, Final; null for league matches.'
        leg:
          type:
          - integer
          - 'null'
          description: 'Soccer only: 1 or 2 for a two-legged knockout tie, otherwise null.'
        date:
          type: string
          format: date
          description: Game day in the league's home time zone.
        start_time:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - scheduled
          - in_progress
          - final
          - postponed
          - canceled
          - suspended
          - delayed
        status_detail:
          type:
          - string
          - 'null'
          description: 'While a game is in progress: halftime or end_of_period (NFL, NBA, WNBA), intermission (NHL), halftime, extra_time_break or penalties (soccer), top, middle, bottom or end (MLB). While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.'
        period:
          type:
          - integer
          - 'null'
          description: 'Current or last period played: quarter, period, inning, or soccer half (3 and 4 = extra time). While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.'
        clock:
          type:
          - string
          - 'null'
          description: Time left in the period while in progress, or the match minute in soccer (e.g. 67' or 90'+3'); always null in MLB. While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.
        home_team:
          $ref: '#/components/schemas/SportsTeamRef'
        away_team:
          $ref: '#/components/schemas/SportsTeamRef'
        home_score:
          type:
          - integer
          - 'null'
          description: While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.
        away_score:
          type:
          - integer
          - 'null'
          description: While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.
        period_scores:
          type:
          - object
          - 'null'
          description: Points, goals or runs per period, half or inning, including overtime periods, extra-time halves and extra innings. While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.
          properties:
            home:
              type: array
              items:
                type: integer
            away:
              type: array
              items:
                type: integer
        penalty_scores:
          type:
          - object
          - 'null'
          description: 'Soccer only: penalty shootout score when a match is decided on penalties. While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.'
          properties:
            home:
              type: integer
            away:
              type: integer
        aggregate_scores:
          type:
          - object
          - 'null'
          description: 'Soccer only: aggregate score of a two-legged tie after this match. While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.'
          properties:
            home:
              type: integer
            away:
              type: integer
        hits:
          type:
          - object
          - 'null'
          description: 'MLB only: hits per team. While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.'
          properties:
            home:
              type: integer
            away:
              type: integer
        errors:
          type:
          - object
          - 'null'
          description: 'MLB only: errors per team. While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.'
          properties:
            home:
              type: integer
            away:
              type: integer
        decided_in:
          type:
          - string
          - 'null'
          enum:
          - regulation
          - overtime
          - shootout
          - extra_innings
          - extra_time
          - penalties
          - null
        winner:
          type:
          - string
          - 'null'
          description: team_id of the winner of a final game (the shootout winner for a soccer match decided on penalties); null before then and for ties and draws.
        venue:
          $ref: '#/components/schemas/SportsVenue'
        neutral_site:
          type: boolean
        original_date:
          type:
          - string
          - 'null'
          format: date
          description: First scheduled date of a moved game.
        updated_at:
          type: string
          format: date-time
    SportsVenue:
      type:
      - object
      - 'null'
      properties:
        name:
          type: string
        city:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
          description: ISO 3166-1 alpha-2
    SportsStanding:
      type: object
      description: Fields that do not apply to a league are omitted.
      properties:
        league:
          type: string
          enum:
          - nfl
          - nba
          - wnba
          - nhl
          - mlb
          - epl
          - laliga
          - bundesliga
          - seriea
          - ligue1
          - ucl
          - uel
          - mls
        sport:
          type: string
          enum:
          - american_football
          - basketball
          - ice_hockey
          - baseball
          - soccer
        season:
          type: integer
        season_label:
          type: string
        team:
          $ref: '#/components/schemas/SportsTeamRef'
        conference:
          type:
          - string
          - 'null'
          description: Conference (AFC, Eastern), or AL / NL in MLB; null for European soccer.
        division:
          type:
          - string
          - 'null'
        group:
          type: string
          description: UEFA seasons with a group stage, e.g. Group C.
        games_played:
          type: integer
        wins:
          type: integer
        draws:
          type: integer
          description: Soccer
        losses:
          type: integer
        ties:
          type: integer
          description: NFL
        ot_losses:
          type: integer
          description: NHL
        points:
          type: integer
          description: NHL, soccer
        win_pct:
          type: number
          description: NFL, NBA, WNBA, MLB
        point_pct:
          type: number
          description: NHL
        games_behind:
          type: number
          description: 'NFL, NBA, MLB: behind the division leader; WNBA: behind the conference leader'
        regulation_wins:
          type: integer
          description: NHL
        points_for:
          type: integer
          description: NFL, NBA, WNBA; runs in MLB
        points_against:
          type: integer
          description: NFL, NBA, WNBA; runs in MLB
        point_differential:
          type: integer
        goals_for:
          type: integer
          description: NHL, soccer
        goals_against:
          type: integer
          description: NHL, soccer
        goal_differential:
          type: integer
          description: NHL
        goal_difference:
          type: integer
          description: Soccer
        points_deducted:
          type: integer
          description: 'Soccer: points deducted by the competition, when any'
        streak:
          type: string
          example: W2
        home_record:
          type: string
        away_record:
          type: string
        division_record:
          type: string
        conference_record:
          type: string
        last_10:
          type: string
        league_rank:
          type: integer
          description: 'Soccer: table position with the competition tiebreakers applied'
        conference_rank:
          type: integer
          description: 'NFL, NBA, MLB: playoff seed; WNBA, MLS: rank in the conference'
        division_rank:
          type: integer
        group_rank:
          type: integer
          description: 'UEFA group stage: position in the group'
        wildcard_rank:
          type: integer
          description: NHL
        clinched:
          type: string
          description: NHL
        qualification:
          type: string
          description: 'Soccer: what the position leads to, e.g. Champions League or Relegation'
        final:
          type: boolean
    SportsTeamRef:
      type: object
      properties:
        team_id:
          type: string
          example: nba-phi
          description: League team id (nba-phi) or soccer club id (soccer-arsenal), which is the same in every competition.
        name:
          type: string
          example: Philadelphia 76ers
        abbreviation:
          type: string
          example: PHI
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api