# API-Football > Follow football with API-Football: fixtures and live scores, league tables, lineups, match events and statistics, team and player season statistics, injuries, transfers, predictions and bookmakers' odds, across more than 1,200 leagues and cups. Needs an API-Football key; the free plan allows 100 requests a day. App · Sports · 31 actions. Web page: https://docs.lodol.com/docs/integrations/api-football ## Actions ### Find coaches Find a coach by name, by the team they coach, or by ID, with their age, nationality, current team and every job on record. **Inputs** - Search (`search`, text): Optional. Only coaches whose name contains this, at least 3 characters, such as Klopp. - Team ID (`team_id`, text): Optional. The coach of this team, by team ID. - Coach ID (`coach_id`, text): Optional. Only this coach, by ID. **Outputs** - `coaches` (list): The matching coaches. - `count` (number): How many came back. **Example output** ```json { "coaches": [ { "age": 47, "birth": { "country": "Germany", "date": "1973-08-29", "place": "Krumbach" }, "career": [ { "end": null, "start": "2018-07-01", "team": { "id": 85, "logo": "https://media.api-sports.io/football/teams/85.png", "name": "PSG" } }, { "end": "2017-05-01", "start": "2015-07-01", "team": { "id": 165, "logo": "https://media.api-sports.io/football/teams/165.png", "name": "Borussia Dortmund" } } ], "firstname": "Thomas", "height": "192 cm", "id": 40, "lastname": "Tuchel", "name": "T. Tuchel", "nationality": "Germany", "photo": "https://media.api-sports.io/football/coachs/40.png", "team": { "id": 85, "logo": "https://media.api-sports.io/football/teams/85.png", "name": "PSG" }, "weight": "85 kg" } ], "count": 1 } ``` ### Find leagues and cups Find competitions by name, country, season, team or type, each with its ID, logo, country and every season on file: its dates, whether it is current, and what data it has (standings, lineups, statistics, odds and more). With no filter it lists all of the 1,200 or so. **Inputs** - Search (`search`, text): Optional. Only competitions whose name or country contains this, at least 3 characters, such as premier. Not with Country. - Country (`country`, text): Optional. Only this country, by name, such as England or Spain. Pick one from the list. - Season (`season`, number): Optional. Only this season, as the four-digit year it starts in: 2024 for the 2024/25 season. From 1900 to 2100. - League or cup (`league_type`, text): Optional. Only leagues, or only cups. One of: `league`, `cup`. - Current season only (`current_only`, true/false): Optional. Only each competition's current season, or its latest one if none is under way. Default: `false`. - Team ID (`team_id`, text): Optional. Only competitions this team has played in, by team ID. - League ID (`league_id`, text): Optional. Only this competition, by ID, such as 39 for the Premier League. **Outputs** - `count` (number): How many came back. - `leagues` (list): The matching competitions. **Example output** ```json { "count": 1, "leagues": [ { "country": { "code": "GB", "flag": "https://media.api-sports.io/flags/gb.svg", "name": "England" }, "current_season": null, "id": 39, "logo": "https://media.api-sports.io/football/leagues/2.png", "name": "Premier League", "seasons": [ { "coverage": { "fixtures": { "events": true, "lineups": true, "statistics_fixtures": false, "statistics_players": false }, "injuries": true, "odds": false, "players": true, "predictions": true, "standings": true, "top_assists": true, "top_cards": true, "top_scorers": true }, "current": false, "end": "2011-05-17", "start": "2010-08-14", "year": 2010 }, { "coverage": { "fixtures": { "events": true, "lineups": true, "statistics_fixtures": false, "statistics_players": false }, "injuries": true, "odds": false, "players": true, "predictions": true, "standings": true, "top_assists": true, "top_cards": true, "top_scorers": true }, "current": false, "end": "2012-05-13", "start": "2011-08-13", "year": 2011 } ], "type": "League" } ] } ``` ### Find players Find players by surname, or read one player's profile by ID: name, age, date and place of birth, nationality, height, weight, shirt number, position and photo. 250 players a page. **Inputs** - Surname (`search`, text): Optional. Only players whose surname contains this, at least 3 characters, such as Neymar. - Player ID (`player_id`, text): Optional. Read this player's profile, by ID, such as 276 for Neymar. - Page (`page`, number): Optional. Which page to read, from 1. When has_more is true, ask for the next page. At least 1. Default: `1`. **Outputs** - `count` (number): How many came back. - `has_more` (true/false): True when there is another page; ask for page + 1 to read it. - `page` (number): The page this is, from 1. - `players` (list): This page of players. - `total_pages` (number): How many pages there are. **Example output** ```json { "count": 1, "has_more": false, "page": 1, "players": [ { "age": 32, "birth": { "country": "Brazil", "date": "1992-02-05", "place": "Mogi das Cruzes" }, "firstname": "Neymar", "height": "175 cm", "id": 276, "injured": null, "lastname": "da Silva Santos J\u00fanior", "name": "Neymar", "nationality": "Brazil", "number": 10, "photo": "https://media.api-sports.io/football/players/276.png", "position": "Attacker", "weight": "68 kg" } ], "total_pages": 1 } ``` ### Find teams Find teams by name, league and season, country, three-letter code or venue, each with its ID, logo, founding year and home ground. A team's ID is the same in every competition. **Inputs** - Search (`search`, text): Optional. Only teams whose name or country contains this, at least 3 characters, such as manches. - League (`league_id`, text): Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Premier League. - Season (`season`, number): Optional. Only this season, as the four-digit year it starts in: 2024 for the 2024/25 season. From 1900 to 2100. - Country (`country`, text): Optional. Only this country, by name, such as England or Spain. Pick one from the list. - Team code (`code`, text): Optional. Only teams with this three-letter code, such as MUN. - Venue ID (`venue_id`, text): Optional. Only teams that play at this venue. - Team ID (`team_id`, text): Optional. Only this team, by ID, such as 33 for Manchester United. **Outputs** - `count` (number): How many came back. - `teams` (list): The matching teams. **Example output** ```json { "count": 1, "teams": [ { "code": "MUN", "country": "England", "founded": 1878, "id": 33, "logo": "https://media.api-sports.io/football/teams/33.png", "name": "Manchester United", "national": false, "venue": { "address": "Sir Matt Busby Way", "capacity": 76212, "city": "Manchester", "country": null, "id": 556, "image": "https://media.api-sports.io/football/venues/556.png", "name": "Old Trafford", "surface": "grass" } } ] } ``` ### Find venues Find stadiums by name, city or country, each with its address, capacity, pitch surface and a photo. **Inputs** - Search (`search`, text): Optional. Only venues whose name, city or country contains this, at least 3 characters, such as trafford. - City (`city`, text): Optional. Only venues in this city, such as Manchester. - Country (`country`, text): Optional. Only this country, by name, such as England or Spain. Pick one from the list. - Venue ID (`venue_id`, text): Optional. Only this venue, by ID, such as 556. **Outputs** - `count` (number): How many came back. - `venues` (list): The matching venues. **Example output** ```json { "count": 1, "venues": [ { "address": "Sir Matt Busby Way", "capacity": 76212, "city": "Manchester", "country": "England", "id": 556, "image": "https://media.api-sports.io/football/venues/556.png", "name": "Old Trafford", "surface": "grass" } ] } ``` ### Get a fixture Get one fixture by ID with everything API-Football has on it, in a single request: the score and status, the goals, cards and substitutions, both lineups, both sides' statistics, and every player's statistics and rating. **Inputs** - Fixture ID (`fixture_id`, text, required): The fixture's ID, such as 157201. List fixtures and List live fixtures return them. - Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Europe/London or America/New_York. UTC when left empty. **Outputs** - `date` (text): Kick-off, ISO 8601 with its offset. - `events` (list): Goals, cards and substitutions. Filled in when the fixture was read by ID, and for live fixtures; empty otherwise. - `goals` (object): The score now, or the final score. - `id` (number): The fixture's ID. It never changes. - `league` (object): The competition, season and round. - `lineups` (list): Both lineups. Filled in when the fixture was read by ID. - `periods` (object): When each half kicked off, as Unix seconds. - `players` (list): Both sides' player statistics. Filled in when the fixture was read by ID. - `referee` (text): The referee, e.g. Kevin Friend, England. - `score` (object): The score at each stage. - `statistics` (list): Both sides' statistics. Filled in when the fixture was read by ID. - `status` (object): Where the match is up to. - `teams` (object): Both sides. - `timestamp` (number): Kick-off, as Unix seconds. - `timezone` (text): The time zone the date is given in. - `venue` (object): Where it is played. **Example output** ```json { "date": "2019-12-26T17:30:00+00:00", "events": [], "goals": { "away": 1, "home": 4 }, "id": 157201, "league": { "country": "England", "flag": "https://media.api-sports.io/flags/gb.svg", "id": 39, "logo": "https://media.api-sports.io/football/leagues/2.png", "name": "Premier League", "round": "Regular Season - 19", "season": 2019, "standings": null }, "lineups": [], "periods": { "first": 1577381400, "second": 1577385000 }, "players": [], "referee": "Kevin Friend, England", "score": { "extratime": { "away": null, "home": null }, "fulltime": { "away": 1, "home": 4 }, "halftime": { "away": 1, "home": 3 }, "penalty": { "away": null, "home": null } }, "statistics": [], "status": { "elapsed": 90, "extra": null, "long": "Match Finished", "short": "FT" }, "teams": { "away": { "id": 34, "logo": "https://media.api-sports.io/football/teams/34.png", "name": "Newcastle", "winner": false }, "home": { "id": 33, "logo": "https://media.api-sports.io/football/teams/33.png", "name": "Manchester United", "winner": true } }, "timestamp": 1577381400, "timezone": "UTC", "venue": { "city": "Manchester", "id": 556, "name": "Old Trafford" } } ``` ### Get a team's squad Get a team's current squad: each player's ID, name, age, shirt number, position and photo. **Inputs** - Team ID (`team_id`, text, required): The team's ID, such as 33 for Manchester United or 541 for Real Madrid. Find teams looks one up. A team's ID is the same in every competition. **Outputs** - `count` (number): How many came back. - `players` (list): The squad. - `team` (object): A team. **Example output** ```json { "count": 2, "players": [ { "age": 22, "id": 20319, "name": "N. Bishop", "number": 30, "photo": "https://media.api-sports.io/football/players/20319.png", "position": "Goalkeeper" }, { "age": 31, "id": 882, "name": "David de Gea", "number": 1, "photo": "https://media.api-sports.io/football/players/882.png", "position": "Goalkeeper" } ], "team": { "id": 33, "logo": "https://media.api-sports.io/football/teams/33.png", "name": "Manchester United" } } ``` ### Get account status See the connected key's API-Football plan, when it renews, and how many of today's requests are used and left. Free for a key from API-Football's dashboard; for a RapidAPI key it costs one request and reports the daily allowance only. **Inputs**: None. **Outputs** - `active` (true/false): Whether the plan is active. Null for a RapidAPI key. - `channel` (text): Where the key is from: api-sports (API-Football's own dashboard) or rapidapi. - `daily_limit` (number): Requests the plan allows each day. - `plan` (text): The plan, e.g. Free or Pro. Null for a RapidAPI key. - `requests_remaining` (number): Requests left today. - `requests_today` (number): Requests made today. - `subscription_end` (text): When the plan renews or ends, ISO 8601. Null for a RapidAPI key. **Example output** ```json { "active": true, "channel": "api-sports", "daily_limit": 100, "plan": "Free", "requests_remaining": 88, "requests_today": 12, "subscription_end": "2020-04-10T23:24:27+00:00" } ``` ### Get fixture events Get a fixture's timeline: goals with the assist, cards, substitutions and VAR decisions, each with its minute and added time. Can narrow to one team, one player or one kind. Updated every 15 seconds during a match. **Inputs** - Fixture ID (`fixture_id`, text, required): The fixture's ID, such as 157201. List fixtures and List live fixtures return them. - Team ID (`team_id`, text): Optional. Only this team, by ID, such as 33 for Manchester United. - Player ID (`player_id`, text): Optional. Only this player, by ID, such as 276 for Neymar. - Kind (`event_type`, text): Optional. Only goals, cards, substitutions or VAR decisions. Every kind when left empty. One of: `Goal` (Goals), `Card` (Cards), `subst` (Substitutions), `Var` (VAR decisions). **Outputs** - `count` (number): How many came back. - `events` (list): The events, in the order they happened. - `fixture_id` (number): The fixture asked about. **Example output** ```json { "count": 4, "events": [ { "assist": { "id": null, "name": null }, "comments": null, "detail": "Normal Goal", "player": { "id": 6126, "name": "F. Andrada" }, "team": { "id": 463, "logo": "https://media.api-sports.io/football/teams/463.png", "name": "Aldosivi" }, "time": { "elapsed": 25, "extra": null }, "type": "Goal" }, { "assist": { "id": null, "name": null }, "comments": null, "detail": "Yellow Card", "player": { "id": 5936, "name": "Julio Gonz\u00e1lez" }, "team": { "id": 442, "logo": "https://media.api-sports.io/football/teams/442.png", "name": "Defensa Y Justicia" }, "time": { "elapsed": 33, "extra": null }, "type": "Card" }, { "assist": { "id": null, "name": null }, "comments": null, "detail": "Yellow Card", "player": { "id": 6126, "name": "Federico Andrada" }, "team": { "id": 463, "logo": "https://media.api-sports.io/football/teams/463.png", "name": "Aldosivi" }, "time": { "elapsed": 33, "extra": null }, "type": "Card" }, { "assist": { "id": null, "name": null }, "comments": null, "detail": "Yellow Card", "player": { "id": 5931, "name": "Diego Rodr\u00edguez" }, "team": { "id": 442, "logo": "https://media.api-sports.io/football/teams/442.png", "name": "Defensa Y Justicia" }, "time": { "elapsed": 36, "extra": null }, "type": "Card" } ], "fixture_id": 215662 } ``` ### Get fixture lineups Get each side's formation, coach, starting eleven with each player's place on the pitch, and substitutes. Usually there 20 to 40 minutes before kick-off; for some competitions only after the match. **Inputs** - Fixture ID (`fixture_id`, text, required): The fixture's ID, such as 157201. List fixtures and List live fixtures return them. - Team ID (`team_id`, text): Optional. Only this team, by ID, such as 33 for Manchester United. **Outputs** - `count` (number): How many came back. - `fixture_id` (number): The fixture asked about. - `lineups` (list): Each side's lineup, home side first. Empty until they are announced. **Example output** ```json { "count": 1, "fixture_id": 592872, "lineups": [ { "coach": { "id": 4, "name": "Guardiola", "photo": "https://media.api-sports.io/football/coachs/4.png" }, "formation": "4-3-3", "start_xi": [ { "grid": "1:1", "id": 617, "name": "Ederson", "number": 31, "pos": "G" }, { "grid": "2:4", "id": 627, "name": "Kyle Walker", "number": 2, "pos": "D" }, { "grid": "2:3", "id": 626, "name": "John Stones", "number": 5, "pos": "D" } ], "substitutes": [ { "grid": null, "id": 50828, "name": "Zack Steffen", "number": 13, "pos": "G" }, { "grid": null, "id": 623, "name": "Benjamin Mendy", "number": 22, "pos": "D" } ], "team": { "colors": { "goalkeeper": { "border": "99ff99", "number": "000000", "primary": "99ff99" }, "player": { "border": "99ff99", "number": "ffffff", "primary": "5badff" } }, "id": 50, "logo": "https://media.api-sports.io/football/teams/50.png", "name": "Manchester City" } } ] } ``` ### Get fixture player statistics Get every player's statistics for a fixture, side by side: minutes, rating, goals, assists, shots, passes, tackles, duels, dribbles, fouls, cards and penalties. **Inputs** - Fixture ID (`fixture_id`, text, required): The fixture's ID, such as 157201. List fixtures and List live fixtures return them. - Team ID (`team_id`, text): Optional. Only this team, by ID, such as 33 for Manchester United. **Outputs** - `count` (number): How many came back. - `fixture_id` (number): The fixture asked about. - `teams` (list): Each side's players. **Example output** ```json { "count": 1, "fixture_id": 169080, "teams": [ { "players": [ { "id": 35931, "name": "Sebasti\u00e1n Sosa", "photo": "https://media.api-sports.io/football/players/35931.png", "statistics": { "cards": { "red": 0, "yellow": 0, "yellow_red": null }, "dribbles": { "attempts": 0, "past": null, "success": 0 }, "duels": { "total": null, "won": null }, "fouls": { "committed": 0, "drawn": 0 }, "games": { "appearances": null, "captain": false, "lineups": null, "minutes": 90, "number": 13, "position": "G", "rating": 6.3, "substitute": false }, "goals": { "assists": null, "conceded": 1, "saves": 0, "total": null }, "offsides": null, "passes": { "accuracy": 68, "key": 0, "total": 17 }, "penalty": { "committed": null, "missed": 0, "saved": 0, "scored": 0, "won": null }, "shots": { "on": 0, "total": 0 }, "substitutes": { "bench": null, "in": null, "out": null }, "tackles": { "blocks": 0, "interceptions": 0, "total": null } } } ], "team": { "id": 2284, "logo": "https://media.api-sports.io/football/teams/2284.png", "name": "Monarcas" }, "updated_at": "2020-01-13T16:12:12+00:00" } ] } ``` ### Get fixture statistics Get each side's statistics for a fixture: shots on and off target, possession, passes and accuracy, fouls, corners, offsides, cards, saves and expected goals, as numbers. Can split them by half, from the 2024 season on. **Inputs** - Fixture ID (`fixture_id`, text, required): The fixture's ID, such as 157201. List fixtures and List live fixtures return them. - Team ID (`team_id`, text): Optional. Only this team, by ID, such as 33 for Manchester United. - Split by half (`include_halves`, true/false): Optional. Add each half's statistics as well as the whole match's. From the 2024 season on. Default: `false`. **Outputs** - `count` (number): How many came back. - `fixture_id` (number): The fixture asked about. - `teams` (list): Each side's statistics, home side first. **Example output** ```json { "count": 2, "fixture_id": 1299002, "teams": [ { "first_half": { "ball_possession": 54, "blocked_shots": 2, "corner_kicks": 2, "expected_goals": 1.04, "fouls": null, "goalkeeper_saves": null, "goals_prevented": null, "offsides": 2, "other": {}, "passes_accurate": 210, "passes_percentage": 83, "red_cards": null, "shots_inside_box": 7, "shots_off_goal": 3, "shots_on_goal": 4, "shots_outside_box": 2, "total_passes": 254, "total_shots": 9, "yellow_cards": 1 }, "second_half": { "ball_possession": 49, "blocked_shots": 2, "corner_kicks": 2, "expected_goals": 0.49, "fouls": null, "goalkeeper_saves": 2, "goals_prevented": null, "offsides": 1, "other": {}, "passes_accurate": 162, "passes_percentage": 81, "red_cards": null, "shots_inside_box": 4, "shots_off_goal": 1, "shots_on_goal": 3, "shots_outside_box": 2, "total_passes": 199, "total_shots": 6, "yellow_cards": 2 }, "statistics": { "ball_possession": 52, "blocked_shots": 4, "corner_kicks": 4, "expected_goals": 1.53, "fouls": 17, "goalkeeper_saves": 2, "goals_prevented": 2, "offsides": 3, "other": {}, "passes_accurate": 372, "passes_percentage": 82, "red_cards": null, "shots_inside_box": 11, "shots_off_goal": 4, "shots_on_goal": 7, "shots_outside_box": 4, "total_passes": 453, "total_shots": 15, "yellow_cards": 3 }, "team": { "id": 571, "logo": "https://media.api-sports.io/football/teams/571.png", "name": "Red Bull Salzburg" } }, { "first_half": { "ball_possession": 46, "blocked_shots": 1, "corner_kicks": null, "expected_goals": 0.67, "fouls": null, "goalkeeper_saves": 4, "goals_prevented": null, "offsides": null, "other": {}, "passes_accurate": 170, "passes_percentage": 78, "red_cards": null, "shots_inside_box": 4, "shots_off_goal": 2, "shots_on_goal": 1, "shots_outside_box": null, "total_passes": 218, "total_shots": 4, "yellow_cards": 2 }, "second_half": { "ball_possession": 51, "blocked_shots": 1, "corner_kicks": null, "expected_goals": 1.09, "fouls": null, "goalkeeper_saves": 3, "goals_prevented": null, "offsides": null, "other": {}, "passes_accurate": 169, "passes_percentage": 81, "red_cards": null, "shots_inside_box": 5, "shots_off_goal": 3, "shots_on_goal": 5, "shots_outside_box": 4, "total_passes": 208, "total_shots": 9, "yellow_cards": null }, "statistics": { "ball_possession": 48, "blocked_shots": 2, "corner_kicks": null, "expected_goals": 1.76, "fouls": 11, "goalkeeper_saves": 7, "goals_prevented": 2, "offsides": null, "other": {}, "passes_accurate": 339, "passes_percentage": 80, "red_cards": null, "shots_inside_box": 9, "shots_off_goal": 5, "shots_on_goal": 6, "shots_outside_box": 4, "total_passes": 426, "total_shots": 13, "yellow_cards": 2 }, "team": { "id": 106, "logo": "https://media.api-sports.io/football/teams/106.png", "name": "Stade Brestois 29" } } ] } ``` ### Get live odds Get in-play odds for fixtures under way, or one fixture, league or bet type, with the score and clock they were priced at and whether betting is paused. Fixtures appear shortly before kick-off and none are kept once a match ends. **Inputs** - Fixture ID (`fixture_id`, text): Optional. Only this fixture's odds. - League (`league_id`, text): Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Premier League. - Bet type (`bet_id`, text): Optional. Only this bet type, such as Asian Handicap. Pick one from the list: in-play bet types only. **Outputs** - `count` (number): How many came back. - `fixtures` (list): The fixtures and their odds. **Example output** ```json { "count": 1, "fixtures": [ { "fixture": { "id": 721238, "status": { "elapsed": 62, "long": "Second Half", "seconds": "62:14" } }, "league": { "id": 30, "season": 2022 }, "odds": [ { "id": 20, "name": "Match Corners", "values": [ { "handicap": "8", "main": null, "odd": 2.5, "suspended": false, "value": "Over" }, { "handicap": "8", "main": null, "odd": 4.333, "suspended": false, "value": "Exactly" } ] }, { "id": 33, "name": "Asian Handicap", "values": [ { "handicap": "-1", "main": false, "odd": 1.475, "suspended": false, "value": "Home" }, { "handicap": "1", "main": false, "odd": 2.6, "suspended": false, "value": "Away" } ] } ], "status": { "blocked": false, "finished": false, "stopped": false }, "teams": { "away": { "goals": 0, "id": 1565 }, "home": { "goals": 1, "id": 1563 } }, "updated_at": "2022-01-27T16:21:01+00:00" } ] } ``` ### Get player statistics Get players' season statistics, a line per team and competition: appearances, minutes, rating, goals, assists, shots, passes, tackles, duels, dribbles, fouls, cards and penalties. For a player, or a team's or league's players, with a season; 20 players a page. **Inputs** - Player ID (`player_id`, text): Optional. This player, by ID, such as 276 for Neymar. Pair it with a season. - Team ID (`team_id`, text): Optional. This team's players, by ID. Pair it with a season. - League (`league_id`, text): Optional. This competition's players. Pair it with a season. - Season (`season`, number): Optional. Only this season, as the four-digit year it starts in: 2024 for the 2024/25 season. From 1900 to 2100. - Search (`search`, text): Optional. Only players whose name contains this, together with a team or league, such as cavani. - Page (`page`, number): Optional. Which page to read, from 1. When has_more is true, ask for the next page. At least 1. Default: `1`. **Outputs** - `count` (number): How many came back. - `has_more` (true/false): True when there is another page; ask for page + 1 to read it. - `page` (number): The page this is, from 1. - `players` (list): This page of players. - `total_pages` (number): How many pages there are. **Example output** ```json { "count": 1, "has_more": false, "page": 1, "players": [ { "player": { "age": 28, "birth": { "country": "Brazil", "date": "1992-02-05", "place": "Mogi das Cruzes" }, "firstname": "Neymar", "height": "175 cm", "id": 276, "injured": false, "lastname": "da Silva Santos J\u00fanior", "name": "Neymar", "nationality": "Brazil", "number": null, "photo": "https://media.api-sports.io/football/players/276.png", "position": null, "weight": "68 kg" }, "statistics": [ { "cards": { "red": 0, "yellow": 3, "yellow_red": 1 }, "dribbles": { "attempts": 143, "past": null, "success": 88 }, "duels": { "total": null, "won": null }, "fouls": { "committed": 14, "drawn": 62 }, "games": { "appearances": 15, "captain": false, "lineups": 15, "minutes": 1322, "number": null, "position": "Attacker", "rating": 8.053333, "substitute": null }, "goals": { "assists": 6, "conceded": null, "saves": 0, "total": 13 }, "league": { "country": "France", "flag": "https://media.api-sports.io/flags/fr.svg", "id": 61, "logo": "https://media.api-sports.io/football/leagues/61.png", "name": "Ligue 1", "season": 2019 }, "offsides": null, "passes": { "accuracy": 79, "key": 39, "total": 704 }, "penalty": { "committed": null, "missed": 1, "saved": null, "scored": 4, "won": 1 }, "shots": { "on": 36, "total": 70 }, "substitutes": { "bench": 0, "in": 0, "out": 3 }, "tackles": { "blocks": 0, "interceptions": 4, "total": 13 }, "team": { "id": 85, "logo": "https://media.api-sports.io/football/teams/85.png", "name": "Paris Saint Germain" } } ] } ], "total_pages": 1 } ``` ### Get pre-match odds Get bookmakers' pre-match odds for a fixture, a league and season, or a day, optionally from one bookmaker or for one bet type. Odds appear 1 to 14 days before kick-off and are kept for 7 days. 10 fixtures a page. **Inputs** - Fixture ID (`fixture_id`, text): Optional. Only this fixture's odds. - League (`league_id`, text): Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Premier League. - Season (`season`, number): Optional. Only this season, as the four-digit year it starts in: 2024 for the 2024/25 season. From 1900 to 2100. - Date (`on_date`, date): Optional. Only fixtures on this day. - Bookmaker (`bookmaker_id`, text): Optional. Only this bookmaker's odds. Pick one from the list. - Bet type (`bet_id`, text): Optional. Only this bet type, such as Match Winner. Pick one from the list: pre-match bet types only. - Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Europe/London or America/New_York. UTC when left empty. - Page (`page`, number): Optional. Which page to read, from 1. When has_more is true, ask for the next page. At least 1. Default: `1`. **Outputs** - `count` (number): How many came back. - `fixtures` (list): This page of fixtures and their odds. - `has_more` (true/false): True when there is another page; ask for page + 1 to read it. - `page` (number): The page this is, from 1. - `total_pages` (number): How many pages there are. **Example output** ```json { "count": 1, "fixtures": [ { "bookmakers": [ { "bets": [ { "id": 38, "name": "Exact Goals Number", "values": [ { "odd": 7.0, "value": "4" }, { "odd": 4.4, "value": "3" } ] }, { "id": 20, "name": "Double Chance - First Half", "values": [ { "odd": 1.2, "value": "Home/Draw" }, { "odd": 1.75, "value": "Home/Away" } ] } ], "id": 6, "name": "Bwin" } ], "fixture": { "date": "2020-05-15T15:00:00+00:00", "id": 326090, "timestamp": 1589554800, "timezone": "UTC" }, "league": { "country": "Belarus", "flag": "https://media.api-sports.io/flags/by.svg", "id": 116, "logo": "https://media.api-sports.io/football/leagues/116.png", "name": "Vysshaya Liga", "season": 2020 }, "updated_at": "2020-05-15T09:49:32+00:00" } ], "has_more": false, "page": 1, "total_pages": 1 } ``` ### Get predictions Get API-Football's forecast for a fixture: the likely winner, the chance of a home win, draw and away win, goal lines, advice in words, how the two sides compare on form, attack and defence, and their previous meetings. Based on statistics, not bookmakers' odds. **Inputs** - Fixture ID (`fixture_id`, text, required): The fixture's ID, such as 157201. List fixtures and List live fixtures return them. **Outputs** - `advice` (text): The advice in words, e.g. Double chance : Deportivo Santani or draw. - `comparison` (object): How the two sides compare. - `fixture_id` (number): The fixture asked about. - `goals` (object): Each side's goals line, in the same notation. - `h2h` (list): The two sides' previous meetings, as fixtures. - `league` (object): The competition and season. - `percent` (object): The chance of each result, as a percentage. - `teams` (object): Both sides. - `under_over` (text): The goals line, e.g. -3.5 for at most 3 goals or +2.5 for at least 3. - `win_or_draw` (true/false): True if the pick is that team winning or drawing. - `winner` (object): Who API-Football expects to come out on top. **Example output** ```json { "advice": "Double chance : Fulham or draw", "comparison": { "att": { "away": 38, "home": 63 }, "def": { "away": 44, "home": 56 }, "form": { "away": 33, "home": 67 }, "goals": { "away": 67, "home": 33 }, "h2h": { "away": 80, "home": 20 }, "poisson_distribution": { "away": 44, "home": 56 }, "total": { "away": 51.0, "home": 49.2 } }, "fixture_id": 1208247, "goals": { "away": "-2.5", "home": "-2.5" }, "h2h": [ { "date": "2024-08-16T19:00:00+00:00", "events": [], "goals": { "away": 0, "home": 1 }, "id": 1208021, "league": { "country": "England", "flag": "https://media.api-sports.io/flags/gb-eng.svg", "id": 39, "logo": "https://media.api-sports.io/football/leagues/39.png", "name": "Premier League", "round": "Regular Season - 1", "season": 2024, "standings": true }, "lineups": [], "periods": { "first": 1723834800, "second": 1723838400 }, "players": [], "referee": "R. Jones", "score": { "extratime": { "away": null, "home": null }, "fulltime": { "away": 0, "home": 1 }, "halftime": { "away": 0, "home": 0 }, "penalty": { "away": null, "home": null } }, "statistics": [], "status": { "elapsed": 90, "extra": null, "long": "Match Finished", "short": "FT" }, "teams": { "away": { "id": 36, "logo": "https://media.api-sports.io/football/teams/36.png", "name": "Fulham", "winner": false }, "home": { "id": 33, "logo": "https://media.api-sports.io/football/teams/33.png", "name": "Manchester United", "winner": true } }, "timestamp": 1723834800, "timezone": "UTC", "venue": { "city": "Manchester", "id": 556, "name": "Old Trafford" } }, { "date": "2024-02-24T15:00:00+00:00", "events": [], "goals": { "away": 2, "home": 1 }, "id": 1035431, "league": { "country": "England", "flag": "https://media.api-sports.io/flags/gb-eng.svg", "id": 39, "logo": "https://media.api-sports.io/football/leagues/39.png", "name": "Premier League", "round": "Regular Season - 26", "season": 2023, "standings": true }, "lineups": [], "periods": { "first": 1708786800, "second": 1708790400 }, "players": [], "referee": "M. Oliver", "score": { "extratime": { "away": null, "home": null }, "fulltime": { "away": 2, "home": 1 }, "halftime": { "away": 0, "home": 0 }, "penalty": { "away": null, "home": null } }, "statistics": [], "status": { "elapsed": 90, "extra": null, "long": "Match Finished", "short": "FT" }, "teams": { "away": { "id": 36, "logo": "https://media.api-sports.io/football/teams/36.png", "name": "Fulham", "winner": true }, "home": { "id": 33, "logo": "https://media.api-sports.io/football/teams/33.png", "name": "Manchester United", "winner": false } }, "timestamp": 1708786800, "timezone": "UTC", "venue": { "city": "Manchester", "id": 556, "name": "Old Trafford" } } ], "league": { "country": "England", "flag": "https://media.api-sports.io/flags/gb-eng.svg", "id": 39, "logo": "https://media.api-sports.io/football/leagues/39.png", "name": "Premier League", "season": 2024 }, "percent": { "away": 30, "draw": 35, "home": 35 }, "teams": { "away": { "id": 33, "last_5": { "att": 46, "def": 23, "form": 27, "goals": { "against": { "average": 2.0, "total": 10 }, "for": { "average": 1.2, "total": 6 } }, "played": 5 }, "logo": "https://media.api-sports.io/football/teams/33.png", "name": "Manchester United", "season": { "biggest": { "goals": { "against": { "away": 2, "home": 3 }, "for": { "away": 3, "home": 4 } }, "losses": { "away": "2-0", "home": "0-3" }, "streak": { "draws": 1, "losses": 3, "wins": 1 }, "wins": { "away": "0-3", "home": "4-0" } }, "cards": { "red": [ { "minute": "0-15", "percentage": null, "total": null }, { "minute": "16-30", "percentage": null, "total": null }, { "minute": "31-45", "percentage": 50.0, "total": 1 }, { "minute": "46-60", "percentage": 50.0, "total": 1 }, { "minute": "61-75", "percentage": null, "total": null }, { "minute": "76-90", "percentage": null, "total": null }, { "minute": "91-105", "percentage": null, "total": null }, { "minute": "106-120", "percentage": null, "total": null } ], "yellow": [ { "minute": "0-15", "percentage": 3.77, "total": 2 }, { "minute": "16-30", "percentage": 9.43, "total": 5 }, { "minute": "31-45", "percentage": 22.64, "total": 12 }, { "minute": "46-60", "percentage": 30.19, "total": 16 }, { "minute": "61-75", "percentage": 20.75, "total": 11 }, { "minute": "76-90", "percentage": 5.66, "total": 3 }, { "minute": "91-105", "percentage": 7.55, "total": 4 }, { "minute": "106-120", "percentage": null, "total": null } ] }, "clean_sheet": { "away": 3, "home": 3, "total": 6 }, "failed_to_score": { "away": 4, "home": 4, "total": 8 }, "fixtures": { "draws": { "away": 4, "home": 1, "total": 5 }, "losses": { "away": 4, "home": 6, "total": 10 }, "played": { "away": 10, "home": 12, "total": 22 }, "wins": { "away": 2, "home": 5, "total": 7 } }, "form": "WLLWDLDWLDWDWLLWLLLDWL", "goals": { "against": { "average": { "away": 1.2, "home": 1.7, "total": 1.5 }, "minute": [ { "minute": "0-15", "percentage": 12.5, "total": 4 }, { "minute": "16-30", "percentage": 6.25, "total": 2 }, { "minute": "31-45", "percentage": 18.75, "total": 6 }, { "minute": "46-60", "percentage": 28.13, "total": 9 }, { "minute": "61-75", "percentage": 18.75, "total": 6 }, { "minute": "76-90", "percentage": 6.25, "total": 2 }, { "minute": "91-105", "percentage": 9.38, "total": 3 }, { "minute": "106-120", "percentage": null, "total": null } ], "total": { "away": 12, "home": 20, "total": 32 }, "under_over": [ { "line": 0.5, "over": 16, "under": 6 }, { "line": 1.5, "over": 11, "under": 11 }, { "line": 2.5, "over": 5, "under": 17 }, { "line": 3.5, "over": 0, "under": 22 }, { "line": 4.5, "over": 0, "under": 22 } ] }, "for": { "average": { "away": 1.0, "home": 1.4, "total": 1.2 }, "minute": [ { "minute": "0-15", "percentage": 3.7, "total": 1 }, { "minute": "16-30", "percentage": 11.11, "total": 3 }, { "minute": "31-45", "percentage": 18.52, "total": 5 }, { "minute": "46-60", "percentage": 14.81, "total": 4 }, { "minute": "61-75", "percentage": 14.81, "total": 4 }, { "minute": "76-90", "percentage": 29.63, "total": 8 }, { "minute": "91-105", "percentage": 7.41, "total": 2 }, { "minute": "106-120", "percentage": null, "total": null } ], "total": { "away": 10, "home": 17, "total": 27 }, "under_over": [ { "line": 0.5, "over": 14, "under": 8 }, { "line": 1.5, "over": 8, "under": 14 }, { "line": 2.5, "over": 4, "under": 18 }, { "line": 3.5, "over": 1, "under": 21 }, { "line": 4.5, "over": 0, "under": 22 } ] } }, "lineups": [ { "formation": "4-2-3-1", "played": 11 }, { "formation": "3-4-2-1", "played": 10 }, { "formation": "3-4-3", "played": 1 } ], "penalty": { "missed": { "percentage": 0, "total": 0 }, "scored": { "percentage": 100.0, "total": 3 }, "total": 3 } } }, "home": { "id": 36, "last_5": { "att": 77, "def": 38, "form": 53, "goals": { "against": { "average": 1.6, "total": 8 }, "for": { "average": 2.0, "total": 10 } }, "played": 5 }, "logo": "https://media.api-sports.io/football/teams/36.png", "name": "Fulham", "season": { "biggest": { "goals": { "against": { "away": 3, "home": 4 }, "for": { "away": 2, "home": 3 } }, "losses": { "away": "3-2", "home": "1-4" }, "streak": { "draws": 3, "losses": 2, "wins": 2 }, "wins": { "away": "0-2", "home": "3-1" } }, "cards": { "red": [ { "minute": "0-15", "percentage": null, "total": null }, { "minute": "16-30", "percentage": null, "total": null }, { "minute": "31-45", "percentage": null, "total": null }, { "minute": "46-60", "percentage": null, "total": null }, { "minute": "61-75", "percentage": 50.0, "total": 1 }, { "minute": "76-90", "percentage": 50.0, "total": 1 }, { "minute": "91-105", "percentage": null, "total": null }, { "minute": "106-120", "percentage": null, "total": null } ], "yellow": [ { "minute": "0-15", "percentage": 3.92, "total": 2 }, { "minute": "16-30", "percentage": 7.84, "total": 4 }, { "minute": "31-45", "percentage": 11.76, "total": 6 }, { "minute": "46-60", "percentage": 21.57, "total": 11 }, { "minute": "61-75", "percentage": 17.65, "total": 9 }, { "minute": "76-90", "percentage": 17.65, "total": 9 }, { "minute": "91-105", "percentage": 19.61, "total": 10 }, { "minute": "106-120", "percentage": null, "total": null } ] }, "clean_sheet": { "away": 3, "home": 1, "total": 4 }, "failed_to_score": { "away": 1, "home": 1, "total": 2 }, "fixtures": { "draws": { "away": 4, "home": 5, "total": 9 }, "losses": { "away": 3, "home": 2, "total": 5 }, "played": { "away": 11, "home": 11, "total": 22 }, "wins": { "away": 4, "home": 4, "total": 8 } }, "form": "LWDDWWLLDWWLDWDDDWDDLW", "goals": { "against": { "average": { "away": 1.2, "home": 1.5, "total": 1.4 }, "minute": [ { "minute": "0-15", "percentage": 6.67, "total": 2 }, { "minute": "16-30", "percentage": 6.67, "total": 2 }, { "minute": "31-45", "percentage": 20.0, "total": 6 }, { "minute": "46-60", "percentage": 30.0, "total": 9 }, { "minute": "61-75", "percentage": 6.67, "total": 2 }, { "minute": "76-90", "percentage": 20.0, "total": 6 }, { "minute": "91-105", "percentage": 10.0, "total": 3 }, { "minute": "106-120", "percentage": null, "total": null } ], "total": { "away": 13, "home": 17, "total": 30 }, "under_over": [ { "line": 0.5, "over": 18, "under": 4 }, { "line": 1.5, "over": 7, "under": 15 }, { "line": 2.5, "over": 4, "under": 18 }, { "line": 3.5, "over": 1, "under": 21 }, { "line": 4.5, "over": 0, "under": 22 } ] }, "for": { "average": { "away": 1.5, "home": 1.6, "total": 1.5 }, "minute": [ { "minute": "0-15", "percentage": 14.71, "total": 5 }, { "minute": "16-30", "percentage": 14.71, "total": 5 }, { "minute": "31-45", "percentage": 5.88, "total": 2 }, { "minute": "46-60", "percentage": 11.76, "total": 4 }, { "minute": "61-75", "percentage": 20.59, "total": 7 }, { "minute": "76-90", "percentage": 17.65, "total": 6 }, { "minute": "91-105", "percentage": 14.71, "total": 5 }, { "minute": "106-120", "percentage": null, "total": null } ], "total": { "away": 16, "home": 18, "total": 34 }, "under_over": [ { "line": 0.5, "over": 20, "under": 2 }, { "line": 1.5, "over": 12, "under": 10 }, { "line": 2.5, "over": 2, "under": 20 }, { "line": 3.5, "over": 0, "under": 22 }, { "line": 4.5, "over": 0, "under": 22 } ] } }, "lineups": [ { "formation": "4-2-3-1", "played": 17 }, { "formation": "4-5-1", "played": 2 }, { "formation": "4-3-3", "played": 1 }, { "formation": "5-4-1", "played": 1 }, { "formation": "3-4-3", "played": 1 } ], "penalty": { "missed": { "percentage": 25.0, "total": 1 }, "scored": { "percentage": 75.0, "total": 3 }, "total": 4 } } } }, "under_over": null, "win_or_draw": true, "winner": { "comment": "Win or draw", "id": 36, "name": "Fulham" } } ``` ### Get standings Get a league table: each team's rank, points, goal difference, form, and home and away record, and what each place leads to (the Champions League, relegation and so on). A group stage has a table per group. Give a team instead of a league for its line in every competition it plays. **Inputs** - Season (`season`, number, required): The season, as the four-digit year it starts in: 2024 for the Premier League's 2024/25 season, or 2025 for a league played within 2025. The free plan covers a few recent seasons only. From 1900 to 2100. - League (`league_id`, text): Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Premier League. - Team ID (`team_id`, text): Optional. Only this team's line, by ID: in every competition it plays unless a league is set. **Outputs** - `count` (number): How many came back. - `standings` (list): One table per league and group. For a league, standings[0].table is the table. **Example output** ```json { "count": 1, "standings": [ { "group": "Premier League", "league": { "country": "England", "flag": "https://media.api-sports.io/flags/gb.svg", "id": 39, "logo": "https://media.api-sports.io/football/leagues/2.png", "name": "Premier League", "season": 2019 }, "table": [ { "all": { "draw": 1, "goals": { "against": 15, "for": 56 }, "lose": 0, "played": 24, "win": 23 }, "away": { "draw": 1, "goals": { "against": 6, "for": 25 }, "lose": 0, "played": 12, "win": 11 }, "description": "Promotion - Champions League (Group Stage)", "form": "WWWWW", "goals_diff": 41, "group": "Premier League", "home": { "draw": 0, "goals": { "against": 9, "for": 31 }, "lose": 0, "played": 12, "win": 12 }, "points": 70, "rank": 1, "status": "same", "team": { "id": 40, "logo": "https://media.api-sports.io/football/teams/40.png", "name": "Liverpool" }, "updated_at": "2020-01-29T00:00:00+00:00" } ] } ] } ``` ### Get team statistics Get a team's season in one competition: matches won, drawn and lost home and away, goals scored and conceded with averages and when they came, clean sheets, biggest wins, longest runs, penalties, formations used and cards. Set a date to see the season up to that day. **Inputs** - League (`league_id`, text, required): The competition, such as 39 for the Premier League, 140 for La Liga or 2 for the Champions League. Pick one from the list, or pass a league ID from an earlier step. - Season (`season`, number, required): The season, as the four-digit year it starts in: 2024 for the Premier League's 2024/25 season, or 2025 for a league played within 2025. The free plan covers a few recent seasons only. From 1900 to 2100. - Team ID (`team_id`, text, required): The team's ID, such as 33 for Manchester United or 541 for Real Madrid. Find teams looks one up. A team's ID is the same in every competition. - Up to date (`on_date`, date): Optional. Count only the matches up to this day, for the team's record at that point of the season. **Outputs** - `biggest` (object): The season's longest runs, biggest wins and losses, and most goals. - `cards` (object): Cards by 15-minute spell. - `clean_sheet` (object): Matches without conceding. - `failed_to_score` (object): Matches without scoring. - `fixtures` (object): Matches played, won, drawn and lost. - `form` (text): Results in order, oldest first: W, D or L for each match. - `goals` (object): Goals scored and conceded. - `league` (object): The competition and season. - `lineups` (list): Formations used, most used first. - `penalty` (object): Penalties taken. - `team` (object): A team. **Example output** ```json { "biggest": { "goals": { "against": { "away": 3, "home": 2 }, "for": { "away": 3, "home": 5 } }, "losses": { "away": "2-0", "home": "0-2" }, "streak": { "draws": 2, "losses": 2, "wins": 4 }, "wins": { "away": "0-3", "home": "4-0" } }, "cards": { "red": [ { "minute": "0-15", "percentage": null, "total": null }, { "minute": "16-30", "percentage": null, "total": null }, { "minute": "31-45", "percentage": null, "total": null }, { "minute": "46-60", "percentage": null, "total": null }, { "minute": "61-75", "percentage": null, "total": null }, { "minute": "76-90", "percentage": null, "total": null }, { "minute": "91-105", "percentage": null, "total": null }, { "minute": "106-120", "percentage": null, "total": null } ], "yellow": [ { "minute": "0-15", "percentage": 6.85, "total": 5 }, { "minute": "16-30", "percentage": 6.85, "total": 5 }, { "minute": "31-45", "percentage": 21.92, "total": 16 }, { "minute": "46-60", "percentage": 16.44, "total": 12 }, { "minute": "61-75", "percentage": 19.18, "total": 14 }, { "minute": "76-90", "percentage": 28.77, "total": 21 }, { "minute": "91-105", "percentage": null, "total": null }, { "minute": "106-120", "percentage": null, "total": null } ] }, "clean_sheet": { "away": 6, "home": 7, "total": 13 }, "failed_to_score": { "away": 6, "home": 2, "total": 8 }, "fixtures": { "draws": { "away": 5, "home": 7, "total": 12 }, "losses": { "away": 6, "home": 2, "total": 8 }, "played": { "away": 19, "home": 19, "total": 38 }, "wins": { "away": 8, "home": 10, "total": 18 } }, "form": "WDLDWLDLDWLWDDWWDLWWLWLLDWWDWDWWWWDWDW", "goals": { "against": { "average": { "away": 1.0, "home": 0.9, "total": 0.9 }, "minute": [ { "minute": "0-15", "percentage": 16.67, "total": 6 }, { "minute": "16-30", "percentage": 8.33, "total": 3 }, { "minute": "31-45", "percentage": 19.44, "total": 7 }, { "minute": "46-60", "percentage": 25.0, "total": 9 }, { "minute": "61-75", "percentage": 8.33, "total": 3 }, { "minute": "76-90", "percentage": 13.89, "total": 5 }, { "minute": "91-105", "percentage": 8.33, "total": 3 }, { "minute": "106-120", "percentage": null, "total": null } ], "total": { "away": 19, "home": 17, "total": 36 }, "under_over": [ { "line": 0.5, "over": 25, "under": 13 }, { "line": 1.5, "over": 10, "under": 28 }, { "line": 2.5, "over": 1, "under": 37 }, { "line": 3.5, "over": 0, "under": 38 }, { "line": 4.5, "over": 0, "under": 38 } ] }, "for": { "average": { "away": 1.4, "home": 2.1, "total": 1.7 }, "minute": [ { "minute": "0-15", "percentage": 6.06, "total": 4 }, { "minute": "16-30", "percentage": 25.76, "total": 17 }, { "minute": "31-45", "percentage": 16.67, "total": 11 }, { "minute": "46-60", "percentage": 19.7, "total": 13 }, { "minute": "61-75", "percentage": 15.15, "total": 10 }, { "minute": "76-90", "percentage": 12.12, "total": 8 }, { "minute": "91-105", "percentage": 4.55, "total": 3 }, { "minute": "106-120", "percentage": null, "total": null } ], "total": { "away": 26, "home": 40, "total": 66 }, "under_over": [ { "line": 0.5, "over": 30, "under": 8 }, { "line": 1.5, "over": 20, "under": 18 }, { "line": 2.5, "over": 11, "under": 27 }, { "line": 3.5, "over": 4, "under": 34 }, { "line": 4.5, "over": 1, "under": 37 } ] } }, "league": { "country": "England", "flag": "https://media.api-sports.io/flags/gb-eng.svg", "id": 39, "logo": "https://media.api-sports.io/football/leagues/39.png", "name": "Premier League", "season": 2019 }, "lineups": [ { "formation": "4-2-3-1", "played": 32 }, { "formation": "3-4-1-2", "played": 4 } ], "penalty": { "missed": { "percentage": 0, "total": 0 }, "scored": { "percentage": 100.0, "total": 10 }, "total": 10 }, "team": { "id": 33, "logo": "https://media.api-sports.io/football/teams/33.png", "name": "Manchester United" } } ``` ### List a player's teams List every team a player has played for, clubs and national sides, with the seasons at each. **Inputs** - Player ID (`player_id`, text, required): The player's ID, such as 276 for Neymar. Find players looks one up. A player's ID is the same at every team. **Outputs** - `count` (number): How many came back. - `player_id` (number): The player asked about. - `teams` (list): The teams, with the seasons at each. **Example output** ```json { "count": 2, "player_id": 276, "teams": [ { "seasons": [ 2026, 2023, 2022 ], "team": { "id": 6, "logo": "https://media.api-sports.io/football/teams/6.png", "name": "Brazil" } }, { "seasons": [ 2024, 2023 ], "team": { "id": 2932, "logo": "https://media.api-sports.io/football/teams/2932.png", "name": "Al-Hilal Saudi FC" } } ] } ``` ### List bet types List the bet types of pre-match or in-play odds, such as Match Winner or Goals Over/Under, with the IDs the odds actions filter on. The two kinds of odds number their bet types separately. **Inputs** - Odds (`odds_type`, text): Optional. Pre-match or in-play bet types. Pre-match when left empty. One of: `pre_match` (Pre-match odds), `live` (In-play (live) odds). Default: `pre_match`. - Search (`search`, text): Optional. Only bet types whose name contains this, at least 3 characters, such as under. **Outputs** - `bets` (list): The bet types. - `count` (number): How many came back. - `odds_type` (text): pre_match or live. **Example output** ```json { "bets": [ { "id": 5, "name": "Goals Over/Under" }, { "id": 6, "name": "Goals Over/Under First Half" } ], "count": 2, "odds_type": "pre_match" } ``` ### List bookmakers List the bookmakers API-Football has odds from, with the IDs the odds actions filter on. **Inputs** - Search (`search`, text): Optional. Only bookmakers whose name contains this, at least 3 characters, such as Bet. **Outputs** - `bookmakers` (list): The bookmakers. - `count` (number): How many came back. **Example output** ```json { "bookmakers": [ { "id": 1, "name": "10Bet" }, { "id": 2, "name": "Marathonbet" } ], "count": 2 } ``` ### List countries List the countries that have competitions in API-Football, each with its code and flag. The names are what the Country filters elsewhere take. **Inputs** - Search (`search`, text): Optional. Only countries whose name contains this, at least 3 characters, such as engl. - Country code (`code`, text): Optional. Only the country with this code, such as GB, FR or GB-ENG. **Outputs** - `count` (number): How many came back. - `countries` (list): The countries, by name. **Example output** ```json { "count": 1, "countries": [ { "code": "GB", "flag": "https://media.api-sports.io/flags/gb.svg", "name": "England" } ] } ``` ### List fixtures List fixtures and results by day or date range, league and season, team, round, venue or status, or a team's or league's last or next few. Each has its kick-off, status, venue, referee, teams, and the score at half time, full time, extra time and penalties. **Inputs** - League (`league_id`, text): Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Premier League. - Season (`season`, number): Optional. Only this season, as the four-digit year it starts in: 2024 for the 2024/25 season. From 1900 to 2100. - Team ID (`team_id`, text): Optional. Only this team, by ID, such as 33 for Manchester United. - Date (`on_date`, date): Optional. Only fixtures on this day. - From date (`date_from`, date): Optional. Only fixtures on or after this day. Set together with To date. - To date (`date_to`, date): Optional. Only fixtures on or before this day. Set together with From date. - Round (`round`, text): Optional. Only this round, by name, such as Regular Season - 1. List rounds names them. - Status (`status`, list): Optional. Only fixtures in these states, such as Not started (NS) or Finished (FT). Every state when none is chosen. One or more of: `TBD` (Time to be defined (TBD)), `NS` (Not started (NS)), `1H` (First half (1H)), `HT` (Half time (HT)), `2H` (Second half (2H)), `ET` (Extra time (ET)), `BT` (Break before extra time or penalties (BT)), `P` (Penalty shootout in progress (P)), `SUSP` (Suspended (SUSP)), `INT` (Interrupted (INT)), and 9 more. - Venue ID (`venue_id`, text): Optional. Only fixtures at this venue, by ID. - Last N fixtures (`last`, number): Optional. Only the most recent this many fixtures, up to 99. Not with Next N fixtures. Paid plans only: the free plan refuses it. From 1 to 99. - Next N fixtures (`next`, number): Optional. Only the coming this many fixtures, up to 99. Not with Last N fixtures. Paid plans only: the free plan refuses it. From 1 to 99. - Fixture IDs (`fixture_ids`, list): Optional. Only these fixtures, up to 20, with their events, lineups and statistics too. Not with the other filters. Two or more need a paid plan. - Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Europe/London or America/New_York. UTC when left empty. **Outputs** - `count` (number): How many came back. - `fixtures` (list): The matching fixtures, earliest first. **Example output** ```json { "count": 1, "fixtures": [ { "date": "2019-12-26T17:30:00+00:00", "events": [], "goals": { "away": 1, "home": 4 }, "id": 157201, "league": { "country": "England", "flag": "https://media.api-sports.io/flags/gb.svg", "id": 39, "logo": "https://media.api-sports.io/football/leagues/2.png", "name": "Premier League", "round": "Regular Season - 19", "season": 2019, "standings": null }, "lineups": [], "periods": { "first": 1577381400, "second": 1577385000 }, "players": [], "referee": "Kevin Friend, England", "score": { "extratime": { "away": null, "home": null }, "fulltime": { "away": 1, "home": 4 }, "halftime": { "away": 1, "home": 3 }, "penalty": { "away": null, "home": null } }, "statistics": [], "status": { "elapsed": 90, "extra": null, "long": "Match Finished", "short": "FT" }, "teams": { "away": { "id": 34, "logo": "https://media.api-sports.io/football/teams/34.png", "name": "Newcastle", "winner": false }, "home": { "id": 33, "logo": "https://media.api-sports.io/football/teams/33.png", "name": "Manchester United", "winner": true } }, "timestamp": 1577381400, "timezone": "UTC", "venue": { "city": "Manchester", "id": 556, "name": "Old Trafford" } } ] } ``` ### List head-to-head fixtures List every meeting of two teams in any competition, or only in one league, season, date range or status, or the last or next few, with a count of each side's wins, the draws and the goals across the finished ones. **Inputs** - First team ID (`first_team_id`, text, required): One of the two teams, by ID, such as 33 for Manchester United. The summary counts its wins first. - Second team ID (`second_team_id`, text, required): The other team, by ID, such as 34 for Newcastle. - League (`league_id`, text): Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Premier League. - Season (`season`, number): Optional. Only this season, as the four-digit year it starts in: 2024 for the 2024/25 season. From 1900 to 2100. - From date (`date_from`, date): Optional. Only fixtures on or after this day. Set together with To date. - To date (`date_to`, date): Optional. Only fixtures on or before this day. Set together with From date. - Status (`status`, list): Optional. Only fixtures in these states, such as Not started (NS) or Finished (FT). Every state when none is chosen. One or more of: `TBD` (Time to be defined (TBD)), `NS` (Not started (NS)), `1H` (First half (1H)), `HT` (Half time (HT)), `2H` (Second half (2H)), `ET` (Extra time (ET)), `BT` (Break before extra time or penalties (BT)), `P` (Penalty shootout in progress (P)), `SUSP` (Suspended (SUSP)), `INT` (Interrupted (INT)), and 9 more. - Last N fixtures (`last`, number): Optional. Only the most recent this many fixtures, up to 99. Not with Next N fixtures. Paid plans only: the free plan refuses it. From 1 to 99. - Next N fixtures (`next`, number): Optional. Only the coming this many fixtures, up to 99. Not with Last N fixtures. Paid plans only: the free plan refuses it. From 1 to 99. - Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Europe/London or America/New_York. UTC when left empty. **Outputs** - `count` (number): How many came back. - `fixtures` (list): The meetings, earliest first. - `summary` (object): The record across the finished meetings returned. **Example output** ```json { "count": 1, "fixtures": [ { "date": "2019-12-26T17:30:00+00:00", "events": [], "goals": { "away": 1, "home": 4 }, "id": 157201, "league": { "country": "England", "flag": "https://media.api-sports.io/flags/gb.svg", "id": 39, "logo": "https://media.api-sports.io/football/leagues/2.png", "name": "Premier League", "round": "Regular Season - 19", "season": 2019, "standings": null }, "lineups": [], "periods": { "first": 1577381400, "second": 1577385000 }, "players": [], "referee": "Kevin Friend, England", "score": { "extratime": { "away": null, "home": null }, "fulltime": { "away": 1, "home": 4 }, "halftime": { "away": 1, "home": 3 }, "penalty": { "away": null, "home": null } }, "statistics": [], "status": { "elapsed": 90, "extra": null, "long": "Match Finished", "short": "FT" }, "teams": { "away": { "id": 34, "logo": "https://media.api-sports.io/football/teams/34.png", "name": "Newcastle", "winner": false }, "home": { "id": 33, "logo": "https://media.api-sports.io/football/teams/33.png", "name": "Manchester United", "winner": true } }, "timestamp": 1577381400, "timezone": "UTC", "venue": { "city": "Manchester", "id": 556, "name": "Old Trafford" } } ], "summary": { "draws": 0, "first_team_goals": 4, "first_team_wins": 1, "played": 1, "second_team_goals": 1, "second_team_wins": 0 } } ``` ### List injuries List players missing, or at risk of missing, fixtures through injury or suspension, and why, by fixture, league, team, player or day. Give a league, team or player together with a season. **Inputs** - Fixture ID (`fixture_id`, text): Optional. Only players missing this fixture. - League (`league_id`, text): Optional. Only this competition. Pick one from the list, or pass a league ID such as 39 for the Premier League. - Season (`season`, number): Optional. Only this season, as the four-digit year it starts in: 2024 for the 2024/25 season. From 1900 to 2100. - Team ID (`team_id`, text): Optional. Only this team's players, by ID. Pair it with a season. - Player ID (`player_id`, text): Optional. Only this player, by ID. Pair it with a season. - Date (`on_date`, date): Optional. Only fixtures on this day. - Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Europe/London or America/New_York. UTC when left empty. **Outputs** - `count` (number): How many came back. - `injuries` (list): One entry per player and fixture. **Example output** ```json { "count": 1, "injuries": [ { "fixture": { "date": "2021-04-07T19:00:00+00:00", "id": 686314, "timestamp": 1617822000, "timezone": "UTC" }, "league": { "country": "World", "flag": null, "id": 2, "logo": "https://media.api-sports.io/football/leagues/2.png", "name": "UEFA Champions League", "season": 2020 }, "player": { "id": 865, "name": "D. Costa", "photo": "https://media.api-sports.io/football/players/865.png", "reason": "Broken ankle", "type": "Missing Fixture" }, "team": { "id": 157, "logo": "https://media.api-sports.io/football/teams/157.png", "name": "Bayern Munich" } } ] } ``` ### List live fixtures List the fixtures being played right now, everywhere or in some leagues, with the score, the minute, and the goals, cards and substitutions so far. Updated every 15 seconds. **Inputs** - Leagues (`league_ids`, list): Optional. Only fixtures in these competitions. Every live fixture when none is chosen. - Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Europe/London or America/New_York. UTC when left empty. **Outputs** - `count` (number): How many came back. - `fixtures` (list): The fixtures under way. **Example output** ```json { "count": 1, "fixtures": [ { "date": "2020-02-06T14:00:00+00:00", "events": [], "goals": { "away": 1, "home": 0 }, "id": 239625, "league": { "country": "Morocco", "flag": "https://media.api-sports.io/flags/ma.svg", "id": 200, "logo": "https://media.api-sports.io/football/leagues/115.png", "name": "Botola Pro", "round": "Regular Season - 14", "season": 2019, "standings": null }, "lineups": [], "periods": { "first": 1580997600, "second": null }, "players": [], "referee": null, "score": { "extratime": { "away": null, "home": null }, "fulltime": { "away": null, "home": null }, "halftime": { "away": 1, "home": 0 }, "penalty": { "away": null, "home": null } }, "statistics": [], "status": { "elapsed": 45, "extra": null, "long": "Halftime", "short": "HT" }, "teams": { "away": { "id": 968, "logo": "https://media.api-sports.io/football/teams/968.png", "name": "Wydad AC", "winner": true }, "home": { "id": 967, "logo": "https://media.api-sports.io/football/teams/967.png", "name": "Rapide Oued ZEM", "winner": false } }, "timestamp": 1580997600, "timezone": "UTC", "venue": { "city": "Oued Zem", "id": 1887, "name": "Stade Municipal" } } ] } ``` ### List rounds List a season's rounds in order, such as Regular Season - 1 or Quarter-finals, with the days each is played on if asked, or only the current round. A round's name is what List fixtures takes as its Round. **Inputs** - League (`league_id`, text, required): The competition, such as 39 for the Premier League, 140 for La Liga or 2 for the Champions League. Pick one from the list, or pass a league ID from an earlier step. - Season (`season`, number, required): The season, as the four-digit year it starts in: 2024 for the Premier League's 2024/25 season, or 2025 for a league played within 2025. The free plan covers a few recent seasons only. From 1900 to 2100. - Current round only (`current_only`, true/false): Optional. Only the round being played now. Default: `false`. - Include dates (`include_dates`, true/false): Optional. Add the days each round is played on. Default: `false`. - Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Europe/London or America/New_York. UTC when left empty. **Outputs** - `count` (number): How many came back. - `rounds` (list): The rounds, in the order they are played. **Example output** ```json { "count": 3, "rounds": [ { "dates": [ "2024-08-16", "2024-08-17", "2024-08-18", "2024-08-19" ], "name": "Regular Season - 1" }, { "dates": [ "2024-08-24", "2024-08-25" ], "name": "Regular Season - 2" }, { "dates": [ "2024-08-31", "2024-09-01" ], "name": "Regular Season - 3" } ] } ``` ### List sidelined periods List every injury and suspension on record for a player or a coach, with when each started and ended. **Inputs** - Player ID (`player_id`, text): Optional. The player, by ID, such as 276 for Neymar. Set a player or a coach, not both. - Coach ID (`coach_id`, text): Optional. The coach, by ID. Find coaches looks one up. Set a player or a coach, not both. **Outputs** - `count` (number): How many came back. - `sidelined` (list): The spells out of action. **Example output** ```json { "count": 2, "sidelined": [ { "end": "2020-03-01", "start": "2020-02-26", "type": "Suspended" }, { "end": "2020-02-10", "start": "2020-02-02", "type": "Hip/Thigh Injury" } ] } ``` ### List top players List a competition's top 20 players in a season by goals, assists, yellow cards or red cards, each with their full season statistics. **Inputs** - League (`league_id`, text, required): The competition, such as 39 for the Premier League, 140 for La Liga or 2 for the Champions League. Pick one from the list, or pass a league ID from an earlier step. - Season (`season`, number, required): The season, as the four-digit year it starts in: 2024 for the Premier League's 2024/25 season, or 2025 for a league played within 2025. The free plan covers a few recent seasons only. From 1900 to 2100. - Ranked by (`ranking`, text): Optional. What to rank by: goals, assists, yellow cards or red cards. Goals when left empty. One of: `goals` (Top scorers), `assists` (Top assists), `yellow_cards` (Most yellow cards), `red_cards` (Most red cards). Default: `goals`. **Outputs** - `count` (number): How many came back. - `players` (list): The players, best placed first. - `ranking` (text): What they are ranked by: goals, assists, yellow_cards or red_cards. **Example output** ```json { "count": 1, "players": [ { "player": { "age": 22, "birth": { "country": "France", "date": "1998-12-20", "place": "Paris" }, "firstname": "Kylian", "height": "178 cm", "id": 278, "injured": false, "lastname": "Mbapp\u00e9 Lottin", "name": "K. Mbapp\u00e9", "nationality": "France", "number": null, "photo": "https://media.api-sports.io/football/players/278.png", "position": null, "weight": "73 kg" }, "statistics": [ { "cards": { "red": 1, "yellow": 5, "yellow_red": 0 }, "dribbles": { "attempts": 115, "past": null, "success": 64 }, "duels": { "total": 232, "won": 112 }, "fouls": { "committed": 19, "drawn": 39 }, "games": { "appearances": 29, "captain": false, "lineups": 24, "minutes": 2340, "number": null, "position": "Attacker", "rating": 7.871428, "substitute": null }, "goals": { "assists": 7, "conceded": null, "saves": 0, "total": 33 }, "league": { "country": "France", "flag": "https://media.api-sports.io/flags/fr.svg", "id": 61, "logo": "https://media.api-sports.io/football/leagues/61.png", "name": "Ligue 1", "season": 2018 }, "offsides": null, "passes": { "accuracy": 78, "key": 48, "total": 591 }, "penalty": { "committed": null, "missed": 0, "saved": null, "scored": 1, "won": 3 }, "shots": { "on": 68, "total": 122 }, "substitutes": { "bench": 5, "in": 5, "out": 1 }, "tackles": { "blocks": 0, "interceptions": 4, "total": 4 }, "team": { "id": 85, "logo": "https://media.api-sports.io/football/teams/85.png", "name": "Paris Saint Germain" } } ] } ], "ranking": "goals" } ``` ### List transfers List a player's transfers, or every transfer into and out of a team, newest first: the date, the fee or type (Free, Loan and so on), and the teams the player left and joined. **Inputs** - Player ID (`player_id`, text): Optional. This player's transfers, by ID, such as 35845. - Team ID (`team_id`, text): Optional. Every transfer into and out of this team, by ID. **Outputs** - `count` (number): How many came back. - `transfers` (list): The transfers, newest first. **Example output** ```json { "count": 2, "transfers": [ { "date": "2019-07-15", "from_team": { "id": 2283, "logo": "https://media.api-sports.io/football/teams/2283.png", "name": "Atlas" }, "player": { "id": 35845, "name": "Hern\u00e1n Dar\u00edo Burbano" }, "to_team": { "id": 2283, "logo": "https://media.api-sports.io/football/teams/2283.png", "name": "Atlas" }, "type": "Free", "updated_at": "2020-02-06T00:08:15+00:00" }, { "date": "2019-01-01", "from_team": { "id": 1139, "logo": "https://media.api-sports.io/football/teams/1139.png", "name": "Santa Fe" }, "player": { "id": 35845, "name": "Hern\u00e1n Dar\u00edo Burbano" }, "to_team": { "id": 1937, "logo": "https://media.api-sports.io/football/teams/1937.png", "name": "Atletico Atlas" }, "type": "N/A", "updated_at": "2020-02-06T00:08:15+00:00" } ] } ``` ### List trophies List the trophies a player or a coach has won, and their other placings, with the competition, country and season. **Inputs** - Player ID (`player_id`, text): Optional. The player, by ID, such as 276 for Neymar. Set a player or a coach, not both. - Coach ID (`coach_id`, text): Optional. The coach, by ID. Find coaches looks one up. Set a player or a coach, not both. **Outputs** - `count` (number): How many came back. - `trophies` (list): The trophies and placings. **Example output** ```json { "count": 2, "trophies": [ { "country": "South-America", "league": "Sudamericano U20", "place": "Winner", "season": "Peru 2011" }, { "country": "France", "league": "Troph\u00e9e des Champions", "place": "Winner", "season": "2019/2020" } ] } ```