{ "openapi": "3.1.0", "info": { "title": "SportAPI football data API", "version": "1.1.0", "description": "Fixtures, live scores, events, line-ups, match stats, standings, teams, squads and players.\n\nAuthenticate with your API key in the `X-Api-Key` header (create one at https://sportapi.ai/dashboard). Each plan has a daily limit that resets at 00:00 UTC; the Free plan also has a monthly limit of 14,000 requests per calendar month (UTC) from 1 November 2026. Responses carry `X-RateLimit-*` headers (and `X-RateLimit-Month-*` on the Free plan). Successful GETs carry an `ETag`: send it in `If-None-Match` to get `304 Not Modified` when nothing changed.\n\nTimes: `kickoff_utc` and `updated_at` are UTC; `date` and `datetime` are Central European time (CET/CEST).\n\nLive score pushes: WebSocket `wss://sportapi.ai/ws?key=YOUR_API_KEY` (see https://sportapi.ai/docs#websocket).", "contact": { "url": "https://sportapi.ai/contact" } }, "externalDocs": { "url": "https://sportapi.ai/docs" }, "servers": [ { "url": "https://sportapi.ai/api" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Fixtures" }, { "name": "Teams" }, { "name": "Standings" }, { "name": "Leagues" }, { "name": "Players" } ], "paths": { "/fixtures/date/{date}": { "get": { "tags": [ "Fixtures" ], "summary": "Fixtures on a date", "operationId": "fixturesDate", "parameters": [ { "name": "date", "in": "path", "required": true, "schema": { "type": "string" }, "description": "YYYY-MM-DD", "example": "2026-10-10" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "date": { "type": "string", "format": "date" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "home_id": { "type": "integer" }, "away_id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "datetime": { "type": "string", "description": "Kick-off in Central European time (CET/CEST); use kickoff_utc for UTC" }, "kickoff_utc": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string" }, "home_score": { "type": [ "integer", "null" ] }, "away_score": { "type": [ "integer", "null" ] }, "result": { "type": [ "integer", "null" ], "description": "1 home win, 0 draw, -1 away win; null until played" }, "status": { "type": "string", "enum": [ "Scheduled", "LIVE", "FT", "AET", "PENS", "Postponed", "Cancelled", "Suspended" ] }, "minute": { "type": "null", "description": "Match clock while LIVE (\"HT\" at half-time)" }, "stage": { "type": "string" }, "league_id": { "type": "integer" }, "league_name": { "type": "string" }, "league_geo": { "type": "string" }, "league_zone": { "type": "string" }, "home_team": { "type": "string" }, "home_short": { "type": "string" }, "home_logo": { "type": "string", "description": "Logo file name; GET /api/teams/{id}/logo returns the image" }, "home_geo": { "type": "string" }, "away_team": { "type": "string" }, "away_short": { "type": "string" }, "away_logo": { "type": "string", "description": "Logo file name; GET /api/teams/{id}/logo returns the image" }, "away_geo": { "type": "string" }, "penalty_home": { "type": "null" }, "penalty_away": { "type": "null" }, "winner": { "type": [ "string", "null" ], "enum": [ "home", "away", "draw", null ], "description": "Includes the penalty shoot-out" } } } } } }, "example": { "success": true, "date": "2026-10-10", "data": [ { "id": 13596176, "home_id": 311, "away_id": 352, "date": "2026-10-10", "datetime": "2026-10-10 13:30:00", "kickoff_utc": "2026-10-10T11:30:00Z", "updated_at": "2026-10-11T01:43:09Z", "home_score": 2, "away_score": 1, "result": 1, "status": "FT", "minute": null, "stage": "", "league_id": 24, "league_name": "Premier League", "league_geo": "GB-ENG", "league_zone": "England", "home_team": "Arsenal", "home_short": "Arsenal", "home_logo": "espn-359.png", "home_geo": "", "away_team": "Leeds United", "away_short": "Leeds", "away_logo": "espn-357.png", "away_geo": "", "penalty_home": null, "penalty_away": null, "winner": "home" } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/fixtures/{id}": { "get": { "tags": [ "Fixtures" ], "summary": "Fixture with teams, venue, coaches and events", "operationId": "fixtureSingle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Fixture ID", "example": 13596176 }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "fixture": { "type": "object", "properties": { "id": { "type": "integer" }, "home_id": { "type": "integer" }, "away_id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "datetime": { "type": "string", "description": "Kick-off in Central European time (CET/CEST); use kickoff_utc for UTC" }, "kickoff_utc": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string" }, "home_score": { "type": "integer" }, "away_score": { "type": "integer" }, "ht_home": { "type": "integer" }, "ht_away": { "type": "integer" }, "result": { "type": "integer", "description": "1 home win, 0 draw, -1 away win; null until played" }, "status": { "type": "string", "enum": [ "Scheduled", "LIVE", "FT", "AET", "PENS", "Postponed", "Cancelled", "Suspended" ] }, "minute": { "type": "null", "description": "Match clock while LIVE (\"HT\" at half-time)" }, "stage": { "type": "string" }, "league_id": { "type": "integer" }, "league_name": { "type": "string" }, "league_geo": { "type": "string" }, "league_zone": { "type": "string" }, "home_team": { "type": "string" }, "home_short": { "type": "string" }, "home_logo": { "type": "string", "description": "Logo file name; GET /api/teams/{id}/logo returns the image" }, "home_geo": { "type": "string" }, "home_stadium": { "type": "string" }, "home_city": { "type": "string" }, "home_coach": { "type": "string" }, "home_founded": { "type": "integer" }, "away_team": { "type": "string" }, "away_short": { "type": "string" }, "away_logo": { "type": "string", "description": "Logo file name; GET /api/teams/{id}/logo returns the image" }, "away_geo": { "type": "string" }, "away_stadium": { "type": "string" }, "away_city": { "type": "string" }, "away_coach": { "type": "string" }, "away_founded": { "type": "integer" }, "penalty_home": { "type": "null" }, "penalty_away": { "type": "null" }, "winner": { "type": [ "string", "null" ], "enum": [ "home", "away", "draw", null ], "description": "Includes the penalty shoot-out" }, "events": { "type": "array", "items": { "type": "object", "properties": { "event_type": { "type": "string" }, "team_side": { "type": "string" }, "player_name": { "type": "string" }, "minute": { "type": "string", "description": "Match clock while LIVE (\"HT\" at half-time)" }, "extra_info": { "type": [ "string", "null" ] } } } } } } } }, "example": { "success": true, "fixture": { "id": 13596176, "home_id": 311, "away_id": 352, "date": "2026-10-10", "datetime": "2026-10-10 13:30:00", "kickoff_utc": "2026-10-10T11:30:00Z", "updated_at": "2026-10-11T01:43:09Z", "home_score": 2, "away_score": 1, "ht_home": 0, "ht_away": 0, "result": 1, "status": "FT", "minute": null, "stage": "", "league_id": 24, "league_name": "Premier League", "league_geo": "GB-ENG", "league_zone": "England", "home_team": "Arsenal", "home_short": "Arsenal", "home_logo": "espn-359.png", "home_geo": "", "home_stadium": "Emirates Stadium", "home_city": "London", "home_coach": "Mikel Arteta", "home_founded": 1886, "away_team": "Leeds United", "away_short": "Leeds", "away_logo": "espn-357.png", "away_geo": "", "away_stadium": "Elland Road", "away_city": "Leeds", "away_coach": "Daniel Farke", "away_founded": 1919, "penalty_home": null, "penalty_away": null, "winner": "home", "events": [ { "event_type": "goal", "team_side": "away", "player_name": "J. Justin", "minute": "55'", "extra_info": "Goal" }, { "event_type": "yellow_card", "team_side": "away", "player_name": "A. Tanaka", "minute": "36'", "extra_info": null } ] } } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/fixtures/{id}/events": { "get": { "tags": [ "Fixtures" ], "summary": "Match events: goals, cards, substitutions", "operationId": "fixtureEvents", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Fixture ID", "example": 13596176 }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "fixture_id": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "event_type": { "type": "string" }, "team_side": { "type": "string" }, "player_name": { "type": "string" }, "player_urn": { "type": "string" }, "minute": { "type": "string", "description": "Match clock while LIVE (\"HT\" at half-time)" }, "extra_info": { "type": [ "string", "null" ] } } } } } }, "example": { "success": true, "fixture_id": 13596176, "data": [ { "id": 19194470, "event_type": "goal", "team_side": "away", "player_name": "J. Justin", "player_urn": "urn:bbc:sportsdata:football:player:s-6icypdqtfk2k81ax0i49j5xpl", "minute": "55'", "extra_info": "Goal" }, { "id": 18933975, "event_type": "yellow_card", "team_side": "away", "player_name": "A. Tanaka", "player_urn": "urn:bbc:sportsdata:football:player:s-28ucbvor6b0yxreoieehudfc9", "minute": "36'", "extra_info": null } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/fixtures/{id}/stats": { "get": { "tags": [ "Fixtures" ], "summary": "Team match statistics", "operationId": "fixtureStats", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Fixture ID", "example": 13596176 }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "fixture_id": { "type": "integer" }, "available": { "type": "boolean" }, "data": { "type": "object", "properties": { "home": { "type": "object", "properties": { "shots": { "type": "integer" }, "shots_on_target": { "type": "integer" }, "shots_off_target": { "type": "integer" }, "fouls": { "type": "integer" }, "total_passes": { "type": "integer" }, "pass_accuracy": { "type": "number" }, "tackles": { "type": "integer" }, "tackle_success": { "type": "number" }, "saves": { "type": "integer" }, "yellow_cards": { "type": "integer" } } }, "away": { "type": "object", "properties": { "shots": { "type": "integer" }, "shots_on_target": { "type": "integer" }, "shots_off_target": { "type": "integer" }, "fouls": { "type": "integer" }, "total_passes": { "type": "integer" }, "pass_accuracy": { "type": "number" }, "tackles": { "type": "integer" }, "tackle_success": { "type": "integer" }, "saves": { "type": "integer" }, "yellow_cards": { "type": "integer" } } } } } } }, "example": { "success": true, "fixture_id": 13596176, "available": true, "data": { "home": { "shots": 13, "shots_on_target": 6, "shots_off_target": 7, "fouls": 12, "total_passes": 512, "pass_accuracy": 85.3, "tackles": 12, "tackle_success": 66.7, "saves": 4, "yellow_cards": 1 }, "away": { "shots": 11, "shots_on_target": 5, "shots_off_target": 6, "fouls": 20, "total_passes": 356, "pass_accuracy": 78.9, "tackles": 10, "tackle_success": 60, "saves": 4, "yellow_cards": 4 } } } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/fixtures/{id}/lineups": { "get": { "tags": [ "Fixtures" ], "summary": "Starting XI and substitutes", "operationId": "fixtureLineups", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Fixture ID", "example": 13596176 }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "fixture_id": { "type": "integer" }, "available": { "type": "boolean" }, "data": { "type": "object", "properties": { "home": { "type": "object", "properties": { "starters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "position": { "type": "string" }, "shirt": { "type": "integer" }, "is_captain": { "type": "boolean" }, "mins_played": { "type": "integer" } } } }, "subs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "position": { "type": "string" }, "shirt": { "type": "integer" }, "is_captain": { "type": "boolean" }, "mins_played": { "type": "integer" } } } } } }, "away": { "type": "object", "properties": { "starters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "position": { "type": "string" }, "shirt": { "type": "integer" }, "is_captain": { "type": "boolean" }, "mins_played": { "type": "integer" } } } }, "subs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "position": { "type": "string" }, "shirt": { "type": "integer" }, "is_captain": { "type": "boolean" }, "mins_played": { "type": "integer" } } } } } } } } } }, "example": { "success": true, "fixture_id": 13596176, "available": true, "data": { "home": { "starters": [ { "name": "David Raya", "position": "Goalkeeper", "shirt": 1, "is_captain": false, "mins_played": 90 }, { "name": "B. White", "position": "Defender", "shirt": 4, "is_captain": false, "mins_played": 63 } ], "subs": [ { "name": "P. Hincapié", "position": "Substitute", "shirt": 5, "is_captain": false, "mins_played": 8 } ] }, "away": { "starters": [ { "name": "J. Trafford", "position": "Goalkeeper", "shirt": 1, "is_captain": false, "mins_played": 90 }, { "name": "J. Bogle", "position": "Midfielder", "shirt": 2, "is_captain": false, "mins_played": 86 } ], "subs": [ { "name": "S. Longstaff", "position": "Substitute", "shirt": 8, "is_captain": false, "mins_played": 0 } ] } } } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/fixtures/h2h/{team1}/{team2}": { "get": { "tags": [ "Fixtures" ], "summary": "Head-to-head matches between two teams", "operationId": "fixturesH2h", "parameters": [ { "name": "team1", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Team ID", "example": 311 }, { "name": "team2", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Team ID", "example": 312 }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "team1": { "type": "integer" }, "team2": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "home_id": { "type": "integer" }, "away_id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "home_score": { "type": [ "integer", "null" ] }, "away_score": { "type": [ "integer", "null" ] }, "result": { "type": [ "integer", "null" ], "description": "1 home win, 0 draw, -1 away win; null until played" }, "status": { "type": "string", "enum": [ "Scheduled", "LIVE", "FT", "AET", "PENS", "Postponed", "Cancelled", "Suspended" ] }, "home_team": { "type": "string" }, "away_team": { "type": "string" }, "league_name": { "type": "string" } } } } } }, "example": { "success": true, "team1": 311, "team2": 312, "data": [ { "id": 604, "home_id": 311, "away_id": 312, "date": "2026-01-08", "home_score": 0, "away_score": 0, "result": 0, "status": "FT", "home_team": "Arsenal", "away_team": "Liverpool", "league_name": "Premier League" }, { "id": 577, "home_id": 312, "away_id": 311, "date": "2025-08-31", "home_score": 1, "away_score": 0, "result": 1, "status": "FT", "home_team": "Liverpool", "away_team": "Arsenal", "league_name": "Premier League" } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/teams/{id}": { "get": { "tags": [ "Teams" ], "summary": "Team with recent and upcoming matches and its competitions", "operationId": "teamSingle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Team ID", "example": 311 }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "team": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "short_name": { "type": "string" }, "league_id": { "type": "integer" }, "geo": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" }, "coach_name": { "type": "string" }, "stadium_name": { "type": "string" }, "founded_year": { "type": "integer" }, "logo_file": { "type": "string", "description": "Logo file name; GET /api/teams/{id}/logo returns the image" } } }, "matches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "home_id": { "type": "integer" }, "away_id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "home_score": { "type": [ "integer", "null" ] }, "away_score": { "type": [ "integer", "null" ] }, "result": { "type": [ "integer", "null" ], "description": "1 home win, 0 draw, -1 away win; null until played" }, "status": { "type": "string", "enum": [ "Scheduled", "LIVE", "FT", "AET", "PENS", "Postponed", "Cancelled", "Suspended" ] }, "league_id": { "type": "integer" }, "league_name": { "type": "string" }, "home_team": { "type": "string" }, "away_team": { "type": "string" } } } }, "leagues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } } }, "example": { "success": true, "team": { "id": 311, "name": "Arsenal", "short_name": "Arsenal", "league_id": 24, "geo": "GB-ENG", "country": "England", "city": "London", "coach_name": "Mikel Arteta", "stadium_name": "Emirates Stadium", "founded_year": 1886, "logo_file": "espn-359.png" }, "matches": [ { "id": 16096707, "home_id": 311, "away_id": 10165, "date": "2026-11-07", "home_score": null, "away_score": null, "result": null, "status": "Scheduled", "league_id": 24, "league_name": "Premier League", "home_team": "Arsenal", "away_team": "Hull City" }, { "id": 15868670, "home_id": 162, "away_id": 311, "date": "2026-11-04", "home_score": null, "away_score": null, "result": null, "status": "Scheduled", "league_id": 18, "league_name": "UEFA Champions League", "home_team": "Slavia Prague", "away_team": "Arsenal" } ], "leagues": [ { "id": 24, "name": "Premier League" }, { "id": 18, "name": "UEFA Champions League" } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/teams/{id}/logo": { "get": { "tags": [ "Teams" ], "summary": "Team logo image (a placeholder shield when there is none)", "operationId": "teamLogo", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Team ID", "example": 311 } ], "responses": { "200": { "description": "Image", "content": { "image/png": {}, "image/svg+xml": {}, "image/webp": {} } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/teams/slug/{slug}": { "get": { "tags": [ "Teams" ], "summary": "Team by slug, with league, results, upcoming matches and squad", "operationId": "teamSlug", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team slug", "example": "arsenal" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "team": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "short_name": { "type": "string" }, "slug": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" }, "geo": { "type": "string" }, "founded_year": { "type": "integer" }, "coach_name": { "type": "string" }, "stadium_name": { "type": "string" }, "logo_file": { "type": "string", "description": "Logo file name; GET /api/teams/{id}/logo returns the image" }, "league": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } } } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "home_score": { "type": "integer" }, "away_score": { "type": "integer" }, "status": { "type": "string", "enum": [ "Scheduled", "LIVE", "FT", "AET", "PENS", "Postponed", "Cancelled", "Suspended" ] }, "result": { "type": "integer", "description": "1 home win, 0 draw, -1 away win; null until played" }, "home_team": { "type": "string" }, "home_slug": { "type": "string" }, "away_team": { "type": "string" }, "away_slug": { "type": "string" }, "league_name": { "type": "string" }, "league_slug": { "type": "string" } } } }, "upcoming": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "datetime": { "type": "string", "description": "Kick-off in Central European time (CET/CEST); use kickoff_utc for UTC" }, "status": { "type": "string", "enum": [ "Scheduled", "LIVE", "FT", "AET", "PENS", "Postponed", "Cancelled", "Suspended" ] }, "home_team": { "type": "string" }, "home_slug": { "type": "string" }, "away_team": { "type": "string" }, "away_slug": { "type": "string" }, "league_name": { "type": "string" } } } }, "squad": { "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": "string" }, "position": { "type": "string" }, "jersey_number": { "type": "integer" }, "nationality": { "type": "string" }, "slug": { "type": "string" } } } } } }, "example": { "success": true, "team": { "id": 311, "name": "Arsenal", "short_name": "Arsenal", "slug": "arsenal", "country": "England", "city": "London", "geo": "GB-ENG", "founded_year": 1886, "coach_name": "Mikel Arteta", "stadium_name": "Emirates Stadium", "logo_file": "espn-359.png", "league": { "id": 24, "name": "Premier League", "slug": "premier-league" } }, "results": [ { "id": 13596176, "date": "2026-10-10", "home_score": 2, "away_score": 1, "status": "FT", "result": 1, "home_team": "Arsenal", "home_slug": "arsenal", "away_team": "Leeds United", "away_slug": "leeds-united", "league_name": "Premier League", "league_slug": "premier-league" } ], "upcoming": [ { "id": 13596702, "date": "2026-10-13", "datetime": "2026-10-13 21:00:00", "status": "Scheduled", "home_team": "Arsenal", "home_slug": "arsenal", "away_team": "Lille", "away_slug": "lille", "league_name": "UEFA Champions League" } ], "squad": [ { "full_name": "David Raya", "position": "Goalkeeper", "jersey_number": 1, "nationality": "ES", "slug": "david-raya" }, { "full_name": "Kepa Arrizabalaga", "position": "Goalkeeper", "jersey_number": 13, "nationality": "ES", "slug": "kepa-arrizabalaga" } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/teams/{id}/squad": { "get": { "tags": [ "Teams" ], "summary": "Current squad", "operationId": "teamSquad", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Team ID", "example": 311 }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "squad": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "full_name": { "type": "string" }, "position": { "type": "string" }, "jersey_number": { "type": "integer" }, "nationality": { "type": "string" }, "date_of_birth": { "type": "string", "format": "date" }, "height": { "type": "null" }, "weight": { "type": "null" } } } } } }, "example": { "success": true, "squad": [ { "id": 4904, "full_name": "David Raya", "position": "Goalkeeper", "jersey_number": 1, "nationality": "ES", "date_of_birth": "1995-09-15", "height": null, "weight": null }, { "id": 4903, "full_name": "Kepa Arrizabalaga", "position": "Goalkeeper", "jersey_number": 13, "nationality": "ES", "date_of_birth": "1994-10-03", "height": null, "weight": null } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/teams/{id}/trophies": { "get": { "tags": [ "Teams" ], "summary": "Trophy history", "operationId": "teamTrophies", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Team ID", "example": 311 }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "trophies": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer" }, "position": { "type": "integer" }, "tournament_id": { "type": "integer" }, "name": { "type": "string" }, "short_name": { "type": "null" }, "type": { "type": "string" }, "country": { "type": "null" } } } } } }, "example": { "success": true, "trophies": [ { "year": 1994, "position": 1, "tournament_id": 26, "name": "1994 UEFA Cup Winners' Cup Final", "short_name": null, "type": "domestic_league", "country": null }, { "year": 1993, "position": 1, "tournament_id": 24, "name": "1987 Football League Cup Final", "short_name": null, "type": "domestic_league", "country": null } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/standings/leagues": { "get": { "tags": [ "Standings" ], "summary": "Leagues that have a table", "operationId": "standingsLeagues", "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "zone": { "type": "string" }, "geo": { "type": "string" } } } } } }, "example": { "success": true, "data": [ { "id": 24, "name": "Premier League", "slug": "premier-league", "zone": "England", "geo": "GB-ENG" }, { "id": 1, "name": "Spanish La Liga", "slug": "spanish-la-liga", "zone": "Spain", "geo": "ES" } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/standings/{league}": { "get": { "tags": [ "Standings" ], "summary": "League table with form (last 6 matches, oldest first)", "operationId": "standingsSingle", "parameters": [ { "name": "league", "in": "path", "required": true, "schema": { "type": "string" }, "description": "League ID or slug; with a slug the response also has `league`", "example": "24" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "league": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "zone": { "type": "string" }, "geo": { "type": "string" } }, "description": "The league the table belongs to" }, "data": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "team": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "short_name": { "type": "string" }, "slug": { "type": "string" }, "logo": { "type": "string", "description": "Logo file name; GET /api/teams/{id}/logo returns the image" } } }, "played": { "type": "integer" }, "won": { "type": "integer" }, "draw": { "type": "integer" }, "lost": { "type": "integer" }, "goals_for": { "type": "integer" }, "goals_against": { "type": "integer" }, "goal_difference": { "type": "integer" }, "points": { "type": "integer" }, "form": { "type": "array", "items": { "type": "object", "properties": { "result": { "type": "string" }, "date": { "type": "string", "format": "date" }, "home_team": { "type": "string" }, "away_team": { "type": "string" }, "home_score": { "type": "integer" }, "away_score": { "type": "integer" }, "is_home": { "type": "boolean" } } } } } } } }, "required": [ "data", "league", "success" ] }, "example": { "success": true, "data": [ { "position": 1, "team": { "id": 324, "name": "Manchester City", "short_name": "Man City", "slug": "manchester-city", "logo": "espn-382.png" }, "played": 5, "won": 5, "draw": 0, "lost": 0, "goals_for": 13, "goals_against": 5, "goal_difference": 8, "points": 15, "form": [ { "result": "W", "date": "2026-09-13", "home_team": "Manchester United", "away_team": "Manchester City", "home_score": 0, "away_score": 1, "is_home": false }, { "result": "W", "date": "2026-09-20", "home_team": "Manchester City", "away_team": "Sunderland", "home_score": 5, "away_score": 3, "is_home": true } ] }, { "position": 2, "team": { "id": 311, "name": "Arsenal", "short_name": "Arsenal", "slug": "arsenal", "logo": "espn-359.png" }, "played": 6, "won": 5, "draw": 0, "lost": 1, "goals_for": 10, "goals_against": 5, "goal_difference": 5, "points": 15, "form": [ { "result": "L", "date": "2026-09-19", "home_team": "Brighton & Hove Albion", "away_team": "Arsenal", "home_score": 3, "away_score": 0, "is_home": false }, { "result": "W", "date": "2026-10-10", "home_team": "Arsenal", "away_team": "Leeds United", "home_score": 2, "away_score": 1, "is_home": true } ] } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "League not found (unknown id or slug)" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/leagues": { "get": { "tags": [ "Leagues" ], "summary": "All leagues grouped by country, with coverage", "operationId": "leaguesAll", "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "geo": { "type": "string" }, "leagues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "geo": { "type": "string" }, "domestic": { "type": "integer" }, "has_standings": { "type": "boolean" }, "has_fixtures": { "type": "boolean" }, "fixtures_count": { "type": "integer" }, "teams_count": { "type": "integer" }, "format": { "type": "string", "enum": [ "league", "cup" ], "description": "\"league\" for a round-robin competition with a table, \"cup\" for a knockout competition" } } } } } } } } }, "example": { "success": true, "data": [ { "country": "England", "geo": "GB-ENG", "leagues": [ { "id": 53, "name": "Championship", "geo": "GB-ENG", "domestic": 1, "has_standings": true, "has_fixtures": true, "fixtures_count": 737, "teams_count": 24 }, { "id": 26, "name": "English Community Shield", "geo": "GB-ENG", "domestic": 1, "has_standings": true, "has_fixtures": true, "fixtures_count": 2, "teams_count": 0 } ] } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/leagues/{id}": { "get": { "tags": [ "Leagues" ], "summary": "League with teams, upcoming fixtures and recent results", "operationId": "leagueSingle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "League ID", "example": 24 }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "integer" }, "name": { "type": "string" }, "geo": { "type": "string" }, "country": { "type": "string" }, "domestic": { "type": "integer" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "logo_file": { "type": "string", "description": "Logo file name; GET /api/teams/{id}/logo returns the image" } } } }, "upcoming_fixtures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "datetime": { "type": "string", "description": "Kick-off in Central European time (CET/CEST); use kickoff_utc for UTC" }, "home_team": { "type": "string" }, "away_team": { "type": "string" }, "stage": { "type": "string", "description": "Stage or round as the source names it (\"Group Stage\", \"1st Round\", \"Apertura\", ...); empty string when the competition has no stages" } } } }, "recent_results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "home_team": { "type": "string" }, "away_team": { "type": "string" }, "home_score": { "type": "integer" }, "away_score": { "type": "integer" }, "stage": { "type": "string", "description": "Stage or round as the source names it (\"Group Stage\", \"1st Round\", \"Apertura\", ...); empty string when the competition has no stages" } } } }, "format": { "type": "string", "enum": [ "league", "cup" ], "description": "\"league\" for a round-robin competition with a table, \"cup\" for a knockout competition" } } }, "example": { "success": true, "id": 24, "name": "Premier League", "geo": "GB-ENG", "country": "England", "domestic": 1, "teams": [ { "id": 370, "name": "AFC Bournemouth", "logo_file": "espn-349.png" }, { "id": 311, "name": "Arsenal", "logo_file": "espn-359.png" } ], "upcoming_fixtures": [ { "id": 13596518, "date": "2026-10-11", "datetime": "2026-10-11 15:00:00", "home_team": "Crystal Palace", "away_team": "Nottingham Forest" } ], "recent_results": [ { "id": 13596181, "date": "2026-10-10", "home_team": "Manchester United", "away_team": "Tottenham Hotspur", "home_score": 1, "away_score": 1 } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/leagues/{id}/topscorers": { "get": { "tags": [ "Leagues" ], "summary": "Top scorers (current season)", "operationId": "leagueTopscorers", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "League ID", "example": 24 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Rows to return, 1-100 (default 20)", "example": 20 }, { "name": "season", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`all` = every season instead of the current one" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "season_from": { "type": "string", "format": "date" }, "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "player_name": { "type": "string" }, "player_urn": { "type": "string" }, "team_id": { "type": "integer" }, "team_name": { "type": "string" }, "goals": { "type": "integer" }, "penalties": { "type": "integer" } } } } } }, "example": { "success": true, "season_from": "2026-08-21", "data": [ { "rank": 1, "player_name": "E. Haaland", "player_urn": "urn:bbc:sportsdata:football:player:s-atzboo800gv7gic2rgvgo0kq1", "team_id": 324, "team_name": "Manchester City", "goals": 5, "penalties": 0 }, { "rank": 1, "player_name": "João Pedro", "player_urn": "urn:bbc:sportsdata:football:player:s-eaqqezw2ed1u0tt3zc128mr1m", "team_id": 322, "team_name": "Chelsea", "goals": 5, "penalties": 0 } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/leagues/{id}/topassists": { "get": { "tags": [ "Leagues" ], "summary": "Top assists (current season)", "operationId": "leagueTopassists", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "League ID", "example": 24 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Rows to return, 1-100 (default 20)", "example": 20 }, { "name": "season", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`all` = every season instead of the current one" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "season_from": { "type": "string", "format": "date" }, "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "player_name": { "type": "string" }, "player_urn": { "type": "string" }, "team_id": { "type": "integer" }, "team_name": { "type": "string" }, "assists": { "type": "integer" } } } } } }, "example": { "success": true, "season_from": "2026-08-21", "data": [ { "rank": 1, "player_name": "A. Semenyo", "player_urn": "", "team_id": 324, "team_name": "Manchester City", "assists": 3 }, { "rank": 1, "player_name": "C. Palmer", "player_urn": "", "team_id": 322, "team_name": "Chelsea", "assists": 3 } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/leagues/{id}/topcards": { "get": { "tags": [ "Leagues" ], "summary": "Most cards (current season)", "operationId": "leagueTopcards", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "League ID", "example": 24 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Rows to return, 1-100 (default 20)", "example": 20 }, { "name": "season", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`all` = every season instead of the current one" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "season_from": { "type": "string", "format": "date" }, "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "player_name": { "type": "string" }, "player_urn": { "type": "string" }, "team_id": { "type": "integer" }, "team_name": { "type": "string" }, "yellow_cards": { "type": "integer" }, "red_cards": { "type": "integer" }, "total_cards": { "type": "integer" } } } } } }, "example": { "success": true, "season_from": "2026-08-21", "data": [ { "rank": 1, "player_name": "A. Fatawu", "player_urn": "urn:bbc:sportsdata:football:player:s-6cx5c6bzp1hq6c1vui53mxzx0", "team_id": 10158, "team_name": "Ipswich Town", "yellow_cards": 3, "red_cards": 1, "total_cards": 4 }, { "rank": 1, "player_name": "V. Janelt", "player_urn": "urn:bbc:sportsdata:football:player:s-9k8gysrsy1a261nhcszo4aoyx", "team_id": 366, "team_name": "Brentford", "yellow_cards": 4, "red_cards": 0, "total_cards": 4 } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/players/{slug}": { "get": { "tags": [ "Players" ], "summary": "Player profile with stats, recent matches and next match", "operationId": "playerProfile", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Player slug", "example": "bukayo-saka" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "player": { "type": "object", "properties": { "id": { "type": "integer" }, "full_name": { "type": "string" }, "slug": { "type": "string" }, "position": { "type": "string" }, "nationality": { "type": "string" }, "date_of_birth": { "type": "string", "format": "date" }, "height": { "type": "null" }, "weight": { "type": "null" }, "photo_url": { "type": "null" }, "jersey_number": { "type": "integer" }, "team_id": { "type": "integer" } } }, "team": { "type": "object", "properties": { "id": { "type": "integer" }, "full_name": { "type": "string" }, "slug": { "type": "string" }, "country": { "type": "string" }, "geo": { "type": "string" }, "league_id": { "type": "integer" } } }, "league": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "linked": { "type": "boolean" }, "career": { "type": "null" }, "season": { "type": "null" }, "rank": { "type": "null" }, "matches": { "type": "array", "items": {} }, "recent": { "type": "array", "items": {} }, "next_match": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "datetime": { "type": "string", "description": "Kick-off in Central European time (CET/CEST); use kickoff_utc for UTC" }, "home_team": { "type": "string" }, "home_slug": { "type": "string" }, "away_team": { "type": "string" }, "away_slug": { "type": "string" }, "league_name": { "type": "string" } } }, "squad": { "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": "string" }, "slug": { "type": "string" }, "position": { "type": "string" }, "jersey_number": { "type": "integer" } } } } } }, "example": { "success": true, "player": { "id": 4928, "full_name": "Bukayo Saka", "slug": "bukayo-saka", "position": "Forward", "nationality": "GB-ENG", "date_of_birth": "2001-09-05", "height": null, "weight": null, "photo_url": null, "jersey_number": 7, "team_id": 311 }, "team": { "id": 311, "full_name": "Arsenal", "slug": "arsenal", "country": "England", "geo": "GB-ENG", "league_id": 24 }, "league": { "id": 24, "name": "Premier League", "slug": "premier-league" }, "linked": false, "career": null, "season": null, "rank": null, "matches": [], "recent": [], "next_match": { "date": "2026-10-13", "datetime": "2026-10-13 21:00:00", "home_team": "Arsenal", "home_slug": "arsenal", "away_team": "Lille", "away_slug": "lille", "league_name": "UEFA Champions League" }, "squad": [ { "full_name": "David Raya", "slug": "david-raya", "position": "Goalkeeper", "jersey_number": 1 } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/players/stats": { "get": { "tags": [ "Players" ], "summary": "Per-match stats and totals by player name and team", "operationId": "playerStats", "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Player name", "example": "Bukayo Saka" }, { "name": "team_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Team ID", "example": 311 }, { "name": "shirt_number", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Optional, tells apart players with similar names" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "player": { "type": "object", "properties": { "shirt_number": { "type": "integer" }, "position": { "type": "string" }, "nationality": { "type": "string" }, "team": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } }, "totals": { "type": "object", "properties": { "appearances": { "type": "integer" }, "goals": { "type": "integer" }, "assists": { "type": "integer" }, "mins_played": { "type": "integer" }, "shots_total": { "type": "integer" }, "total_passes": { "type": "integer" }, "tackles": { "type": "integer" }, "saves": { "type": "integer" } } }, "matches": { "type": "array", "items": { "type": "object", "properties": { "goals": { "type": "integer" }, "assists": { "type": "integer" }, "mins_played": { "type": "integer" }, "shots_total": { "type": "integer" }, "total_passes": { "type": "integer" }, "tackles": { "type": "integer" }, "saves": { "type": "integer" }, "position": { "type": "string" }, "shirt_number": { "type": "integer" }, "is_starter": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "home_score": { "type": "integer" }, "away_score": { "type": "integer" }, "home_id": { "type": "integer" }, "away_id": { "type": "integer" }, "home_team": { "type": "string" }, "away_team": { "type": "string" }, "league_name": { "type": "string" } } } } } }, "example": { "success": true, "player": { "shirt_number": 7, "position": "Forward", "nationality": "GB-ENG", "team": { "id": 311, "name": "Arsenal" } }, "totals": { "appearances": 46, "goals": 12, "assists": 6, "mins_played": 2775, "shots_total": 96, "total_passes": 957, "tackles": 42, "saves": 0 }, "matches": [ { "goals": 0, "assists": 0, "mins_played": 90, "shots_total": 2, "total_passes": 34, "tackles": 1, "saves": 0, "position": "Attacking Midfielder", "shirt_number": 7, "is_starter": 1, "date": "2026-10-10", "home_score": 2, "away_score": 1, "home_id": 311, "away_id": 352, "home_team": "Arsenal", "away_team": "Leeds United", "league_name": "Premier League" } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } }, "parameters": { "IfNoneMatch": { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "ETag from an earlier response" } }, "responses": { "NotModified": { "description": "Unchanged since the ETag you sent; empty body", "headers": { "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" } } }, "example": { "success": false, "error": "API key required. Pass your key via X-Api-Key header." } } } }, "NotFound": { "description": "No such fixture, team, league or player", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" } } }, "example": { "success": false } } } }, "TooManyRequests": { "description": "Daily or monthly limit reached (see `scope`)", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per UTC day on your plan", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left today", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time of the next reset (00:00 UTC)", "schema": { "type": "integer" } }, "ETag": { "description": "Send back in If-None-Match to get 304 when unchanged", "schema": { "type": "string" } }, "X-RateLimit-Month-Limit": { "description": "Free plan only: requests allowed per calendar month (UTC)", "schema": { "type": "integer" } }, "X-RateLimit-Month-Remaining": { "description": "Free plan only: requests left this month", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the limit resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" }, "scope": { "type": "string", "enum": ["day", "month"], "description": "Which limit was reached: the daily one or the Free plan monthly one" }, "limit": { "type": "integer" }, "used": { "type": "integer" }, "reset_in": { "type": "integer", "description": "Seconds until the reset" } } }, "example": { "success": false, "error": "Daily request limit reached. Limit resets at midnight UTC.", "scope": "day", "limit": 2000, "used": 2000, "reset_in": 36000 } } } } } } }