openapi: 3.2.0
info:
title: iSports Football Stats API
version: '2026-08-09'
description: 'Key-authenticated REST/HTTP data feeds for football (soccer) and basketball: livescores, schedules and results, match events, lineups, live text, statistics, standings, player and team profiles, transfers, referees, multi-language name packs, live-animation feeds, and pre-match / in-play / historical odds across 200+ bookmakers.
All operations are GET, authenticated with an `api_key` query parameter, and return the same `{code, message, data}` envelope with HTTP 200 — including on error (see `code`).
This document was derived by API Evangelist from the endpoint definitions the provider publishes at https://www.isportsapi.com/en/docs.html — iSports API does not publish an OpenAPI definition of its own.'
termsOfService: https://www.isportsapi.com/en/home/terms.html
contact:
name: iSports API
url: https://www.isportsapi.com/en/
x-derived-by: API Evangelist enrichment pipeline
x-derived-from: https://www.isportsapi.com/en/docs.html
x-derived-on: '2026-08-09'
servers:
- url: https://api.isportsapi.com
description: Primary API host
- url: https://api2.isportsapi.com
description: Alternate host, documented for when the primary host is slow or unreachable
security:
- apiKeyQuery: []
tags:
- name: Football Stats
paths:
/sport/football/playerstats/match/list:
get:
operationId: getFootballPlayerstatsMatchList
summary: List of Player Stats (Match)
description: "• This API endpoint returns match list which contains players' technical statistics within one day (24H). You can use it with the <a href=\"/docs.html?id=40\" style=\"color:blue\">Player Stats (Match)</a> endpoint.\n\n\n\n• Coverage is limited to selected top leagues. \n\n\n\n• By using endpoints <a href=\"/docs.html?id=41\" style=\"color:blue\">Schedule & Results (Basic)\n</a> and <a href=\"/docs.html?id=33\" style=\"color:blue\">Match Modify Record</a>, you can get basic information of matches."
tags:
- Football Stats
responses:
'200':
description: Standard iSports envelope. `code` 0 indicates success; a non-zero `code` carries the error in `message` (HTTP status is 200 in both cases).
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: 0 on success; 2 on invalid/illegal api_key
message:
type: string
description: '"success" on success; otherwise the error message'
data:
type: array
items:
type: object
properties:
matchId:
type: string
matchTime:
type: integer
description: Match kick-off time (Unix timestamp, GMT+0)
leagueName:
type: string
description: League or cup name
homeName:
type: string
description: Home team name
awayName:
type: string
description: Away team name
modifyTime:
type: integer
description: Timestamp of when this record was last modified (Unix timestamp, GMT+0)
externalDocs:
description: iSports API documentation
url: https://www.isportsapi.com/en/docs.html?id=37
x-documentation:
- https://www.isportsapi.com/en/docs.html?id=37
x-rate-limit: This interface is limited to 60 seconds/call;
x-recommended-call-frequency: 12 hours/call
x-plan-products:
- Stats
x-doc-modified: '2026-06-29'
/sport/football/standing/league/getsub:
get:
operationId: getFootballStandingLeagueGetsub
summary: League Standing (Get Subleague)
description: '• This API endpoint returns a list of sub-leagues and stages for a specified league. Use the returned subLeagueId with the League Standing endpoint to retrieve standings for each stage.
• Sub-leagues are used to differentiate divisions or multiple stages within a league (e.g., group stage, play-off). Use the League & Cup Profile endpoint to get full profile information for each league.'
tags:
- Football Stats
parameters:
- name: leagueId
in: query
required: true
schema:
type: string
description: League ID to retrieve sub-leagues and stages for.
responses:
'200':
description: Standard iSports envelope. `code` 0 indicates success; a non-zero `code` carries the error in `message` (HTTP status is 200 in both cases).
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: 0 on success; 2 on invalid/illegal api_key
message:
type: string
description: '"success" on success; otherwise the error message'
data:
type: array
items:
type: object
properties:
subLeagueId:
type: string
currentSubLeague:
type: boolean
description: "true: This sub-league or stage is currently in progress\n false: Not in progress"
externalDocs:
description: iSports API documentation
url: https://www.isportsapi.com/en/docs.html?id=38
x-documentation:
- https://www.isportsapi.com/en/docs.html?id=38
x-rate-limit: This interface is limited to 3 seconds/call;
x-recommended-call-frequency: 1 day/call
x-plan-products:
- Stats
x-doc-modified: '2026-06-29'
/sport/football/topscorer:
get:
operationId: getFootballTopscorer
summary: Top Scorer
description: "• This API endpoint returns top scorer statistics for a specified league or cup, including goals broken down by home, away, and penalty. \n\n\n\n• Coverage is limited to selected major leagues and cups.\n\n\n\n• By using endpoint <a href=\"/docs.html?id=42\" style=\"color:blue\">League & Cup Profile (Basic)\n</a>, you can get basic information of leagues and cups."
tags:
- Football Stats
parameters:
- name: leagueId
in: query
required: true
schema:
type: string
description: League or cup ID to retrieve top scorer data for.
- name: season
in: query
required: false
schema:
type: string
description: 'Season to retrieve data for (e.g., 2025, 2025-2026).
Must be used together with leagueId. If omitted, returns current season data.'
responses:
'200':
description: Standard iSports envelope. `code` 0 indicates success; a non-zero `code` carries the error in `message` (HTTP status is 200 in both cases).
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: 0 on success; 2 on invalid/illegal api_key
message:
type: string
description: '"success" on success; otherwise the error message'
data:
type: array
items:
type: object
properties:
playerId:
type: string
playerName:
type: string
description: Player's full name
teamId:
type: string
teamName:
type: string
description: Team name
country:
type: string
description: Player's nationality (e.g., Paraguay, Argentina)
goalsCount:
type: integer
description: Total goals scored, including penalties
homeGoals:
type: integer
description: Goals scored in home matches, including penalties
awayGoals:
type: integer
description: Goals scored in away matches, including penalties
homePenalty:
type: integer
description: Penalty goals scored in home matches
awayPenalty:
type: integer
description: Penalty goals scored in away matches
matchNum:
type: integer
description: Total appearances. Null if not available for cup competitions.
subNum:
type: integer
description: Substitute appearances. Null if not available for cup competitions.
externalDocs:
description: iSports API documentation
url: https://www.isportsapi.com/en/docs.html?id=39
x-documentation:
- https://www.isportsapi.com/en/docs.html?id=39
x-rate-limit: This interface is limited to 10 seconds/call;
x-recommended-call-frequency: 1 day/call
x-plan-products:
- Stats
x-doc-modified: '2026-06-29'
/sport/football/playerstats/match:
get:
operationId: getFootballPlayerstatsMatch
summary: Player Stats (Match)
description: '• This API endpoint returns players'' technical statistics of specified matchId. You can use it with the <a href="/docs.html?id=37" style="color:blue">List of Player Stats (Match)</a> endpoint.
• Currently only some top leagues are supported.
• support to check back the matches within a week.'
tags:
- Football Stats
parameters:
- name: matchId
in: query
required: true
schema:
type: string
description: 'for detailed statistical data specified match;
support to check back the matches within a week.'
responses:
'200':
description: Standard iSports envelope. `code` 0 indicates success; a non-zero `code` carries the error in `message` (HTTP status is 200 in both cases).
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: 0 on success; 2 on invalid/illegal api_key
message:
type: string
description: '"success" on success; otherwise the error message'
data:
type: array
items:
type: object
properties:
playerId:
type: string
teamId:
type: string
number:
type: integer
description: Player's shirt number
name:
type: string
description: Player's full name
positionName:
type: string
description: Player's position (e.g., Goalkeeper, Defender)
shots:
type: integer
description: Total shots attempted
shotsTarget:
type: integer
description: Shots on target
keyPass:
type: integer
description: Key passes (directly creating a goal-scoring opportunity)
passRate:
type: string
description: Pass accuracy rate (e.g., 0.741935 = 74.2%)
aerialWon:
type: integer
description: Aerial duels won
touches:
type: integer
description: Total ball touches
dribblesWon:
type: integer
description: Successful dribbles
wasFouled:
type: integer
description: Times fouled by an opponent
dispossessed:
type: integer
description: Times dispossessed
turnOver:
type: integer
description: Times possession was lost without a foul
offsides:
type: integer
description: Times caught offside
tackles:
type: integer
description: Tackles attempted
interception:
type: integer
description: Interceptions made
clearances:
type: integer
description: Clearances made
clearanceWon:
type: integer
description: Clearances won under pressure
shotsBlocked:
type: integer
description: Opponent shots blocked
offsideProvoked:
type: integer
description: Times an opponent was caught offside due to this player
fouls:
type: integer
description: Fouls committed
totalPass:
type: integer
description: Total passes attempted
accuratePass:
type: integer
description: Accurate passes completed
crossNum:
type: integer
description: Crosses attempted
crossWon:
type: integer
description: Successful crosses
longBall:
type: integer
description: Long balls attempted
longBallWon:
type: integer
description: Successful long balls
throughBall:
type: integer
description: Through balls attempted
throughBallWon:
type: integer
description: Successful through balls
rating:
type: string
description: Player match rating (e.g., 7.5)
red:
type: integer
description: Red cards received
yellow:
type: integer
description: Yellow cards received
assist:
type: integer
description: Assists
playingTime:
type: integer
description: Minutes played
goals:
type: integer
description: Goals scored
firstTeam:
type: boolean
description: "true: Player started in the lineup \n false: Substitute"
penaltyGoals:
type: integer
description: Goals scored from penalty kicks
shotOnPost:
type: integer
description: Shots hitting the post
errorLeadToGoal:
type: integer
description: Errors directly leading to an opponent's goal
secondYellow:
type: integer
description: Second yellow cards received (resulting in red)
penaltySave:
type: integer
description: Penalty kicks saved (goalkeepers only). 0 if not applicable
isBest:
type: boolean
description: "true: Player of the match \n false: Not selected"
duelTotal:
type: integer
description: Total 1v1 duels participated in
aerialTotal:
type: integer
description: "1v1 duels won. \n Note: despite the field name, this represents successful duels, not total count."
highClaims:
type: integer
description: High balls successfully claimed (goalkeepers only). 0 if not applicable
saves:
type: integer
description: Saves made (goalkeepers only). 0 if not applicable
punches:
type: integer
description: Times the goalkeeper punched the ball clear. 0 if not applicable
externalDocs:
description: iSports API documentation
url: https://www.isportsapi.com/en/docs.html?id=40
x-documentation:
- https://www.isportsapi.com/en/docs.html?id=40
x-rate-limit: This interface is limited to 10 seconds/call;
x-recommended-call-frequency: 1 minute/call
x-plan-products:
- Stats
x-doc-modified: '2026-08-03'
/sport/football/standing/league:
get:
operationId: getFootballStandingLeague
summary: League Standing
description: '• This API endpoint returns league standings for a specified league, including total, home, away, and first-half breakdowns.
• Use it with the League Standing (Get Subleague) endpoint to get available subLeagueId values when a league has multiple stages or divisions.
• Without parameters, returns all leagues and cups with standings updated in the past 24 hours. Use the League & Cup Profile endpoint to get basic league information.'
tags:
- Football Stats
parameters:
- name: leagueId
in: query
required: true
schema:
type: string
description: "League ID to retrieve standings for. \n\n\n\nIf the league has multiple stages or sub-leagues, standings are differentiated by sub-league. \n\n\n\nUse subLeagueId to filter to a specific stage."
- name: subLeagueId
in: query
required: false
schema:
type: string
description: "Sub-league or stage ID. \n\n\n\nIf omitted, returns the standings of the first sub-league in the subLeagueInfos list by default (e.g., leagueId=1122&subLeagueId=1122)."
responses:
'200':
description: Standard iSports envelope. `code` 0 indicates success; a non-zero `code` carries the error in `message` (HTTP status is 200 in both cases).
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: 0 on success; 2 on invalid/illegal api_key
message:
type: string
description: '"success" on success; otherwise the error message'
data:
type: array
items:
type: object
properties:
leagueInfo:
type: object
description: Basic profile of the league
properties:
leagueId:
type: string
name:
type: string
description: Full league name (e.g., Brazil Serie A)
shortName:
type: string
description: Abbreviated league name (e.g., BRA D1)
logo:
type: string
description: "League logo image URL. \n\n Do not hotlink directly; download and serve locally."
color:
type: string
description: 'Theme color as an RGB hex code (e.g., #B5A150)'
totalRound:
type: integer
description: Total number of rounds in the season
currentRound:
type: integer
description: Current round in progress
currentSeason:
type: string
description: Current season identifier (e.g., 2026, 2025-2026)
subLeagueInfos:
type: array
description: List of sub-leagues or stages within the league
items:
type: object
properties:
subLeagueId:
type: string
name:
type: string
description: Sub-league or stage name (e.g., League, Western Play-off)
totalRound:
type: integer
description: Total rounds in this sub-league
currentRound:
type: integer
description: Current round in this sub-league
hasScore:
type: boolean
description: "true: Standing data is available \n false: Not available"
hasTwoLegs:
type: boolean
description: "true: Ties are decided over two legs \n false: Single match"
currentSubLeague:
type: boolean
description: "true: This sub-league is currently in progress \n false: Not in progress"
teamInfos:
type: array
description: List of teams participating in this league
items:
type: object
properties:
teamId:
type: string
name:
type: string
description: Team name
logo:
type: string
description: "Team logo image URL. \n\nDo not hotlink directly; download and serve locally."
area:
type: integer
description: "Conference zone \n 0: No division 1: East 2: West"
totalStandings:
type: array
description: Full-match standings (all venues)
items:
type: object
properties:
rank:
type: integer
description: Current league position
teamId:
type: string
winRate:
type: string
description: Win rate as a percentage (e.g., 57.1)
drawRate:
type: string
description: Draw rate as a percentage
loseRate:
type: string
description: Loss rate as a percentage
winAverage:
type: string
description: Average goals scored per match
loseAverage:
type: string
description: Average goals conceded per match
deduction:
type: string
description: Points deducted
deductionExplain:
type: string
description: Explanation of points deduction. Empty string if no deduction.
recentFirstResult:
type: integer
description: "Result of most recent match \n 0: Win 1: Draw 2: Loss 3: Empty"
recentSecondResult:
type: integer
description: "Result of 2nd most recent match. \n 0: Win 1: Draw 2: Loss 3: Empty"
recentThirdResult:
type: integer
description: "Result of 3rd most recent match. \n 0: Win 1: Draw 2: Loss 3: Empty"
recentFourthResult:
type: integer
description: "Result of 4th most recent match. \n 0: Win 1: Draw 2: Loss 3: Empty"
recentFifthResult:
type: integer
description: "Result of 5th most recent match. \n 0: Win 1: Draw 2: Loss 3: Empty"
recentSixthResult:
type: integer
description: "Result of 6th most recent match. \n 0: Win 1: Draw 2: Loss 3: Empty"
color:
type: string
description: "Promotion or relegation zone indicator. \n\n Corresponds to the index of the matching entry in leagueColorInfos (starting from 0). -1 indicates no promotion or relegation status."
red:
type: integer
description: Red cards received
totalCount:
type: integer
description: Total matches played
winCount:
type: integer
description: Matches won
drawCount:
type: integer
description: Matches drawn
loseCount:
type: integer
description: Matches lost
getScore:
type: integer
description: Goals scored
loseScore:
type: integer
description: Goals conceded
goalDifference:
type: integer
description: Goal difference (goals scored minus goals conceded)
totalAddScore:
type: integer
description: Additional points awarded (e.g., bonus points)
integral:
type: integer
description: Total points (excluding deductions)
halfStandings:
type: array
description: First-half standings (all venues)
items:
type: object
properties:
rank:
type: integer
description: Current league position
teamId:
type: string
winRate:
type: string
description: Win rate as a percentage (e.g., 57.1)
drawRate:
type: string
description: Draw rate as a percentage
loseRate:
type: string
description: Loss rate as a percentage
winAverage:
type: string
description: Average goals scored per match
loseAverage:
type: string
description: Average goals conceded per match
totalCount:
type: integer
description: Total matches played
winCount:
type: integer
description: Matches won
drawCount:
type: integer
description: Matches drawn
loseCount:
type: integer
description: Matches lost
getScore:
type: integer
description: Goals scored
loseScore:
type: integer
description: Goals conceded
goalDifference:
type: integer
description: Goal difference (goals scored minus goals conceded)
integral:
type: integer
description: Total points (excluding deductions)
homeStandings:
type: array
description: Full-match standings, home matches only
items: {}
awayStandings:
type: array
description: Full-match standings, away matches only
items: {}
homeHalfStandings:
type: array
description: First-half standings, home matches only
items: {}
awayHalf
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/isports-api/refs/heads/main/openapi/isports-api-football-stats-api-openapi.yml