Soccer Advanced Analytics Update
Soccer Advanced Analytics will be consolidating with the Soccer Extended API on November 6th, 2024.
Introduction
Our Soccer Advanced Analytics API provides real-time match updates with cutting edge advanced statistics.
Our highly skilled team collects deeper events and derived statistics, using universal standards for soccer definitions. 2,000+ unique events are created (with attributes and outcomes) per game. 100+ player and team stat types are tracked per game.
Advanced statistics are available for select top leagues. See our Coverage Matrix for a detailed breakdown of competitions and data offered. Subscription to this package will also include access to lower tiered competitions via Soccer v4.
The Soccer Advanced Analytics API is consistent in structure, format and behavior with the Soccer v4 API. Primary feeds will return seasons, competitions, team/player data and real-time scores.
Additional feeds provide a host of complementary stats, including:
- Live standings for top leagues
- League leaders
- Win probabilities for every match
- Lineups with formations
- Seasonal statistics
- Missing/Injured players
- Live ball-spotting data (x,y coordinates for events on the field)
- Head-to-head statistics
- Fun facts
Real-time customers are also offered two delivery Push Feeds to enhance speed.
Authentication is required for all API calls.
API Map
To best utilize the Soccer Advanced Analytics API, you will need several parameters to create your API calls. The map below illustrates how you can obtain the parameters you need.
Primary and mapping feeds only require dates, human-readable parameters or a Competition Id (which can be found in the competitions endpoint), while other feeds require a global unique identifier (GUID) to identify the sport event, competitor, or player that the feed will describe. The primary feeds provide GUIDs for sport events, competitions, and competitors, while sport event and competitors provide GUIDS for players.
Endpoint Descriptions
Competition Info – Provides the name, id, and parent id for a given competition.
Competition Seasons – Provides historical Season Info for a given competition. Competitions will return a maximum of three seasons of data, including current or newly created seasons.
Competitions – Provides a list of all available Soccer competitions.
Competitor Mappings – Provides competitor id mapping between previous versions of the Soccer API.
Competitor Merge Mappings – Provides the valid Sportradar Id in cases when two competitors have been merged into one.
Competitor Profile – Provides top-level information for a given team, including the full team roster, manager, home venue, and team colors.
Competitor Schedules - Provides previous and upcoming match information for a given competitor.
Competitor Versus Competitor Schedules – Provides previous and upcoming matches between two teams.
Daily Schedules – Provides a list of all scheduled matches on a given day.
League Timeline - Provides an alternate set of statistics for an event which match official league sites. Official stats are provided for: England Premier League, Germany Bundesliga, Italy Serie A, Spain La Liga, UEFA Champions League, USA MLS, Austria Bundesliga.
Live Schedules - Provides match information for all currently live matches.
Live Timelines Delta - Provides a 10 second live delta of match information, including scoring and a play-by-play event timeline.
Player Mappings – Provides player id mapping between previous versions of the Soccer API.
Player Merge Mappings – Provides valid ids for players who have had their profiles merged. While Sportradar always strives to provide one unique player id, it is a possibility for two ids to be created. This feed provides the correct id once profiles have been merged.
Player Profile – Provides player information, including current and historical team membership info.
Player Schedules - Provides match info for the past 10 matches in which a given player participated.
Season Competitors – Provides a list of teams participating for a given season.
Season Info – Provides detailed information for a given season, including participating teams and coverage level.
Season Leaders – Provides a list of leaders for a given season. Statistics include points, goals, assists, cards, and minutes played.
Season Lineups – Provides match lineups and substitutions for a given season.
Season Links – Provides information about linked cup rounds for a given season. Use this feed to compile full advancement brackets for relevant seasons/tournaments. Links between all matches and rounds are available when competitors (TBD vs. TBD) are not yet known.
Season Missing Players – Provides a list of injured and/or missing players for a given season.
Season Over/Under Statistics – provides the over/under match goal totals for all teams in a given season.
Season Players – Provides names and ids for all participating players for a given season.
Season Probabilities – Provides 3-way win probabilities (home team win, away team win, draw) for all matches for a given season.
Season Schedule – Provides basic match information for all matches for a given season, including scoring and match coverage.
Season Standings – Provides detailed standings info for a given season.
Season Transfers - Provides a list of all player transfers for a given season.
Seasonal Competitor Players – Provides player roster information for every team from a given season.
Seasonal Competitor Statistics – Provides team and player seasonal statistics for a given season.
Seasons – Provides a list of historical season information for all competitions. Competitions will return a maximum of three seasons of data, including current or newly created seasons.
Sport Event Fun Facts – Provides noteworthy, human-readable, facts based on statistical information about a given match and its competing teams.
Sport Event Lineups – Provides detailed roster information for a given match. Starting players, substitutions, formation type, and channel availability are included if supported by coverage level.
Sport Event Summary – Provides real-time advanced analytic statistics for a given match. Including player and team stats, scoring info, and channel availability. Please note that data returned is determined by coverage level.
Sport Event Timeline – Provides real-time advanced analytic events and a play-by-play event timeline for a given match. Please note that data returned is determined by coverage level.
Sport Events Created – Provides ids for sport events that have been created in the last 24 hours.
Sport Events Removed – Provides ids for sport events that have been removed or deleted.
Sport Events Updated - Provides ids for sport events that have been updated in the last 24 hours.
Push Events – Provides real-time event updates for all live matches.
Push Statistics - Provides real-time team and player match-level statistics for all live matches.
Data Retrieval Samples
To find the fun facts for a given match:
- Call the daily schedule for the date of the match and find the Sport Event Id for the chosen match
- Call the Sport Event Fun Facts using the Sport Event Id
- Locate the Fact Statement
The fun facts for the match are displayed.
To find a teams number of completed forward passes:
- Call the daily schedule for the date of the match and find the Sport Event Id for the chosen match
- Call the Sport Event Summary using the Sport Event Id
- Locate the completed forward passes attribute (passes_forward_complete)
The teams number of completed forward passes is displayed.
Integration Links
OpenAPI Spec
Our Soccer API is available via OpenAPI. Click below to view and/or download the spec.
Soccer Advanced Analytics v1 OpenAPI
Postman Workspace
Our entire Media APIs are available on Postman. Click the link above to be taken directly to our Soccer Advanced Analytics API collection.
Feel free to follow and/or fork any collections to receive updates.
Schema Download
Open the zip file below to access our entire Soccer API XSD schema.
Soccer Advanced Analytics Schema
Failover Info
If we lose connection with our scout feed, Sportradar Production performs failover.
Up to live coverage tier 2 failover is in place in the situation where there are any issues with primary live coverage for deeper player or team stats such as shots, corners, assists and offsides.
For our Advanced Analytics coverage, there is no live failover in place in case of any issues with primary coverage. Data will be updated post-match.
Advanced Analytics Data Dictionary
See below for a breakdown of all advanced statistics provided, including definitions.
Events
| Event | Definition |
| pass | A ball action that has the intention to send the ball to a Player of the same team. Ball actions that belong to Set play are not counted as passes. |
| duel | An Action where two Players of the opposite Teams at the same moment try to influence the ball with the intention to play the ball. |
| cross | A ball action, pass or free kick that is a cross. |
| foul_against | Player commits a foul |
| interception | Action with which possession was regained that is not a duel. |
| clearance | A Ball-action where the player plays the ball without having the intention to reach a team mate. The purpose of the action is to keep the ball away from the own goal. |
| goalkeeper_throw | Pass is a throw by hands of keeper. |
| goalkeeper_control | Action performed by a goalkeeper to control the ball. |
| block | A Ball-action where the player blocks a play action or Goal attempt of a player of the opponent team. |
| ball_distribution | Advancing the ball with the feet in the direction of the opponent’s goal over a minimum of 5 meters. |
| touch | An action where a player touched the ball unintended. For example, when a teammate shoots against the player or an opponent passes the ball against the player so the ball changes of direction. |
| out_of_play | Ball goes out of play |
Statistics
| Event | Definition |
| aerial_duels_defensive | A defensive duel, that is a duel an has attribute air |
| aerial_duels_defensive_won | A defensive duel with air attribute that is won (see won definition) |
| aerial_duels_offensive | An offensive duel, that is a duel an has attribute air |
| aerial_duels_offensive_won | An offensive duel with air attribute that is won (see won definition) |
| assists | A key action on a goal attempt that is scored |
| assists_by_free_kick | A free kicks that counts as an assist |
| attempts_at_goal_blocked | A defensive blocking action on a shot of the opponent |
| attempts_at_goal_inside_ the_penalty_area | A shot inside the box |
| attempts_at_goal_inside_ the_penalty_area_on_target | A shot inside the box that is saved or is a goal |
| attempts_at_goal_inside_ the_penalty_area_scored | A shot inside the box and is a goal |
| attempts_at_goal_outside_ the_penalty_area | A shot outside the box |
| attempts_at_goal_outside_ the_penalty_area_on_target | A shot outside the box that is saved or is a goal |
| attempts_at_goal_outside_ the_penalty_area_scored | A shot outside the box and is a goal |
| ball_progression | A move with the ball by the player without encountering a opponent, only moves longer than 5m are tagged |
| ball_progression_complete | A completed move with the ball by the player without encountering a opponent, only moves longer than 5m are tagged |
| ball_progression_incomplete | A failed move with the ball by the player without encountering a opponent, only moves longer than 5m are tagged |
| clearances | A defensive action with a attribute clearance |
| corners | The number of corner kicks taken by a player/team. |
| corners_long | A corner that is not short |
| corners_short | A corner taken short |
| crosses | Pass with attribute cross |
| crosses_completed | A pass with attribute cross that is complete |
| crosses_early | A cross given before the horizontal line of the box |
| crosses_high | A cross given through the air |
| crosses_incomplete | A pass with attribute cross that is incomplete |
| crosses_late | A cross given after the horizontal line of the box |
| crosses_low | A cross given over the ground |
| crosses_to_attempt_at_goal | A cross that lead to a goal attempt of team mate |
| crosses_to_goal | A free kick that is directly shot on goal resulting in a goal |
| direct_red_cards | A direct red card |
| diving_saves | A more advanced save that requires skill from the goalkeeper to dive. |
| duels_complete | Duels defensive or offensive that are complete |
| duels_defensive | Total number of defensive duels |
| duels_defensive_opponents_half | Number of defensive duels on opponent half |
| duels_defensive_opponents_half_won | Number of defensive duels on opponent half won |
| duels_defensive_own_box | Number of defensive duels on own box |
| duels_defensive_own_box_won | Number of defensive duels on own box won |
| duels_defensive_own_half | Number of defensive duels on own half |
| duels_defensive_own_half_won | Number of defensive duels on own half won |
| duels_defensive_won | Total number of defensive duels won |
| duels_fifty_fifty | Number of duels, that have a duel as previous action |
| duels_incomplete | Duels defensive or offensive that are incomplete |
| duels_offensive | Total number of off duels |
| duels_offensive_won | Total number of off duels won |
| duels_sliding | A defensive action with attributes sliding |
| duels_total | Duels defensive or offensive |
| events | The number of ball actions a player made during the match |
| events_inside_box | The number of ball actions a player made during the match that occurred inside the box |
| events_key | An action that leads to a goal attempt of a teammate. It is the action before a goal attempt from another player of the same team without a clearance or pass of the opponent between it |
| events_key_corner | A corner kick that is a key action |
| events_key_freekick | A free kick that is a key action |
| events_successful | The number of actions that are successful, for each type of action we have a definition of what is successful |
| fouls_against | A foul is given against the team/player |
| fouls_for | A foul is given for the team/player |
| fouls_own_half | A foul conceded in their own half |
| free_kicks | Total number of free kicks taken |
| free_kicks_missed | Total number of free kicks off target |
| free_kicks_on_goal | Total number of free kicks that are saved or a goal |
| free_kicks_scored | Total number of free kicks that are a goal |
| goal_kicks | Total number of goal kicks taken |
| goals | Total amount of goals scored |
| grade | Every action is rated by analysts with an overall match grade created from this |
| ground_duels_defensive | A defensive duel with no air attribute |
| ground_duels_defensive_won | A defensive ground duel that is won (see won definition) |
| ground_duels_offensive | An offensive duel with no air attribute |
| ground_duels_offensive_won | An offensive ground duel that is won (see won definition) |
| interceptions_goalkeeper | A interception of the goalkeeper by his hands on a long ball or cross, either intercepted by caught or punch |
| involvement_in_attempt_at_goal | Number of times an action in a possession ends with goal attempt |
| involvement_in_attempt_at_goal_xg | Total xG of goal attempts in which player has an action |
| keeper_throws_long | A pass with attribute throw and length >30 |
| keeper_throws_short | A pass with attribute throw and length <20 |
| offsides | Total of offsides called |
| own_goals | Total of own goals scored |
| passes | Any pass that is attempted |
| passes_backward | Passes with angle between 102.5 and 257.5 |
| passes_backward_complete | Both Backwards and completed |
| passes_between_central_defenders | A pass between two central defenders |
| passes_complete | Tagged passes that have a next action of the same team |
| passes_direct | A pass with attribute directly played |
| passes_first_in_possession | The first pass in a possession moment |
| passes_first_in_possession_forward | A first pass that is also forward |
| passes_forward | Passes with angle between 0 and 77.5 or 282.5 and 360 degrees |
| passes_forward_complete | Both forward and completed |
| passes_in_final_third | A pass is given in the last 30m of the field |
| passes_in_final_third_complete | A pass is given in the last 30m of the field completed |
| passes_incomplete | A pass that is attempted but incomplete |
| passes_into_box | A pass given from outside the opponents box that ends in the opponent box |
| passes_key | A pass that lead to a goal attempt |
| passes_long | Passes with length >30 |
| passes_long_complete | Passes with length >30 completed |
| passes_long_incomplete | Passes with length >30 incompleted |
| passes_opponents_half | A pass on the opponent half |
| passes_opponents_half_complete | A pass on the opponent half completed |
| passes_own_half | A pass in their own half |
| passes_short | Passes with length <30 |
| passes_switch | A pass that crosses the vertical midline and the difference in wide of the field between starting point and ending point is 30m |
| passes_wide | Passes with angle between 77.5 and 102.5 or 257.5 and 282.5 degrees |
| passes_wide_complete | Both wide and completed |
| penalties_faced | Total number of penalties faced (excluding shootouts) |
| penalties_saved | Total number of penalties saved (excluding shootouts) |
| possession_opponents_half | Percentage passes opponent half / total passes |
| possessions_lost | The last action of a ball possession moment |
| possessions_lost_by_duel | A possession lost action that is a duel |
| possessions_lost_by_passes | A possession lost action that is a pass |
| possessions_regained_ by_duel | First action of possession moment that is a duel |
| possessions_regained_ by_interception | First action of possession moment that is neither a duel or a dead moment |
| possessions_regained_ in_opponents_half | A possession regain by duel of interception on the opponent half |
| possessions_regained_ in_play | First action of a possession moment that is not a set play |
| possessions_time | Total Time a team has the ball in possession in minutes |
| red_cards_for_second_caution | A red card as a result of two yellow card cautions |
| throw_ins | Total amount of throw ins taken |
| throw_ins_keep_possession | Throw ins with 3 actions of same team |
| total_x_location | The totalX and totalY location can be used to calculate the average location per match |
| total_y_location | The totalX and totalY location can be used to calculate the average location per match |
| xg_value | Expected goal value of all goal attempts |
| yellow_cards | Total amount of yellow cards received |