api-ninjas-com Football (Soccer) API

openapi: 3.2.0
info:
  title: Ninjas Football (Soccer) 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: Football (Soccer)
  description: Fixtures, live scores and results, league tables, clubs and squads for the Premier League (epl), La Liga (laliga), Bundesliga, Serie A (seriea), Ligue 1 (ligue1), UEFA Champions League (ucl), UEFA Europa League (uel) and MLS (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/soccermatches:
    get:
      summary: Get fixtures, live scores and results
      description: Returns matches 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 matches in the league's home time zone.
      operationId: getSoccerMatches
      parameters:
      - name: league
        in: query
        required: false
        description: epl, laliga, bundesliga, seriea, ligue1, ucl, uel or mls. Required unless game_id or a team id is given.
        schema:
          type: string
          example: epl
          enum:
          - 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: ARS
      - 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:
          - regular
          - 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: epl-20261025-new-cry
      - 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/SoccerGame'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoccerError'
      security:
      - ApiKeyAuth: []
      tags:
      - Football (Soccer)
  /v1/soccerstandings:
    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: getSoccerStandings
      parameters:
      - name: league
        in: query
        required: true
        description: epl, laliga, bundesliga, seriea, ligue1, ucl, uel or mls.
        schema:
          type: string
          example: epl
          enum:
          - 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
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SoccerStanding'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoccerError'
      security:
      - ApiKeyAuth: []
      tags:
      - Football (Soccer)
  /v1/soccerclubs:
    get:
      summary: List teams
      description: Lists the clubs with domestic league and country and home venue.
      operationId: getSoccerClubs
      parameters:
      - name: league
        in: query
        required: false
        description: Only this league; every league of the API when absent.
        schema:
          type: string
          example: epl
          enum:
          - epl
          - laliga
          - bundesliga
          - seriea
          - ligue1
          - ucl
          - uel
          - mls
      - name: team
        in: query
        required: false
        description: 'Team id, abbreviation or name: one team.'
        schema:
          type: string
          example: ARS
      - 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/SoccerTeam'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoccerError'
      security:
      - ApiKeyAuth: []
      tags:
      - Football (Soccer)
  /v1/soccerplayers:
    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: getSoccerPlayers
      parameters:
      - name: league
        in: query
        required: false
        description: epl, laliga, bundesliga, seriea, ligue1, ucl, uel or mls.
        schema:
          type: string
          example: epl
          enum:
          - 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: ARS
      - 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. 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/SoccerPlayer'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoccerError'
      security:
      - ApiKeyAuth: []
      tags:
      - Football (Soccer)
components:
  schemas:
    SoccerGame:
      type: object
      properties:
        game_id:
          type: string
          example: epl-20261025-new-cry
          description: Unique, permanent id of the game.
        league:
          type: string
          enum:
          - epl
          - laliga
          - bundesliga
          - seriea
          - ligue1
          - ucl
          - uel
          - mls
        sport:
          type: string
          enum:
          - soccer
        season:
          type: integer
          example: 2026
          description: Year the season starts.
        season_label:
          type: string
          example: 2026-27
        season_type:
          type: string
          enum:
          - regular
          - postseason
          - group_stage
          - league_phase
          - knockout
        round:
          type:
          - string
          - 'null'
          description: the cup or playoff round, e.g. Round of 16, Quarterfinals, Final; null for league matches.
        leg:
          type:
          - integer
          - 'null'
          description: 1 or 2 for a two-legged knockout tie, otherwise null.
        date:
          type: string
          format: date
          description: Match day in the competition'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 match is in progress: halftime, extra_time_break or penalties. 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 half played: 1 and 2, then 3 and 4 for 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: Match minute while in progress, e.g. 67' or 90'+3'. 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/SoccerTeamRef'
        away_team:
          $ref: '#/components/schemas/SoccerTeamRef'
        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 half, with both halves of extra time when played. 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: 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: 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
        decided_in:
          type:
          - string
          - 'null'
          enum:
          - regulation
          - extra_time
          - penalties
          - null
        winner:
          type:
          - string
          - 'null'
          description: team_id of the winner of a final match (the shootout winner for a match decided on penalties); null before then and for draws.
        venue:
          $ref: '#/components/schemas/SoccerVenue'
        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
    SoccerPlayer:
      type: object
      properties:
        player_id:
          type: string
          description: Permanent id, the same in every league.
        league:
          type: string
          enum:
          - epl
          - laliga
          - bundesliga
          - seriea
          - ligue1
          - ucl
          - uel
          - mls
        team:
          allOf:
          - $ref: '#/components/schemas/SoccerTeamRef'
        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
        nationality:
          type: string
    SoccerTeam:
      type: object
      properties:
        team_id:
          type: string
          example: soccer-arsenal
          description: Club id, the same in every competition.
        league:
          type:
          - string
          - 'null'
          enum:
          - 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:
          - soccer
        abbreviation:
          type: string
        name:
          type: string
        short_name:
          type:
          - string
          - 'null'
        city:
          type: string
        country:
          type:
          - string
          - 'null'
          description: 'Soccer clubs: ISO 3166-1 alpha-2'
        venue:
          $ref: '#/components/schemas/SoccerVenue'
        active:
          type: boolean
    SoccerVenue:
      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
    SoccerStanding:
      type: object
      description: Fields that do not apply to a league are omitted.
      properties:
        league:
          type: string
          enum:
          - epl
          - laliga
          - bundesliga
          - seriea
          - ligue1
          - ucl
          - uel
          - mls
        sport:
          type: string
          enum:
          - soccer
        season:
          type: integer
        season_label:
          type: string
        team:
          $ref: '#/components/schemas/SoccerTeamRef'
        conference:
          type:
          - string
          - 'null'
          description: 'MLS: conference (Eastern or Western); null in the European competitions.'
        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
        losses:
          type: integer
        points:
          type: integer
        goals_for:
          type: integer
        goals_against:
          type: integer
        goal_difference:
          type: integer
        points_deducted:
          type: integer
          description: 'Soccer: points deducted by the competition, when any'
        league_rank:
          type: integer
        conference_rank:
          type: integer
        division_rank:
          type: integer
        group_rank:
          type: integer
          description: 'UEFA group stage: position in the group'
        qualification:
          type: string
          description: 'Soccer: what the position leads to, e.g. Champions League or Relegation'
        final:
          type: boolean
    SoccerError:
      type: object
      properties:
        error:
          type: string
    SoccerTeamRef:
      type: object
      properties:
        team_id:
          type: string
          example: soccer-arsenal
          description: Club id, the same in every competition, e.g. soccer-arsenal.
        name:
          type: string
        abbreviation:
          type: string
          example: ARS
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api