api-ninjas-com Hockey API

openapi: 3.2.0
info:
  title: Ninjas Hockey 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: Hockey
  description: NHL (ice hockey) schedules, live and final scores by period with overtime and shootouts, standings with points, teams and rosters. league defaults to nhl. 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/hockeygames:
    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 no parameters, returns today's games.
      operationId: getHockeyGames
      parameters:
      - name: league
        in: query
        required: false
        description: 'Optional: nhl, the default.'
        schema:
          type: string
          example: nhl
          enum:
          - nhl
      - 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: TOR
      - 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
          - 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: nhl-20261020-sjs-mtl
      - 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/HockeyGame'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HockeyError'
      security:
      - ApiKeyAuth: []
      tags:
      - Hockey
  /v1/hockeystandings:
    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: getHockeyStandings
      parameters:
      - name: league
        in: query
        required: false
        description: 'Optional: nhl, the default.'
        schema:
          type: string
          example: nhl
          enum:
          - nhl
      - 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/HockeyStanding'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HockeyError'
      security:
      - ApiKeyAuth: []
      tags:
      - Hockey
  /v1/hockeyteams:
    get:
      summary: List teams
      description: Lists the teams with league, conference, division and home venue.
      operationId: getHockeyTeams
      parameters:
      - name: league
        in: query
        required: false
        description: 'Optional: nhl, the default.'
        schema:
          type: string
          example: nhl
          enum:
          - nhl
      - name: team
        in: query
        required: false
        description: 'Team id, abbreviation or name: one team.'
        schema:
          type: string
          example: TOR
      - 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/HockeyTeam'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HockeyError'
      security:
      - ApiKeyAuth: []
      tags:
      - Hockey
  /v1/hockeyplayers:
    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: getHockeyPlayers
      parameters:
      - name: league
        in: query
        required: false
        description: 'Optional: nhl, the default.'
        schema:
          type: string
          example: nhl
          enum:
          - nhl
      - name: team
        in: query
        required: false
        description: 'Team id, abbreviation or name: the team''s current roster.'
        schema:
          type: string
          example: TOR
      - 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. C.
        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/HockeyPlayer'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HockeyError'
      security:
      - ApiKeyAuth: []
      tags:
      - Hockey
components:
  schemas:
    HockeyTeam:
      type: object
      properties:
        team_id:
          type: string
          example: nhl-tor
        league:
          type: string
          enum:
          - nhl
        sport:
          type: string
          enum:
          - ice_hockey
        abbreviation:
          type: string
        name:
          type: string
        nickname:
          type: string
        city:
          type: string
        conference:
          type: string
        division:
          type: string
        venue:
          $ref: '#/components/schemas/HockeyVenue'
        active:
          type: boolean
    HockeyStanding:
      type: object
      description: Fields that do not apply to a league are omitted.
      properties:
        league:
          type: string
          enum:
          - nhl
        sport:
          type: string
          enum:
          - ice_hockey
        season:
          type: integer
        season_label:
          type: string
        team:
          $ref: '#/components/schemas/HockeyTeamRef'
        conference:
          type:
          - string
          - 'null'
          description: Conference, Eastern or Western.
        division:
          type:
          - string
          - 'null'
        games_played:
          type: integer
        wins:
          type: integer
        losses:
          type: integer
        ot_losses:
          type: integer
        points:
          type: integer
        point_pct:
          type: number
        regulation_wins:
          type: integer
        goals_for:
          type: integer
        goals_against:
          type: integer
        goal_differential:
          type: integer
        streak:
          type: string
          example: W2
        home_record:
          type: string
        away_record:
          type: string
        last_10:
          type: string
        league_rank:
          type: integer
        conference_rank:
          type: integer
        division_rank:
          type: integer
        wildcard_rank:
          type: integer
        clinched:
          type: string
        final:
          type: boolean
    HockeyVenue:
      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
    HockeyTeamRef:
      type: object
      properties:
        team_id:
          type: string
          example: nhl-tor
          description: Team id, e.g. nhl-tor.
        name:
          type: string
        abbreviation:
          type: string
          example: TOR
    HockeyPlayer:
      type: object
      properties:
        player_id:
          type: string
          description: Permanent id; it stays the same when a player changes teams.
        league:
          type: string
          enum:
          - nhl
        team:
          allOf:
          - $ref: '#/components/schemas/HockeyTeamRef'
        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
        shoots_catches:
          type: string
          enum:
          - L
          - R
    HockeyError:
      type: object
      properties:
        error:
          type: string
    HockeyGame:
      type: object
      properties:
        game_id:
          type: string
          example: nhl-20261020-sjs-mtl
          description: Unique, permanent id of the game.
        league:
          type: string
          enum:
          - nhl
        sport:
          type: string
          enum:
          - ice_hockey
        season:
          type: integer
          example: 2026
          description: Year the season starts.
        season_label:
          type: string
          example: 2026-27
        season_type:
          type: string
          enum:
          - preseason
          - regular
          - 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: intermission between periods. 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; overtime continues 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 period 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/HockeyTeamRef'
        away_team:
          $ref: '#/components/schemas/HockeyTeamRef'
        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: Goals per period, with each overtime period; a shootout is not a 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
          - shootout
          - null
        winner:
          type:
          - string
          - 'null'
          description: team_id of the winner of a final game (including a shootout winner); null before then.
        venue:
          $ref: '#/components/schemas/HockeyVenue'
        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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api