statsbombpy 1.14.0

easily stream StatsBomb data into Python

statsbombpy

Brought to you by StatsBomb, this repository is a Python package that allows users to easily stream StatsBomb data into Python using your log in credentials for the API or free data from our GitHub page. API access is for paying customers only

Support: [e-mail]

Installation Instructions

pip install statsbombpy

Running the tests

nose2 -v --pretty-assert

Configuration

Authentication

Environment Variables

Authentication can be done by setting environment variables named SB_USERNAME and SB_PASSWORD to your login credentials.

Manual Calls

Alternatively, if you don't want to use environment variables, all functions accept an argument creds to pass your login credentials in the format {"user": "", "passwd": ""}

Concurrency

You can specify how many of your computer's cores to use when running the sb.competition_events() and sb.competition_frames() functions by setting the environment variable SB_CORES to the number you want to use. Allowing statsbombpy to use more cores will speed up those functions.

If you don't have an environment variable set we will try to detect the number of cores in your system and use 2 less than that number. If we cannot detect the number of cores we set the number to 4.

Open Data

StatsBomb's open data can be accessed without the need of authentication.

StatsBomb are committed to sharing new data and research publicly to enhance understanding of the game of Football. We want to actively encourage new research and analysis at all levels. Therefore we have made certain leagues of StatsBomb Data freely available for public use for research projects and genuine interest in football analytics.

StatsBomb are hoping that by making data freely available, we will extend the wider football analytics community and attract new talent to the industry. We would like to collect some basic personal information about users of our data. By giving us your email address, it means we will let you know when we make more data, tutorials and research available. We will store the information in accordance with our Privacy Policy and the GDPR.

Terms & Conditions

Whilst we are keen to share data and facilitate research, we also urge you to be responsible with the data. Please register your details on https://www.statsbomb.com/resource-centre and read our User Agreement carefully. By using this repository, you are agreeing to the user agreement. If you publish, share or distribute any research, analysis or insights based on this data, please state the data source as StatsBomb and use our logo.

Usage

from statsbombpy import sb

Competitions

sb.competitions()

	competition_id	season_id	country_name	competition_name	competition_gender	season_name	match_updated	match_available
0	9	42	Germany	1. Bundesliga	male	2019/2020	2019-12-29T07:47:45.981	2019-12-29T07:47:45.981
1	9	4	Germany	1. Bundesliga	male	2018/2019	2019-12-16T23:09:16.168756	2019-12-16T23:09:16.168756
2	9	1	Germany	1. Bundesliga	male	2017/2018	2019-12-16T23:09:16.168756	2019-12-16T23:09:16.168756
3	78	42	Croatia	1. HNL	male	2019/2020	2020-01-02T10:35:49.065	2020-01-02T10:35:49.065
4	10	42	Germany	2. Bundesliga	male	2019/2020	2019-12-27T00:36:37.498	2019-12-27T00:36:37.498

Matches

sb.matches(competition_id=9, season_id=42)

	match_id	match_date	kick_off	competition	season	home_team	away_team	home_score	away_score	match_status	last_updated	match_week	competition_stage	stadium	referee	home_managers	away_managers	data_version	shot_fidelity_version	xy_fidelity_version
0	303299	2019-12-15	18:00:00.000	Germany - 1. Bundesliga	2019/2020	Schalke 04	Eintracht Frankfurt	1	0	available	2019-12-17T09:50:17.558	15	Regular Season	VELTINS-Arena	F. Zwayer	David Wagner	Adi Hütter	1.1.0	2	2
1	303223	2019-09-01	18:00:00.000	Germany - 1. Bundesliga	2019/2020	Eintracht Frankfurt	Fortuna Düsseldorf	2	1	available	2019-12-16T23:09:16.168756	3	Regular Season	Commerzbank-Arena	F. Willenborg	Adi Hütter	Friedhelm Funkel	1.1.0	2	2
2	303083	2019-12-15	15:30:00.000	Germany - 1. Bundesliga	2019/2020	Wolfsburg	Borussia Mönchengladbach	2	1	available	2019-12-17T15:52:17.843	15	Regular Season	VOLKSWAGEN ARENA	F. Brych	Oliver Glasner	Marco Rose	1.1.0	2	2
3	303266	2019-12-14	15:30:00.000	Germany - 1. Bundesliga	2019/2020	Hertha Berlin	Freiburg	1	0	available	2019-12-17T17:43:18.285	15	Regular Season	Olympiastadion Berlin	F. Willenborg	Jürgen Klinsmann	Christian Streich	1.1.0	2	2
4	303073	2019-12-21	15:30:00.000	Germany - 1. Bundesliga	2019/2020	Bayern Munich	Wolfsburg	2	0	available	2019-12-23T18:02:36.454	17	Regular Season	Allianz Arena	C. Dingert	Hans-Dieter Flick	Oliver Glasner	1.1.0	2	2

Lineups

sb.lineups(match_id=303299)["Eintracht Frankfurt"]

	player_id	player_name	player_nickname	birth_date	player_gender	player_height	player_weight	jersey_number	country
0	3204	Almamy Touré	None	1996-04-28	male	182.0	72.0	18	Mali
1	5591	Filip Kostić	None	1992-11-01	male	184.0	82.0	10	Serbia
2	7713	Obite Evan N"Dicka	Evan N'Dicka	1999-08-20	male	190.0	NaN	2	France
3	8307	Martin Hinteregger	None	1992-09-07	male	184.0	83.0	13	Austria
4	8669	Mijat Gaćinović	None	1995-02-08	male	175.0	66.0	11	Serbia

Events

The default settings for querying events return a single dataframe with all event types and event attributes.

events = sb.events(match_id=303299)

	ball_receipt_outcome	ball_recovery_offensive	ball_recovery_recovery_failure	block_deflection	carry_end_location	clearance_aerial_won	clearance_body_part	clearance_head	clearance_left_foot	clearance_right_foot	counterpress	dribble_no_touch	dribble_outcome	dribble_overrun	duel_outcome	duel_type	duration	foul_committed_advantage	foul_committed_card	foul_won_advantage	foul_won_defensive	goalkeeper_body_part	goalkeeper_end_location	goalkeeper_outcome	goalkeeper_position	goalkeeper_technique	goalkeeper_type	id	index	injury_stoppage_in_chain	interception_outcome	location	match_id	minute	off_camera	out	pass_aerial_won	pass_angle	pass_assisted_shot_id	pass_body_part	pass_cross	pass_cut_back	pass_deflected	pass_end_location	pass_goal_assist	pass_height	pass_length	pass_outcome	pass_outswinging	pass_recipient	pass_shot_assist	pass_straight	pass_switch	pass_technique	pass_through_ball	pass_type	pass_xclaim	period	play_pattern	player	position	possession	possession_team	related_events	second	shot_aerial_won	shot_body_part	shot_end_location	shot_first_time	shot_freeze_frame	shot_key_pass_id	shot_one_on_one	shot_outcome	shot_statsbomb_xg	shot_statsbomb_xg2	shot_technique	shot_type	substitution_outcome	substitution_replacement	team	timestamp	type	under_pressure
500	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	3.498736	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	84828c06-41b5-44eb-aa92-1710bdb818ac	1838	NaN	NaN	[50.1, 16.6]	303299	47	NaN	NaN	NaN	2.720095	NaN	Left Foot	NaN	NaN	NaN	[13.3, 33.1]	NaN	Ground Pass	40.329765	NaN	NaN	Frederik Rønnow	NaN	NaN	NaN	NaN	NaN	NaN	NaN	2	Regular Play	Obite Evan N"Dicka	Left Center Back	103	Eintracht Frankfurt	[ae3094e3-faa3-4608-8284-d9b8cca77711, c1202f1c-0831-4e88-83b2-597f56f0c858]	52	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	Eintracht Frankfurt	00:02:52.438	Pass	True
501	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	3.604236	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	9061cd20-513b-499f-b925-f1de5f241281	1840	NaN	NaN	[13.3, 33.1]	303299	47	NaN	NaN	NaN	-0.153945	NaN	Right Foot	NaN	NaN	NaN	[77.1, 23.2]	NaN	High Pass	64.563540	Incomplete	NaN	Mijat Gaćinović	NaN	NaN	NaN	NaN	NaN	NaN	NaN	2	Regular Play	Frederik Rønnow	Goalkeeper	103	Eintracht Frankfurt	[8e6495a7-782a-4f1a-845f-3ec50d761a1e, ff758a12-1ba6-4dd4-8b2c-7d39aa7aed97]	55	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	Eintracht Frankfurt	00:02:55.937	Pass	NaN
502	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	2.101999	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	8e6495a7-782a-4f1a-845f-3ec50d761a1e	1842	NaN	NaN	[43.0, 56.9]	303299	47	NaN	NaN	NaN	-0.703110	NaN	Head	NaN	NaN	NaN	[64.0, 39.1]	NaN	High Pass	27.528894	NaN	NaN	Amine Harit	NaN	NaN	NaN	NaN	NaN	Recovery	NaN	2	Regular Play	Ozan Muhammed Kabak	Right Center Back	104	Schalke 04	[9061cd20-513b-499f-b925-f1de5f241281, be6dfe7d-7596-4cc2-8cd9-8c17d064317e]	59	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	Schalke 04	00:02:59.541	Pass	NaN
503	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	1.187459	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	86431bc7-210a-4868-8e18-26ff38becefc	1854	NaN	NaN	[65.9, 12.6]	303299	48	NaN	NaN	NaN	-0.730239	NaN	Right Foot	NaN	NaN	NaN	[74.5, 4.9]	NaN	Ground Pass	11.543396	NaN	NaN	Amine Harit	NaN	NaN	NaN	NaN	NaN	NaN	NaN	2	Regular Play	Suat Serdar	Left Defensive Midfield	104	Schalke 04	[761b4e65-8f64-464c-8153-6a98465208ba]	7	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	Schalke 04	00:03:07.689	Pass	NaN
504	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	0.766628	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	6e58c713-622c-4246-8243-e4162e487a1c	1858	NaN	NaN	[79.1, 10.5]	303299	48	NaN	NaN	NaN	1.254940	NaN	Right Foot	NaN	NaN	NaN	[84.1, 25.8]	NaN	Ground Pass	16.096273	NaN	NaN	Rabbi Matondo	NaN	NaN	NaN	NaN	NaN	NaN	NaN	2	Regular Play	Amine Harit	Center Attacking Midfield	104	Schalke 04	[b1960a76-d3ae-4ef3-a2cd-47eca8c25e0a, dd1575c0-a408-4177-944d-7e86d2f79181]	11	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	Schalke 04	00:03:11.719	Pass	True

It's also possible to get distinct dataframes for each event type and/or to have distinct event attributes on their own columns

sb.events(match_id=303299, split=True, flatten_attrs=False)["dribbles"]

	id	index	period	timestamp	minute	second	type	possession	possession_team	play_pattern	team	player	position	location	duration	under_pressure	related_events	dribble	match_id
0	b190c01f-ad24-468c-8241-f955b91d996c	131	1	00:02:08.032	2	8	Dribble	4	Schalke 04	Regular Play	Schalke 04	Daniel Caligiuri	Right Wing	[110.2, 62.9]	0.000000	True	[60f822df-5747-4787-b0f9-45bf5217eb8a]	{'outcome': {'id': 8, 'name': 'Complete'}}	303299
1	4d773c92-f89f-491e-b3e0-3a1d2e863148	399	1	00:08:48.623	8	48	Dribble	18	Schalke 04	Regular Play	Schalke 04	Amine Harit	Center Attacking Midfield	[88.9, 22.7]	0.000000	True	[93d829df-eea7-416b-95aa-7593828cfade]	{'outcome': {'id': 8, 'name': 'Complete'}}	303299
2	8a78dce4-998a-4e81-902c-9f3957cebc9d	460	1	00:13:30.202	13	30	Dribble	23	Schalke 04	Regular Play	Schalke 04	Daniel Caligiuri	Right Wing	[99.5, 68.1]	0.007309	True	[772c5aae-e34e-4364-8a98-7caf7636c90b]	{'outcome': {'id': 9, 'name': 'Incomplete'}}	303299
3	e44d0122-2f2e-4771-820d-cc326a8b0379	496	1	00:14:10.135	14	10	Dribble	24	Schalke 04	From Throw In	Schalke 04	Suat Serdar	Left Defensive Midfield	[41.2, 31.7]	0.000000	True	[4de4039f-7efc-461b-b7d6-27c32ec2cd2a]	{'outcome': {'id': 8, 'name': 'Complete'}}	303299
4	9555afbd-d838-42c9-8f80-be3cd09e4c4a	793	1	00:20:18.409	20	18	Dribble	33	Eintracht Frankfurt	Regular Play	Eintracht Frankfurt	Timothy Chandler	Right Wing Back	[81.8, 75.7]	0.000000	True	[a5c88cee-6319-4c25-91cd-8a028d8dbfbf]	{'outcome': {'id': 9, 'name': 'Incomplete'}}	303299

Competition Events

All events from a given competition can be queried and stored on a single dataframe

events = sb.competition_events(
    country="Germany",
    division= "1. Bundesliga",
    season="2019/2020",
    gender="male"
)

grouped_events = sb.competition_events(
    country="Germany",
    division= "1. Bundesliga",
    season="2019/2020",
    split=True
)
grouped_events["dribbles"]

	id	index	period	timestamp	minute	second	type	possession	possession_team	play_pattern	team	player	position	location	duration	under_pressure	related_events	dribble	match_id
0	b190c01f-ad24-468c-8241-f955b91d996c	131	1	00:02:08.032	2	8	Dribble	4	Schalke 04	Regular Play	Schalke 04	Daniel Caligiuri	Right Wing	[110.2, 62.9]	0.000000	True	[60f822df-5747-4787-b0f9-45bf5217eb8a]	{'outcome': {'id': 8, 'name': 'Complete'}}	303299
1	4d773c92-f89f-491e-b3e0-3a1d2e863148	399	1	00:08:48.623	8	48	Dribble	18	Schalke 04	Regular Play	Schalke 04	Amine Harit	Center Attacking Midfield	[88.9, 22.7]	0.000000	True	[93d829df-eea7-416b-95aa-7593828cfade]	{'outcome': {'id': 8, 'name': 'Complete'}}	303299
2	8a78dce4-998a-4e81-902c-9f3957cebc9d	460	1	00:13:30.202	13	30	Dribble	23	Schalke 04	Regular Play	Schalke 04	Daniel Caligiuri	Right Wing	[99.5, 68.1]	0.007309	True	[772c5aae-e34e-4364-8a98-7caf7636c90b]	{'outcome': {'id': 9, 'name': 'Incomplete'}}	303299
3	e44d0122-2f2e-4771-820d-cc326a8b0379	496	1	00:14:10.135	14	10	Dribble	24	Schalke 04	From Throw In	Schalke 04	Suat Serdar	Left Defensive Midfield	[41.2, 31.7]	0.000000	True	[4de4039f-7efc-461b-b7d6-27c32ec2cd2a]	{'outcome': {'id': 8, 'name': 'Complete'}}	303299
4	9555afbd-d838-42c9-8f80-be3cd09e4c4a	793	1	00:20:18.409	20	18	Dribble	33	Eintracht Frankfurt	Regular Play	Eintracht Frankfurt	Timothy Chandler	Right Wing Back	[81.8, 75.7]	0.000000	True	[a5c88cee-6319-4c25-91cd-8a028d8dbfbf]	{'outcome': {'id': 9, 'name': 'Incomplete'}}	303299

360 Metrics

If you have access to 360 data for a competition, you can set include_360_metrics=True in the events() and competition_events() functions to retrieve 360 metrics such a line breaking passess together with the event data.

The open data does not include the 360 metrics. This is currently only available to customers with a data subscription.

events = sb.events(match_id=3837323, include_360_metrics=True)
comp_events = sb.competition_events(
            country="Europe",
            division="Champions League",
            season="2022/2023",
            include_360_metrics=True,
)
comp_events

	50_50	bad_behaviour_card	ball_receipt_exceeds_distance	ball_receipt_in_space	ball_receipt_outcome	ball_recovery_offensive	ball_recovery_recovery_failure	block_deflection	block_offensive	block_save_block	carry_end_location	clearance_aerial_won	clearance_body_part	clearance_head	clearance_left_foot	clearance_other	clearance_right_foot	counterpress	distance_to_nearest_defender	dribble_no_touch	dribble_nutmeg	dribble_outcome	dribble_overrun	duel_outcome	duel_type	duration	foul_committed_advantage	foul_committed_card	foul_committed_offensive	foul_committed_penalty	foul_committed_type	foul_won_advantage	foul_won_defensive	foul_won_penalty	goalkeeper_body_part	goalkeeper_end_location	goalkeeper_lost_in_play	goalkeeper_lost_out	goalkeeper_outcome	goalkeeper_position	goalkeeper_punched_out	goalkeeper_shot_saved_off_target	goalkeeper_shot_saved_to_post	goalkeeper_success_in_play	goalkeeper_technique	goalkeeper_type	half_start_late_video_start	id	index	injury_stoppage_in_chain	interception_outcome	line_breaking_pass	location	minute	miscontrol_aerial_won	num_defenders_on_goal_side_of_actor	obv_against_after	obv_against_before	obv_against_net	obv_for_after	obv_for_before	obv_for_net	obv_total_net	off_camera	out	pass_aerial_won	pass_angle	pass_assisted_shot_id	pass_body_part	pass_cross	pass_cut_back	pass_deflected	pass_end_location	pass_goal_assist	pass_height	pass_inswinging	pass_length	pass_miscommunication	pass_no_touch	pass_outcome	pass_outswinging	pass_recipient	pass_shot_assist	pass_straight	pass_switch	pass_technique	pass_through_ball	pass_type	pass_xclaim	period	play_pattern	player	player_id	player_off_permanent	position	possession	possession_team	possession_team_id	related_events	second	shot_aerial_won	shot_body_part	shot_deflected	shot_end_location	shot_first_time	shot_freeze_frame	shot_key_pass_id	shot_one_on_one	shot_open_goal	shot_outcome	shot_redirect	shot_saved_off_target	shot_saved_to_post	shot_statsbomb_xg	shot_statsbomb_xg2	shot_technique	shot_type	substitution_outcome	substitution_replacement	team	timestamp	type	under_pressure	visible_opponents	visible_teammates
0	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	0.0	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	3479244f-8234-43c9-a389-4ce587062b48	1	NaN	NaN	NaN	NaN	0	NaN	NaN	None	None	None	None	None	None	None	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	1	Regular Play	NaN	NaN	NaN	NaN	1	Real Madrid	220	NaN	0	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	Real Madrid	00:00:00.000	Starting XI	NaN	NaN	NaN
1	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	0.0	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	c4f5a51b-741e-4920-ac32-02349b1f2755	2	NaN	NaN	NaN	NaN	0	NaN	NaN	None	None	None	None	None	None	None	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	1	Regular Play	NaN	NaN	NaN	NaN	1	Real Madrid	220	NaN	0	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	Celtic	00:00:00.000	Starting XI	NaN	NaN	NaN
2	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	0.0	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	27be67e7-fdb5-4db9-92b6-8f3214cecec4	1	NaN	NaN	NaN	NaN	0	NaN	NaN	None	None	None	None	None	None	None	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	1	Regular Play	NaN	NaN	NaN	NaN	1	Juventus	224	NaN	0	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	Juventus	00:00:00.000	Starting XI	NaN	NaN	NaN
3	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	0.0	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	819c381e-29c1-4f10-a6c3-acc3181cec14	2	NaN	NaN	NaN	NaN	0	NaN	NaN	None	None	None	None	None	None	None	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	1	Regular Play	NaN	NaN	NaN	NaN	1	Juventus	224	NaN	0	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	Paris Saint-Germain	00:00:00.000	Starting XI	NaN	NaN	NaN
4	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	0.0	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	e6d42d87-c78a-4286-94fd-4095e9f7b16f	1	NaN	NaN	NaN	NaN	0	NaN	NaN	None	None	None	None	None	None	None	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	1	Regular Play	NaN	NaN	NaN	NaN	1	Manchester City	36	NaN	0	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	Manchester City	00:00:00.000	Starting XI	NaN	NaN	NaN

360 Frames

The frame functions will return the raw 360 freeze frame data along with the visible area for each frame. This is returned at the player level so you have multiple rows per frame/event_id.

match_frames = sb.frames(match_id=3772072, fmt='dataframe')
comp_frames = sb.competition_frames(
    country="Germany",
    division= "1. Bundesliga",
    season="2019/2020"
)
match_frames

	actor	distance_from_edge_of_visible_area	event_uuid	keeper	location	match_id	teammate	visible_area
0	False	5.183739	065b15cc-b550-48de-9a1e-a9608d8e6c6d	False	[79.14114105224532, 12.646560364129726]	3855869	False	[50.8965834880119, 80.0, 55.8915648466696, 6.76382112514142, 80.0765213141343, 1.48859955554994, 113.056993108772, 80.0, 50.8965834880119, 80.0]
1	False	7.784551	065b15cc-b550-48de-9a1e-a9608d8e6c6d	False	[80.68650097437124, 23.040779651892883]	3855869	True	[50.8965834880119, 80.0, 55.8915648466696, 6.76382112514142, 80.0765213141343, 1.48859955554994, 113.056993108772, 80.0, 50.8965834880119, 80.0]
2	False	8.873694	065b15cc-b550-48de-9a1e-a9608d8e6c6d	False	[80.20033992405365, 24.695673759901382]	3855869	False	[50.8965834880119, 80.0, 55.8915648466696, 6.76382112514142, 80.0765213141343, 1.48859955554994, 113.056993108772, 80.0, 50.8965834880119, 80.0]
3	False	9.738309	065b15cc-b550-48de-9a1e-a9608d8e6c6d	False	[82.43349155444821, 32.24426347120625]	3855869	False	[50.8965834880119, 80.0, 55.8915648466696, 6.76382112514142, 80.0765213141343, 1.48859955554994, 113.056993108772, 80.0, 50.8965834880119, 80.0]
4	False	11.049633	065b15cc-b550-48de-9a1e-a9608d8e6c6d	False	[81.320294294838, 32.98015558905158]	3855869	True	[50.8965834880119, 80.0, 55.8915648466696, 6.76382112514142, 80.0765213141343, 1.48859955554994, 113.056993108772, 80.0, 50.8965834880119, 80.0]

Aggregated Stats

For customers we also provide aggregated statistics at the player-match, player-season and team-season levels.

player_match = sb.player_match_stats(3772072)
player_season = sb.player_season_stats(competition_id=9, season_id=42)
team_match = sb.team_match_stats(3772072)
team_season = sb.team_season_stats(competition_id=9, season_id=42)

player_match

	player_match_pressures	player_match_long_balls	player_match_shot_touch_ratio	player_match_passes_into_box	player_match_pressure_duration_avg	player_match_crossing_ratio	player_match_op_f3_forward_passes	player_match_passing_ratio	team_id	player_match_successful_passes	player_match_op_xgbuildup_per_possession	player_match_op_xgchain	player_match_op_passes_into_box	player_match_deep_progressions	player_match_turnovers	player_match_counterpressured_action_fails	player_match_passes	player_match_key_passes	player_match_dispossessions	player_match_penalties_won	player_match_through_balls	team_name	player_match_op_passes	player_match_dribbles	player_match_clearances	player_match_forward_passes	player_match_np_xg_per_shot	player_match_counterpressures	player_id	player_match_op_xa	player_match_op_xgchain_per_possession	player_match_minutes	player_match_pressured_long_balls	player_match_op_f3_sideways_passes	player_match_dribbles_faced	player_match_np_xg	player_match_goals	player_match_op_key_passes	player_match_aerial_ratio	player_match_op_shots	player_match_successful_crosses	player_match_shots_blocked	player_match_op_f3_passes	player_match_op_assists	player_match_long_ball_ratio	account_id	player_match_np_shots	player_match_challenge_ratio	player_match_touches	player_match_pressure_regains	player_match_crosses_into_box	player_match_fouls	player_match_sideways_passes	player_match_aerials	player_match_touches_inside_box	player_match_counterpressure_duration_total	player_match_successful_aerials	player_match_box_cross_ratio	player_match_xgbuildup_per_possession	player_match_dribbled_past	player_match_pressure_duration_total	player_match_op_xgbuildup	player_match_np_shots_on_target	player_match_interceptions	player_match_counterpressure_duration_avg	player_match_xgchain_per_possession	player_match_successful_long_balls	player_match_op_f3_backward_passes	player_match_xgchain	player_match_tackles	player_match_assists	player_match_sp_xa	player_match_aggressive_actions	player_name	player_match_xa	match_id	player_match_passes_inside_box	player_match_possession	player_match_pressured_action_fails	player_match_crosses	player_match_fouls_won	player_match_xgbuildup	player_match_backward_passes	player_match_unpressured_long_balls	player_match_np_goals
0	NaN	10	0.000000	0	NaN	NaN	0	0.842105	870	32	0.003191	0.105292	0	0	0	NaN	38	0	0	0	0	Arminia Bielefeld	33	0	0	9	NaN	NaN	9194	0.000000	0.003191	94.21667	1	0	0	0.000000	0	0	NaN	0	0	0	0	0	0.600000	48	0	NaN	65	0	0	0	29	0	0	NaN	0	NaN	0.003191	0	NaN	0.105292	0	0	NaN	0.003191	6	0	0.105292	0	0	0.000000	0	Stefan Ortega	0.000000	3772072	0	0.491135	NaN	0	0	0.105292	0	9	0
1	8.0	0	0.033333	0	0.570626	0.0	0	0.812500	870	13	0.003726	0.160582	0	1	3	0.0	16	1	3	0	0	Arminia Bielefeld	10	1	1	0	0.034737	1.0	9210	0.043881	0.007299	91.90000	1	4	0	0.034737	0	1	0.285714	1	0	0	6	0	NaN	48	1	1.0	30	0	0	0	10	7	5	0.327541	2	NaN	0.003726	0	4.565010	0.081964	0	0	0.327541	0.007299	0	2	0.160582	1	0	0.000000	9	Fabian Klos	0.043881	3772072	1	0.491135	0.0	1	1	0.081964	6	0	0
2	7.0	13	0.000000	1	1.795411	0.0	1	0.852941	190	58	0.017993	0.773687	0	3	0	0.0	68	1	0	0	0	Union Berlin	60	0	2	4	NaN	0.0	9164	0.000000	0.017993	94.21667	2	3	0	0.000000	0	0	0.666667	0	0	1	4	0	0.615385	48	0	1.0	122	1	0	2	51	3	0	NaN	2	0.0	0.017993	0	12.567875	0.773687	0	1	NaN	0.019504	8	0	0.838693	2	0	0.043227	11	Christopher Trimmel	0.043227	3772072	0	0.508865	0.0	1	0	0.773687	13	13	0
3	3.0	4	0.013699	1	0.744943	NaN	1	0.777778	870	35	0.002196	0.090022	1	1	1	0.0	45	0	1	0	0	Arminia Bielefeld	40	0	1	18	0.019468	0.0	24343	0.000000	0.002196	94.21667	1	1	0	0.019468	0	0	0.000000	1	0	1	2	0	0.750000	48	1	NaN	73	0	0	0	22	1	1	NaN	0	0.0	0.003043	0	2.234830	0.090022	0	0	NaN	0.003043	3	0	0.124760	0	0	0.000000	3	Jacob Laursen	0.000000	3772072	0	0.491135	0.0	0	1	0.124760	5	4	0
4	14.0	6	0.000000	0	0.592216	NaN	0	0.763158	870	29	0.006048	0.211669	0	1	0	0.0	38	0	2	0	0	Arminia Bielefeld	36	0	1	7	NaN	2.0	9204	0.000000	0.006048	94.21667	1	1	3	0.000000	0	0	0.500000	0	0	0	1	0	1.000000	48	0	0.0	64	1	0	4	29	2	0	0.676610	1	NaN	0.006048	3	8.291025	0.211669	0	2	0.338305	0.006048	6	0	0.211669	0	0	0.000000	18	Manuel Prietl	0.000000	3772072	0	0.491135	0.0	0	1	0.211669	2	6	0

Raw Files

Alternatively, entities can be accessed as python dictionaries serving as an interface to raw jsons and without performing any preprocessing

sb.competitions(fmt="dict")

sb.matches(competition_id=9, season_id=42, fmt="dict")

sb.lineups(match_id=303299, fmt="dict")

sb.events(303299, fmt="dict")

sb.competition_events(
    country="Germany",
    division= "1. Bundesliga",
    season="2019/2020",
    gender="male",
    fmt="dict"
)

sb.frames(3772072, fmt="dict")

sb.competition_frames(
    country="Germany",
    division= "1. Bundesliga",
    season="2021/2022",
    gender="male",
    fmt="dict"
)

sb.player_match_stats(3772072, fmt="dict")

sb.player_season_stats(competition_id=9, season_id=42, fmt="dict")

sb.team_match_stats(3772072, fmt="dict")

sb.team_season_stats(competition_id=9, season_id=42, fmt="dict")