Docs
v4
Coverage MatrixDocumentationRelease LogLog InContact Us
Coverage MatrixDocumentationRelease LogLog InContact Us

Advanced Analytics FAQs

Frequently asked questions on Soccer Advanced Analytics v1

Click on the categories below or browse questions on the right panel.

Categories

.

Coverage


What leagues do you cover for soccer?

You can find all the leagues we cover, as well as a breakdown of advanced analytics offered, via our Coverage Matrix.


When is coverage information added to the endpoints?

On the first day of the season.


How do I find out the coverage for a particular match?

Find the node for coverage within the Summaries, Lineups, and Timeline endpoints.

Coverage nodes have three types: season level, group level, and sport_event level.

  • The season level describes data coverage you can expect for matches involved in that given season.
  • The group level is similar because there exists competitions where coverage levels differ at different stages or in different groups - mostly cup competitions.
  • The sport_event level describes the data depth of a specific match within the group and season.

Note: There are occasions when the sport_event coverage can vary from the anticipated season coverage. This node exists to highlight that instance and assist in handling any discrepancies.

<coverage type="sport_event">
    <sport_event_properties lineups="true" venue="true" extended_player_stats="true" extended_team_stats="true" basic_play_by_play="true" basic_player_stats="true" basic_team_stats="true"/>
</coverage>

How is coverage for a particular match defined?

The coverage nodes contain classifications of data types which are expressed as Boolean values or denoted as live or post. 

<coverage type="sport_event">
    <sport_event_properties lineups="false" venue="false" extended_player_stats="false" extended_team_stats="false" 
      ballspotting="false" commentary="false" fun_facts="false" goal_scorers="false" scores="post" game_clock="false" 
      deeper_play_by_play="false" deeper_player_stats="false" deeper_team_stats="false" basic_play_by_play="false" 
      basic_player_stats="false" basic_team_stats="false"/>
</coverage>

How will a sport event behave when it is not covered with live scores?

When a sport_event is not covered live, the status and match_status will remain as not_started until results are entered post-match.

<sport_event_status status="not_started" match_status="not_started"/>

How are “Live” endpoints handled in the API?

Sport Events appear in the feed 10 minutes before the scheduled start time and are removed 10 minutes after the Sport Event is ended. Live endpoints include: Live Schedules.


How are friendlies handled in the Summary endpoints?

The Summary endpoints return all Friendlies played in the last 2 weeks and scheduled for the next 4 weeks.


Why does the coverage of a cup competition not match the data?

For cup competitions, coverage levels may vary from the early rounds to latter stages. Coverage properties are set at a competition level and display the best coverage we offer for a sport event in this competition.


Why is goals_scored the only statistic available in Season Leaders and Season Competitor Statistics for some competitions?

This is determined by the assists="false" property in the Season Info feed which indicates that stats below goals_scored are not guaranteed for the competition in question.

<sport_event_properties basic_play_by_play="false" basic_player_stats="false" basic_team_stats="false" 
extended_player_stats="false" extended_team_stats="false" deeper_play_by_play="false" deeper_team_stats="false" 
deeper_player_stats="false" lineups="false" goal_scorers="false" scores="live" assists="false"/>

Integration


How can I find the values for various enum data points within the API?

Many enum values are listed in the FAQ below. For the most up-to-date values, please see the Schema section of the OpenAPI specification here


What format are date fields presented in?

When we present date only values we present these in the ISO 8601 standard format.

ex: 2013-04-03

We use these for attributes that have date and no time (such as birthdate). For more information: https://en.wikipedia.org/wiki/ISO_8601


What format are the date/time fields presented in?

All of our Date/Time attributes are in UTC, presented in the ISO 8601 standard format.

ex: 2013-04-03T18:15:00+00:00

For more information: https://en.wikipedia.org/wiki/ISO_8601


How do I locate the TTL (Time to Live)/cache on an API endpoint?

The cache (in seconds) can be accessed in the returned header information on each RESTful API call, under cache-control.

ex. cache-control: max-age=1, public, s-maxage=1 or
cache-control: public, must-revalidate, max-age=120


Sport Event Statuses


What are the valid sport_event_status – status values?

  • not_started – The match is scheduled to be played
  • started - The match has begun
  • live – The match is currently in progress
  • postponed – The match has been postponed to a future date
  • suspended - The match has been suspended
  • match_about_to_start - The match is about to begin
  • delayed – The match has been temporarily delayed and will be continued. Typically appears prior to match start
  • interrupted - The match began, but coverage has stopped for a short time. Note that match scores may not be updated during this period, the last recorded match score will be displayed instead
  • cancelled – The match has been cancelled and will not be played
  • ended – The match is over
  • closed – The match results have been confirmed

What are the valid sport_event_status – match_status values?

  • not_started – The match is scheduled to be played
  • started - The match has begun
  • 1st_half – The match is in the first half
  • 2nd_half – The match is in the second half
  • overtime – The match is in overtime
  • 1st_extra – The match is in the first extra period
  • 2nd_extra – The match is in the second extra period
  • awaiting_penalties – Waiting for announcement of penalties
  • penalties – Penalties are ongoing
  • awaiting_extra_time – Waiting on referee to announce extra time
  • interrupted – The match has been interrupted
  • abandoned – The match has been abandoned
  • postponed – The match has been postponed to a future date
  • start_delayed – The match has been temporarily delayed and will be continued
  • cancelled – The match has been cancelled and will not be played
  • halftime – The match is in halftime
  • extra_time_halftime – The match is in extra time halftime
  • ended – The match has ended
  • aet – The match has ended after extra time
  • ap – The match has ended after penalties

Event & Period Types


What are the possible event types?

  • break_start
  • canceled_decision_to_var
  • corner_kick
  • decision_to_var
  • decision_to_var_over
  • free_kick
  • goal_kick
  • injury
  • injury_return
  • injury_time_shown
  • match_ended
  • match_started
  • offside
  • penalty_awarded
  • penalty_kick
  • penalty_missed
  • penalty_shootout
  • period_score
  • period_start
  • player_back_from_injury
  • possible_decision_to_var
  • red_card
  • save
  • score_change
  • shot_off_target
  • shot_on_target
  • shot_saved
  • substitution
  • throw_in
  • video_assistant_referee
  • video_assistant_referee_over
  • yellow_card
  • yellow_red_card

* Availability of Video Assistant Referee is subject to the VAR capabilities of the league.


How does the possible_goal event type work?

This event will occur immediately if one team scores a goal or if they are in a very clear scoring opportunity (1on1 with the goalkeeper, clear shot at an empty net, etc).


What are the valid period_type and period_name values for events?

  • regular_period
  • overtime
  • penalties
  • interrupted

© Sportradar AG, St. Gallen, Switzerland