api-ninjas-com Basketball API

openapi: 3.2.0
info:
  title: Ninjas Basketball 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: Basketball
  description: NBA, WNBA and Division I men's and women's college basketball schedules, live and final scores, standings, college polls, teams and rosters. 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/basketballgames:
    get:
      summary: Get schedules, live scores and final scores
      description: Returns games for one day, a team's season, a season (50 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: getBasketballGames
      parameters:
      - name: league
        in: query
        required: false
        description: nba, wnba, ncaab (men's college) or ncaaw (women's college).
        schema:
          type: string
          example: nba
          enum:
          - nba
          - wnba
          - ncaab
          - ncaaw
      - 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
          - conference_tournament
          - postseason
      - 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/BasketballGame'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasketballError'
      security:
      - ApiKeyAuth: []
      tags:
      - Basketball
  /v1/basketballstandings:
    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. College tables come conference by conference; with poll, college leagues return a weekly poll (rank, team, previous_rank, points, first_place_votes) instead.
      operationId: getBasketballStandings
      parameters:
      - name: league
        in: query
        required: true
        description: nba, wnba, ncaab (men's college) or ncaaw (women's college).
        schema:
          type: string
          example: nba
          enum:
          - nba
          - wnba
          - ncaab
          - ncaaw
      - 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
      - name: poll
        in: query
        required: false
        description: 'College: return this weekly poll instead of the table: ap, coaches (ap = AP Top 25, coaches = Coaches Poll).'
        schema:
          type: string
          enum:
          - ap
          - coaches
      - name: week
        in: query
        required: false
        description: 'With poll: a week number of the season, or final for the final poll. Defaults to the latest.'
        schema:
          type: string
          example: '10'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BasketballStanding'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasketballError'
      security:
      - ApiKeyAuth: []
      tags:
      - Basketball
  /v1/basketballteams:
    get:
      summary: List teams
      description: Lists the teams with league, conference, division and home venue.
      operationId: getBasketballTeams
      parameters:
      - name: league
        in: query
        required: false
        description: nba, wnba, ncaab (men's college) or ncaaw (women's college).
        schema:
          type: string
          example: nba
          enum:
          - nba
          - wnba
          - ncaab
          - ncaaw
      - 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/BasketballTeam'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasketballError'
      security:
      - ApiKeyAuth: []
      tags:
      - Basketball
  /v1/basketballplayers:
    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: getBasketballPlayers
      parameters:
      - name: league
        in: query
        required: false
        description: nba, wnba, ncaab (men's college) or ncaaw (women's college).
        schema:
          type: string
          example: nba
          enum:
          - nba
          - wnba
          - ncaab
          - ncaaw
      - 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. G.
        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/BasketballPlayer'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasketballError'
      security:
      - ApiKeyAuth: []
      tags:
      - Basketball
components:
  schemas:
    BasketballGame:
      type: object
      properties:
        game_id:
          type: string
          example: nba-20261022-cle-phi
          description: Unique, permanent id of the game.
        league:
          type: string
          enum:
          - nba
          - wnba
        sport:
          type: string
          enum:
          - basketball
        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
          - conference_tournament
          - postseason
        date:
          type: string
          format: date
          description: Game day in US Eastern time.
        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. 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 quarter played; overtime periods continue the count. 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 quarter while in progress. 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/BasketballTeamRef'
        away_team:
          $ref: '#/components/schemas/BasketballTeamRef'
        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 per quarter, with each overtime period. 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
        decided_in:
          type:
          - string
          - 'null'
          enum:
          - regulation
          - overtime
          - null
        winner:
          type:
          - string
          - 'null'
          description: team_id of the winner of a final game; null before then.
        venue:
          $ref: '#/components/schemas/BasketballVenue'
        event:
          type:
          - string
          - 'null'
          description: 'College only: tournament, bowl or round, e.g. Big East Tournament - Quarterfinal or NCAA Men''s Basketball Championship - West Region - 1st Round.'
        conference_game:
          type: boolean
          description: 'College only: true when the game counts in the conference standings.'
        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
    BasketballVenue:
      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
    BasketballTeam:
      type: object
      properties:
        team_id:
          type: string
          example: nba-bos
        league:
          type: string
          enum:
          - nba
          - wnba
        sport:
          type: string
          enum:
          - basketball
        abbreviation:
          type: string
        name:
          type: string
        school:
          type: string
          description: 'College: the school name, e.g. Duke.'
        state:
          type:
          - string
          - 'null'
          description: 'College: state of the home venue.'
        nickname:
          type: string
        city:
          type: string
        conference:
          type: string
        division:
          type: string
        venue:
          $ref: '#/components/schemas/BasketballVenue'
        active:
          type: boolean
    BasketballError:
      type: object
      properties:
        error:
          type: string
    BasketballTeamRef:
      type: object
      properties:
        team_id:
          type: string
          example: nba-bos
          description: Team id, e.g. nba-bos.
        name:
          type: string
        abbreviation:
          type: string
          example: BOS
        rank:
          type:
          - integer
          - 'null'
          description: 'College games only: Top 25 rank at game time (AP poll), null when unranked.'
        seed:
          type:
          - integer
          - 'null'
          description: 'College games only: seed in NCAA tournament games.'
    BasketballPlayer:
      type: object
      properties:
        player_id:
          type: string
          description: Permanent id; it stays the same when a player changes teams.
        league:
          type: string
          enum:
          - nba
          - wnba
        team:
          allOf:
          - $ref: '#/components/schemas/BasketballTeamRef'
        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
        experience_years:
          type: integer
        class_year:
          type: string
          enum:
          - freshman
          - sophomore
          - junior
          - senior
          - graduate
          description: 'College: class year.'
    BasketballStanding:
      type: object
      description: Fields that do not apply to a league are omitted.
      properties:
        league:
          type: string
          enum:
          - nba
          - wnba
        sport:
          type: string
          enum:
          - basketball
        season:
          type: integer
        season_label:
          type: string
        team:
          $ref: '#/components/schemas/BasketballTeamRef'
        conference:
          type:
          - string
          - 'null'
          description: Conference, Eastern or Western.
        division:
          type:
          - string
          - 'null'
        games_played:
          type: integer
        wins:
          type: integer
        losses:
          type: integer
        win_pct:
          type: number
        games_behind:
          type: number
        points_for:
          type: integer
        points_against:
          type: integer
        point_differential:
          type: integer
        streak:
          type: string
          example: W2
        home_record:
          type: string
        away_record:
          type: string
        division_record:
          type: string
        conference_record:
          type: string
        conference_win_pct:
          type:
          - number
          - 'null'
          description: 'College: winning percentage in conference games.'
        last_10:
          type: string
        league_rank:
          type: integer
        conference_rank:
          type: integer
        division_rank:
          type: integer
        final:
          type: boolean
        poll:
          type: string
          enum:
          - ap
          - coaches
          description: 'With poll: which poll.'
        poll_name:
          type: string
          example: AP Top 25
        week:
          type:
          - integer
          - 'null'
          description: 'With poll: week of the season; null for the final poll.'
        date:
          type: string
          format: date
          description: 'With poll: release date.'
        rank:
          type: integer
          description: 'With poll: rank in the poll.'
        previous_rank:
          type:
          - integer
          - 'null'
        points:
          type:
          - integer
          - 'null'
        first_place_votes:
          type:
          - integer
          - 'null'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api