Docs
Coverage MatrixDocumentationChange LogLog InContact Us
Docs

Advanced Analytics Overview

❗️

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:

  1. Call the daily schedule for the date of the match and find the Sport Event Id for the chosen match
  2. Call the Sport Event Fun Facts using the Sport Event Id
  3. Locate the Fact Statement

The fun facts for the match are displayed.


To find a teams number of completed forward passes:

  1. Call the daily schedule for the date of the match and find the Sport Event Id for the chosen match
  2. Call the Sport Event Summary using the Sport Event Id
  3. 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

EventDefinition
passA 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.
duelAn Action where two Players of the opposite Teams at the same moment try to influence the ball with the intention to play the ball.
crossA ball action, pass or free kick that is a cross.
foul_againstPlayer commits a foul
interceptionAction with which possession was regained that is not a duel.
clearanceA 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_throwPass is a throw by hands of keeper.
goalkeeper_controlAction performed by a goalkeeper to control the ball.
blockA Ball-action where the player blocks a play action or Goal attempt of a player of the opponent team.
ball_distributionAdvancing the ball with the feet in the direction of the opponent’s goal over a minimum of 5 meters.
touchAn 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_playBall goes out of play

Statistics

EventDefinition
aerial_duels_defensiveA defensive duel, that is a duel an has attribute air
aerial_duels_defensive_wonA defensive duel with air attribute that is won (see won definition)
aerial_duels_offensiveAn offensive duel, that is a duel an has attribute air
aerial_duels_offensive_wonAn offensive duel with air attribute that is won (see won definition)
assistsA key action on a goal attempt that is scored
assists_by_free_kickA free kicks that counts as an assist
attempts_at_goal_blockedA 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_progressionA move with the ball by the player without encountering a opponent, only moves longer than 5m are tagged
ball_progression_completeA completed move with the ball by the player without encountering a opponent, only moves longer than 5m are tagged
ball_progression_incompleteA failed move with the ball by the player without encountering a opponent, only moves longer than 5m are tagged
clearancesA defensive action with a attribute clearance
cornersThe number of corner kicks taken by a player/team.
corners_longA corner that is not short
corners_shortA corner taken short
crossesPass with attribute cross
crosses_completedA pass with attribute cross that is complete
crosses_earlyA cross given before the horizontal line of the box
crosses_highA cross given through the air
crosses_incompleteA pass with attribute cross that is incomplete
crosses_lateA cross given after the horizontal line of the box
crosses_lowA cross given over the ground
crosses_to_attempt_at_goalA cross that lead to a goal attempt of team mate
crosses_to_goalA free kick that is directly shot on goal resulting in a goal
direct_red_cardsA direct red card
diving_savesA more advanced save that requires skill from the goalkeeper to dive.
duels_completeDuels defensive or offensive that are complete
duels_defensiveTotal number of defensive duels
duels_defensive_opponents_halfNumber of defensive duels on opponent half
duels_defensive_opponents_half_wonNumber of defensive duels on opponent half won
duels_defensive_own_boxNumber of defensive duels on own box
duels_defensive_own_box_wonNumber of defensive duels on own box won
duels_defensive_own_halfNumber of defensive duels on own half
duels_defensive_own_half_wonNumber of defensive duels on own half won
duels_defensive_wonTotal number of defensive duels won
duels_fifty_fiftyNumber of duels, that have a duel as previous action
duels_incompleteDuels defensive or offensive that are incomplete
duels_offensiveTotal number of off duels
duels_offensive_wonTotal number of off duels won
duels_slidingA defensive action with attributes sliding
duels_totalDuels defensive or offensive
eventsThe number of ball actions a player made during the match
events_inside_boxThe number of ball actions a player made during the match that occurred inside the box
events_keyAn 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_cornerA corner kick that is a key action
events_key_freekickA free kick that is a key action
events_successfulThe number of actions that are successful, for each type of action we have a definition of what is successful
fouls_againstA foul is given against the team/player
fouls_forA foul is given for the team/player
fouls_own_halfA foul conceded in their own half
free_kicksTotal number of free kicks taken
free_kicks_missedTotal number of free kicks off target
free_kicks_on_goalTotal number of free kicks that are saved or a goal
free_kicks_scoredTotal number of free kicks that are a goal
goal_kicksTotal number of goal kicks taken
goalsTotal amount of goals scored
gradeEvery action is rated by analysts with an overall match grade created from this
ground_duels_defensiveA defensive duel with no air attribute
ground_duels_defensive_wonA defensive ground duel that is won (see won definition)
ground_duels_offensiveAn offensive duel with no air attribute
ground_duels_offensive_wonAn offensive ground duel that is won (see won definition)
interceptions_goalkeeperA interception of the goalkeeper by his hands on a long ball or cross, either intercepted by caught or punch
involvement_in_attempt_at_goalNumber of times an action in a possession ends with goal attempt
involvement_in_attempt_at_goal_xgTotal xG of goal attempts in which player has an action
keeper_throws_longA pass with attribute throw and length >30
keeper_throws_shortA pass with attribute throw and length <20
offsidesTotal of offsides called
own_goalsTotal of own goals scored
passesAny pass that is attempted
passes_backwardPasses with angle between 102.5 and 257.5
passes_backward_completeBoth Backwards and completed
passes_between_central_defendersA pass between two central defenders
passes_completeTagged passes that have a next action of the same team
passes_directA pass with attribute directly played
passes_first_in_possessionThe first pass in a possession moment
passes_first_in_possession_forwardA first pass that is also forward
passes_forwardPasses with angle between 0 and 77.5 or 282.5 and 360 degrees
passes_forward_completeBoth forward and completed
passes_in_final_thirdA pass is given in the last 30m of the field
passes_in_final_third_completeA pass is given in the last 30m of the field completed
passes_incompleteA pass that is attempted but incomplete
passes_into_boxA pass given from outside the opponents box that ends in the opponent box
passes_keyA pass that lead to a goal attempt
passes_longPasses with length >30
passes_long_completePasses with length >30 completed
passes_long_incompletePasses with length >30 incompleted
passes_opponents_halfA pass on the opponent half
passes_opponents_half_completeA pass on the opponent half completed
passes_own_halfA pass in their own half
passes_shortPasses with length <30
passes_switchA pass that crosses the vertical midline and the difference in wide of the field between starting point and ending point is 30m
passes_widePasses with angle between 77.5 and 102.5 or 257.5 and 282.5 degrees
passes_wide_completeBoth wide and completed
penalties_facedTotal number of penalties faced (excluding shootouts)
penalties_savedTotal number of penalties saved (excluding shootouts)
possession_opponents_halfPercentage passes opponent half / total passes
possessions_lostThe last action of a ball possession moment
possessions_lost_by_duelA possession lost action that is a duel
possessions_lost_by_passesA 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_timeTotal Time a team has the ball in possession in minutes
red_cards_for_second_cautionA red card as a result of two yellow card cautions
throw_insTotal amount of throw ins taken
throw_ins_keep_possessionThrow ins with 3 actions of same team
total_x_locationThe totalX and totalY location can be used to calculate the average location per match
total_y_locationThe totalX and totalY location can be used to calculate the average location per match
xg_valueExpected goal value of all goal attempts
yellow_cardsTotal amount of yellow cards received