Syntax

https://api.sportradar.com/soccer/{access_level}/{version}/stream/statistics/subscribe

Parameters

Parameter	Description
`access_level`	Defines the access level of your API key `production`, `trial`
`version`	Version number of the API `v4`

Optional Query String Parameters

By default, a Push feed will provide all data available for all in progress games. If needed, you can filter the data returned by including query strings.

Each query string parameter can be added with a preceding ampersand (&).

URL Parameters	Description
`competition_id`	Competition id Example: `competition_id=sr:competition:204`
`event_id`	Event type Example: `event_id=free_kick`
`format`	Format type `json`, `xml` Example: `format=json`
`season_id`	Season id Example: `season_id=sr:season:50039`
`sport_event_id`	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/events/subscribe")

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)
request["x-api-key"] = "{your_api_key}"  # Replace with your actual key

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

import requests
import json

headers = {
    'x-api-key': 'your_api_key'  # Replace with your actual key
}

r = requests.get(
    "https://api.sportradar.com/soccer/trial/v4/stream/events/subscribe",
    headers=headers,
    allow_redirects=False
)

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

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 -X GET 'https://api.sportradar.com/soccer/trial/v4/stream/events/subscribe' \
  -H 'x-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/events/subscribe?&format=json&sport_event_id=sr:sport_event: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)
request["x-api-key"] = "{your_api_key}"  # Replace with your actual key

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

import requests
import json

headers = {
    'x-api-key': 'your_api_key'  # Replace with your actual key
}

r = requests.get("https://api.sportradar.com/soccer/trial/v4/stream/events/subscribe",
    params = {'format': 'json', 'sport_event_id': 'sr:sport_event:13468929'},
    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 -X GET 'api.sportradar.com/soccer/trial/v4/stream/events/subscribe?&format=json&sport_event_id=sr:sport_event:13468929'
  -H 'x-api-key: {your_api_key}'

Response Sample

The above commands return json like this.

Data Points

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

Attribute	Parent Element	Type	Description
`aggregate_away_score`	`sport_event_status`	Integer	Aggregate score (of multiple sport events) for the away team
`aggregate_home_score`	`sport_event_status`	Integer	Aggregate score (of multiple sport events) for the home team
`aggregate_winner_id`	`sport_event_status`	String	Unique ID of the aggregate score winner ex. `sr:competitor:44`
`away_normaltime_score`	`sport_event_status`	Integer	Score for the away team in normal time
`away_overtime_score`	`sport_event_status`	Integer	Score for the away team in overtime
`away_score`	`sport_event_status`	Integer	Total score for the away team in the match
`home_normaltime_score`	`sport_event_status`	Integer	Score for the home team in normal time
`home_overtime_score`	`sport_event_status`	Integer	Score for the home team in overtime
`home_score`	`sport_event_status`	Integer	Total score for the home team in the match
`match_status`	`sport_event_status`	String	Status within a match. Provides more detail on the state of a match when live than `status` ex. `not_started`, `2nd_half`, `ended`, `awaiting_penalties` See our FAQ for a complete list of statuses and their definitions.
`match_tie`	`sport_event_status`	Boolean	Signifies a match ended in a tie when `true`
`scout_abandoned`	`sport_event_status`	Boolean	Signifies a match was abandoned by a scout when `true`
`status`	`sport_event_status`	String	Status of a match ex. `not_started`, `live`, `ended`, `awaiting_penalties` See our FAQ for a complete list of statuses and their definitions.
`winner_id`	`sport_event_status`	String	Unique ID of the match winner ex. `sr:competitor:44`

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 situation 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 when `true`. Used for placeholder teams in TBD vs TBD matchups.

Match Stats (Team)

Attribute	Parent Element	Type	Description
`ball_possession`	`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 substitutions 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