Push Statistics

Syntax

https://api.sportradar.com/soccer/{access_level}/{version}/stream/statistics/subscribe?api_key={your_api_key}

Replace placeholders with the following query parameters:

Parameter	Description
`access_level`	Defines the access level of your API key as Production (production) or Trial (trial).
`version`	Version number of the API you are accessing (Current Version: v4).
`your_api_key`	Your API key.

Optional Query String Parameters

In addition to the URL parameters listed above, you can filter the Events information with one or more of the following optional query string parameters.

📘
Optional query string parameters must be added after your API key with an ampersand (&). If you are filtering for more than one result, separate the results with a comma (,) and no spaces.

Replace placeholders with the following query parameters:

Parameter	Description
`competition_id`	Competition id expressed as: {competition_id}. Example: competition_id=sr:competition:204
`event_id`	Event type expressed as: {event_type}. Example: event_id=free_kick
`format`	Format type expressed as: {format}. Example: format=json
`season_id`	Season id expressed as: {season_id}. Example: season_id=sr:season:50039
`sport_event_id`	Sport event id expressed as: {sport_event_id}. Example: sport_event_id=sr:sport_event_id:13644241

Code Samples

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.sportradar.com/soccer/trial/v4/stream/statistics/subscribe?api_key={your_api_key}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

import requests
import json

r = requests.get("https://api.sportradar.com/soccer/trial/v4/stream/statistics/subscribe",
    params = {'api_key': 'your_api_key'},
    allow_redirects=False)

redirect_url = r.headers['Location']
r = requests.get(redirect_url, stream=True)

for line in r.iter_lines():
    # filter out keep-alive new lines
    if line:
        decoded_line = line.decode('utf-8')
        print(json.loads(decoded_line))

curl -L "https://api.sportradar.com/soccer/trial/v4/stream/statistics/subscribe?api_key={your_api_key}"

Samples with Query String Params

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.sportradar.com/soccer/trial/v4/stream/statistics/subscribe?api_key={your_api_key}&format=json&sport_event_id=sr:match:13468929")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

import requests
import json

r = requests.get("https://api.sportradar.com/soccer/trial/v4/stream/statistics/subscribe",
    params = {'api_key': 'your_api_key', 'format': 'json', 'sr:match:13468929': 'test_this_thing'},
    allow_redirects=False)

redirect_url = r.headers['Location']
r = requests.get(redirect_url, stream=True)

for line in r.iter_lines():
    # filter out keep-alive new lines
    if line:
        decoded_line = line.decode('utf-8')
        print(json.loads(decoded_line))

curl -L GET 'api.sportradar.com/soccer/trial/v4/stream/statistics/subscribe?api_key={your_api_key}&format=json&sport_event_id=sr:match:13468929'

Response Sample

The above commands return json like this.

Data Points

Metadata:

Attribute	Parent Element	Type	Description
`channel`	`metadata`	String	Sport of the stream connection ex. `soccer`
`competition_id`	`metadata`	String	Unique Id of a competition ex. `sr:competition:23`
`event_id`	`metadata`	String	Description of a push statistic event `match_started`, `match_ended`, `period_start`, `period_score`, `score_change`, `yellow_card`, `yellow_red_card`, `red_card`, `substitution`, `injury_time_shown`, `free_kick`, `goal_kick`, `throw_in`, `offside`, `corner_kick`, `shot_on_target`, `shot_off_target`, `save`, `injury`, `penalty_kick`, `player_back_from_injury`, `penalty_missed`, `penalty_shootout`, `decision_to_var`, `decision_to_var_over`, `possible_decision_to_var`, `canceled_decision_to_var`, `break_start`, `injury_return`, `video_assistant_referee`, `video_assistant_referee_over`, `penalty_awarded`, `shot_saved, possible_goal`
`format`	`metadata`	String	Format type of the response `json`, `xml`
`season_id`	`metadata`	String	Unique Id of a season ex. `sr:season:106499`
`sport_event_id`	`metadata`	String	Unique Id of a sport event ex. `sr:sport_event_id:42134765`
`sport_id`	`metadata`	String	Unique Id of a sport ex. `sr:sport:1`
`from`	`heartbeat`	Integer	Unix timestamp of the beginning of a heartbeat message ex. `1713804799`
`to`	`heartbeat`	Integer	Unix timestamp of the end of a heartbeat message ex. `1713804804`
`interval`	`heartbeat`	Integer	Interval of a heartbeat message in seconds
`type`	`heartbeat`	String	Type of heartbeat message ex. `events`, `statistics`
`package`	`heartbeat`	String	Package of a heartbeat message ex. `soccer-v4`

Sport Event Status:

Ball Location:

Visit our FAQ for additional information on ball location data.

Attribute	Parent Element	Type	Description
`order`	`sport_event_status` - `ball_locations` - `ball_location`	Integer	Sequential order of a ball location event. The most recent location is `4` and the oldest location is `1`.
`qualifier`	`sport_event_status` - `ball_locations` - `ball_location`	String	Designation of a competitor for a ball location entry `home`, `away`
`x`	`sport_event_status` - `ball_locations` - `ball_location`	String	Horizontal X coordinate of the pitch. `x` is a number between `0` and `100`. The reference point `0` is at the home team’s goal.
`y`	`sport_event_status` - `ball_locations` - `ball_location`	String	Vertical Y coordinate of the pitch. `y` is a number between `0` and `100`. The reference point `0` is on the top of the pitch where the home team’s goal is on the left hand side.

Sport Event Situation:

Attribute	Parent Element	Type	Description
`played`	`sport_event_status` - `clock`	String	Match clock time in minutes `90:00`
`stoppage_time_played`	`sport_event_status` - `clock`	String	Stoppage time played in minutes `5:49`
`stoppage_time_announced`	`sport_event_status` - `clock`	String	Stoppage time announced in minutes `5:00`
`status`	`sport_event_status` - `match_situation`	String	Current situtation status of a match `safe`, `dangerous`, `attack`
`qualifier`	`sport_event_status` - `match_situation`	String	Defines the team in the current situation status `home`, `away`
`updated_at`	`sport_event_status` - `match_situation`	Date-Time	Timestamp of the most recent match situation update ex. `2024-04-14T14:57:28+00:00`
`away_score`	`sport_event_status` - `period_scores`	Integer	Away team period score
`home_score`	`sport_event_status` - `period_scores`	Integer	Home team period score
`number`	`sport_event_status` - `period_scores`	Integer	Period number
`type`	`sport_event_status` - `period_scores`	String	Period type `regular_period`, `overtime`, `penalties`, `pause`, `awaiting_extra`, `extra_time_halftime`, `interrupted`

Competitor:

Attribute	Parent Element	Type	Description
`abbreviation`	`statistics` - `competitors`	String	Abbreviation for a competitor name ex. `LIV` (Liverpool FC)
`age_group`	`statistics` - `competitors`	String	Age group of a competitor, when applicable ex. `U23`
`country`	`statistics` - `competitors`	String	Country of a competitor ex. `England`
`country_code`	`statistics` - `competitors`	String	Country code of a competitor ex. `ENG` (England)
`gender`	`statistics` - `competitors`	String	Gender for a competitor `male`, `female`
`id`	`statistics` - `competitors`	String	Unique ID for a competitor ex. `sr:competitor:44` (Liverpool FC)
`name`	`statistics` - `competitors`	String	Name for a competitor ex. `Liverpool FC`
`qualifier`	`statistics` - `competitors`	String	Designation of a competitor for a sport event `home`, `away`
`virtual`	`statistics` - `competitors`	Boolean	Signifies a competitor is a virtual team whan `true`. Used for placeholder teams in TBD vs TBD matchups.

Match Stats (Team):

Attribute	Parent Element	Type	Description
`ball_posession`	`competitor` - `statistics`	Integer	Percentage of team ball possession for a match. ex. `43`
`cards_given`	`competitor` - `statistics`	Integer	Total cards given to a team in a match
`corner_kicks`	`competitor` - `statistics`	Integer	Total team corner kicks for a match
`fouls`	`competitor` - `statistics`	Integer	Total number of fouls awarded against a team (including those which draw cards)
`free_kicks`	`competitor` - `statistics`	Integer	Team free kicks for a match. In accordance with the rules, a free kick stat counted for the team who executes a free kick. Direct or indirect free kicks are all counted as free kicks.
`goal_kicks`	`competitor` - `statistics`	Integer	Team goal kicks for a match. Total number of kicks awarded to the team as a result of the ball traveling out of bounds over the goal line of the defending team.
`injuries`	`competitor` - `statistics`	Integer	Total team injuries for a match
`offsides`	`competitor` - `statistics`	Integer	Total team offside infringements for a match
`penalties_missed`	`competitor` - `statistics`	Integer	Total team penalty shots missed for a match
`red_cards`	`competitor` - `statistics`	Integer	Total team red cards for a match
`shots_blocked`	`competitor` - `statistics`	Integer	Total team shots blocked for a match
`shots_off_target`	`competitor` - `statistics`	Integer	Total team off-target shots for a match
`shots_on_target`	`competitor` - `statistics`	Integer	Total team on-target shots for a match
`shots_saved`	`competitor` - `statistics`	Integer	Total number of goal keeper saves attributed to a team for a match
`shots_total`	`competitor` - `statistics`	Integer	Total number of shots attributed to a team for a match
`substitutions`	`competitor` - `statistics`	Integer	Total number player subsitutions in a match
`throw_ins`	`competitor` - `statistics`	Integer	Total number of throw-in events for a team during a match
`yellow_cards`	`competitor` - `statistics`	Integer	Total team yellow cards for a match
`yellow_red_cards`	`competitor` - `statistics`	Integer	Player red cards for a match resulting from two yellow cards

Player:

Attribute	Parent Element	Type	Description
`id`	`statistics` - `competitor` - `players`	String	Unique ID of a player ex. `sr:player:159665`
`name`	`statistics` - `competitor` - `players`	String	Name of a player ex. `Salah, Mohamed`
`starter`	`statistics` - `competitor` - `players`	Boolean	Signifies a player is in the starting lineup for a sport event when `true`

Match Stats (Player):

Attribute	Parent Element	Type	Description
`assists`	`players` - `statistics`	Integer	Player assists for a match
`corner_kicks`	`players` - `statistics`	Integer	Player corner kicks for a match
`goals_scored`	`players` - `statistics`	Integer	Player goals scored for a match
`offsides`	`players` - `statistics`	Integer	Player offsides for a match
`own_goals`	`players` - `statistics`	Integer	Player own goals for a match
`penalties_missed`	`players` - `statistics`	Integer	Player penalty shots missed for a match
`red_cards`	`players` - `statistics`	Integer	Player red cards for a match
`shots_blocked`	`players` - `statistics`	Integer	Player shots blocked for a match
`shots_off_target`	`players` - `statistics`	Integer	Player shots off target for a match
`shots_on_target`	`players` - `statistics`	Integer	Player shots on target for a match
`substituted_in`	`players` - `statistics`	Integer	Signifies a player was substituted in during a match when `1`
`substituted_out`	`players` - `statistics`	Integer	Signifies a player was substituted out during a match when `1`
`yellow_cards`	`players` - `statistics`	Integer	Player yellow cards for a match
`yellow_red_cards`	`players` - `statistics`	Integer	Total team red cards for a match which resulted from two yellow cards