api-ninjas-com American Football API

openapi: 3.2.0
info:
  title: Ninjas American Football 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: American Football
  description: NFL and college football (FBS and FCS) schedules by week, live and final scores by quarter, standings, college rankings, teams and rosters. league defaults to nfl; use league=ncaaf for college football. 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/americanfootballgames:
    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: getAmericanFootballGames
      parameters:
      - name: league
        in: query
        required: false
        description: nfl (the default) or ncaaf (college football, FBS and FCS).
        schema:
          type: string
          example: nfl
          enum:
          - nfl
          - ncaaf
      - 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: KC
      - 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
          - conference_championship
          - 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: nfl-20261019-was-sf
      - 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/AmericanFootballGame'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmericanFootballError'
      security:
      - ApiKeyAuth: []
      tags:
      - American Football
  /v1/americanfootballstandings:
    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: getAmericanFootballStandings
      parameters:
      - name: league
        in: query
        required: false
        description: nfl (the default) or ncaaf (college football, FBS and FCS).
        schema:
          type: string
          example: nfl
          enum:
          - nfl
          - ncaaf
      - 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: subdivision
        in: query
        required: false
        description: 'College football: only FBS or FCS teams.'
        schema:
          type: string
          enum:
          - fbs
          - fcs
      - name: poll
        in: query
        required: false
        description: 'College: return this weekly poll instead of the table: ap, coaches, cfp, fcs (ap = AP Top 25, coaches = Coaches Poll, cfp = College Football Playoff rankings, fcs = FCS Coaches Poll).'
        schema:
          type: string
          enum:
          - ap
          - coaches
          - cfp
          - fcs
      - 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/AmericanFootballStanding'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmericanFootballError'
      security:
      - ApiKeyAuth: []
      tags:
      - American Football
  /v1/americanfootballteams:
    get:
      summary: List teams
      description: Lists the teams with league, conference, division and home venue.
      operationId: getAmericanFootballTeams
      parameters:
      - name: league
        in: query
        required: false
        description: nfl (the default) or ncaaf (college football, FBS and FCS).
        schema:
          type: string
          example: nfl
          enum:
          - nfl
          - ncaaf
      - name: team
        in: query
        required: false
        description: 'Team id, abbreviation or name: one team.'
        schema:
          type: string
          example: KC
      - 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: subdivision
        in: query
        required: false
        description: 'College football: only FBS or FCS teams.'
        schema:
          type: string
          enum:
          - fbs
          - fcs
      - 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/AmericanFootballTeam'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmericanFootballError'
      security:
      - ApiKeyAuth: []
      tags:
      - American Football
  /v1/americanfootballplayers:
    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: getAmericanFootballPlayers
      parameters:
      - name: league
        in: query
        required: false
        description: nfl (the default) or ncaaf (college football, FBS and FCS).
        schema:
          type: string
          example: nfl
          enum:
          - nfl
          - ncaaf
      - name: team
        in: query
        required: false
        description: 'Team id, abbreviation or name: the team''s current roster.'
        schema:
          type: string
          example: KC
      - 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.
        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/AmericanFootballPlayer'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmericanFootballError'
      security:
      - ApiKeyAuth: []
      tags:
      - American Football
components:
  schemas:
    AmericanFootballError:
      type: object
      properties:
        error:
          type: string
    AmericanFootballPlayer:
      type: object
      properties:
        player_id:
          type: string
          description: Permanent id; it stays the same when a player changes teams.
        league:
          type: string
          enum:
          - nfl
        team:
          allOf:
          - $ref: '#/components/schemas/AmericanFootballTeamRef'
        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.'
    AmericanFootballTeamRef:
      type: object
      properties:
        team_id:
          type: string
          example: nfl-kc
          description: Team id, e.g. nfl-kc.
        name:
          type: string
        abbreviation:
          type: string
          example: KC
        rank:
          type:
          - integer
          - 'null'
          description: 'College games only: Top 25 rank at game time (AP poll; the College Football Playoff ranking once published), null when unranked.'
        seed:
          type:
          - integer
          - 'null'
          description: 'College games only: seed in College Football Playoff games.'
    AmericanFootballStanding:
      type: object
      description: Fields that do not apply to a league are omitted.
      properties:
        league:
          type: string
          enum:
          - nfl
        sport:
          type: string
          enum:
          - american_football
        season:
          type: integer
        season_label:
          type: string
        team:
          $ref: '#/components/schemas/AmericanFootballTeamRef'
        conference:
          type:
          - string
          - 'null'
          description: Conference, e.g. AFC.
        division:
          type:
          - string
          - 'null'
        subdivision:
          type: string
          enum:
          - FBS
          - FCS
          description: 'College football: FBS or FCS.'
        games_played:
          type: integer
        wins:
          type: integer
        losses:
          type: integer
        ties:
          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.'
        league_rank:
          type: integer
        conference_rank:
          type: integer
        division_rank:
          type: integer
        final:
          type: boolean
        poll:
          type: string
          enum:
          - ap
          - coaches
          - cfp
          - fcs
          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'
    AmericanFootballTeam:
      type: object
      properties:
        team_id:
          type: string
          example: nfl-kc
        league:
          type: string
          enum:
          - nfl
        sport:
          type: string
          enum:
          - american_football
        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.'
        subdivision:
          type: string
          enum:
          - FBS
          - FCS
          description: 'College football: FBS or FCS.'
        nickname:
          type: string
        city:
          type: string
        conference:
          type: string
        division:
          type: string
        venue:
          $ref: '#/components/schemas/AmericanFootballVenue'
        active:
          type: boolean
    AmericanFootballVenue:
      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
    AmericanFootballGame:
      type: object
      properties:
        game_id:
          type: string
          example: nfl-20261019-was-sf
          description: Unique, permanent id of the game.
        league:
          type: string
          enum:
          - nfl
        sport:
          type: string
          enum:
          - american_football
        season:
          type: integer
          example: 2026
          description: Year the season starts.
        season_label:
          type: string
          example: 2026-27
        season_type:
          type: string
          enum:
          - preseason
          - regular
          - conference_championship
          - postseason
        week:
          type:
          - integer
          - 'null'
          description: NFL only.
        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 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 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/AmericanFootballTeamRef'
        away_team:
          $ref: '#/components/schemas/AmericanFootballTeamRef'
        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, plus overtime. 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 and for ties.
        venue:
          $ref: '#/components/schemas/AmericanFootballVenue'
        event:
          type:
          - string
          - 'null'
          description: 'College only: tournament, bowl or round, e.g. SEC Championship or Rose Bowl Game.'
        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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api