mplsoccer.statsbomb module

mplsoccer.statsbomb is a python module for loading StatsBomb open, local and API data.

class mplsoccer.statsbomb.Sbopen(dataframe=True)[source]

Bases: object

Class for loading data from the StatsBomb open-data. The data is available at: https://github.com/statsbomb/open-data under a non-commercial license.

Parameters:

dataframe (bool, default True) – Whether to return dataframes (True) or flattened list of dictionaries (False) from the class methods.

Methods

competition()

StatsBomb competition open-data.

event(match_id)

StatsBomb event open-data.

frame(match_id)

StatsBomb 360 open-data.

lineup(match_id)

StatsBomb lineup open-data.

match(competition_id, season_id)

StatsBomb match open-data.

event(match_id)[source]

StatsBomb event open-data.

Parameters:

match_id (int)

Returns:

Either dataframes or flattened list of dictionaries.

Return type:

events, related, freeze, tactics

Examples

>>> from mplsoccer import Sbopen
>>> parser = Sbopen(dataframe=True)
>>> events, related, freeze, tactics = parser.event(3788741)
lineup(match_id)[source]

StatsBomb lineup open-data.

Parameters:

match_id (int)

Returns:

A dataframe or a flattened list of dictionaries.

Return type:

lineups

Examples

>>> from mplsoccer import Sbopen
>>> parser = Sbopen(dataframe=True)
>>> lineups = parser.lineup(3788741)
match(competition_id, season_id)[source]

StatsBomb match open-data.

Parameters:
  • competition_id (int)

  • season_id (int)

Returns:

A dataframe or a flattened list of dictionaries.

Return type:

matches

Examples

>>> from mplsoccer import Sbopen
>>> parser = Sbopen(dataframe=True)
>>> matches = parser.match(11, 1)
competition()[source]

StatsBomb competition open-data.

Returns:

A dataframe or a flattened list of dictionaries.

Return type:

competition

Examples

>>> from mplsoccer import Sbopen
>>> parser = Sbopen(dataframe=True)
>>> competition = parser.competition()
frame(match_id)[source]

StatsBomb 360 open-data.

Parameters:

match_id (int)

Returns:

Either dataframes or flattened list of dictionaries.

Return type:

frames, visible

Examples

>>> from mplsoccer import Sbopen
>>> parser = Sbopen(dataframe=True)
>>> frames, visible = parser.frame(3788741)
class mplsoccer.statsbomb.Sbapi(username=None, password=None, dataframe=True)[source]

Bases: object

Class for loading data from the StatsBomb API. You can either set the SB_USERNAME and SB_PASSWORD environmental variables or use the username and password arguments.

Parameters:
  • username (str, default None) – Username for accessing StatsBomb API. If None then uses the SB_USERNAME environmental variable.

  • password (str, default None) – Password for accessing the StatsBomb API. If None then uses the SB_PASSWORD environmental variable.

  • dataframe (bool, default True) – Whether to return dataframes (True) or flattened list of dictionaries (False) from the class methods.

Methods

competition([version])

StatsBomb competition from the API.

event(match_id[, version])

StatsBomb event data from the API.

frame(match_id[, version])

StatsBomb 360 data from the API.

lineup(match_id[, version])

StatsBomb lineup data from the API.

match(competition_id, season_id[, version])

StatsBomb match data from the API.

event(match_id, version=6)[source]

StatsBomb event data from the API.

Parameters:
  • match_id (int)

  • version (int, default 6)

Returns:

Either dataframes or flattened list of dictionaries.

Return type:

events, related, freeze, tactics

Examples

>>> from mplsoccer import Sbapi
>>> parser = Sbapi(dataframe=True)
>>> events, related, freeze, tactics = parser.event(3788741)
lineup(match_id, version=2)[source]

StatsBomb lineup data from the API.

Parameters:
  • match_id (int)

  • version (int, default 2)

Returns:

A dataframe or a flattened list of dictionaries.

Return type:

lineups

Examples

>>> from mplsoccer import Sbapi
>>> parser = Sbapi(dataframe=True)
>>> lineups = parser.lineup(3788741)
match(competition_id, season_id, version=5)[source]

StatsBomb match data from the API.

Parameters:
  • competition_id (int)

  • season_id (int)

  • version (int)

Returns:

A dataframe or a flattened list of dictionaries.

Return type:

matches

Examples

>>> from mplsoccer import Sbapi
>>> parser = Sbapi(dataframe=True)
>>> matches = parser.match(11, 1)
competition(version=4)[source]

StatsBomb competition from the API.

Parameters:

version (int, default 4)

Returns:

A dataframe or a flattened list of dictionaries.

Return type:

competition

Examples

>>> from mplsoccer import Sbapi
>>> parser = Sbapi(dataframe=True)
>>> competition = parser.competition()
frame(match_id, version=1)[source]

StatsBomb 360 data from the API.

Parameters:
  • match_id (int)

  • version (int, default 1)

Returns:

Either dataframes or flattened list of dictionaries.

Return type:

frames, visible

Examples

>>> from mplsoccer import Sbapi
>>> parser = Sbapi(dataframe=True)
>>> frames, visible = parser.frame(3788741)
class mplsoccer.statsbomb.Sblocal(dataframe=True)[source]

Bases: object

Class for loading local StatsBomb data.

Parameters:

dataframe (bool, default True) – Whether to return dataframes (True) or flattened list of dictionaries (False) from the class methods.

Methods

competition(path)

Read the competition data from a local file.

event(path)

Read the event data from a local file.

frame(path)

Read the 360 data from a local file.

lineup(path)

Read the lineup data from a local file.

match(path)

Read the match data from a local file.

event(path)[source]

Read the event data from a local file.

Parameters:

path (path to file)

Returns:

Either dataframes or flattened list of dictionaries.

Return type:

events, related, freeze, tactics

Examples

>>> from mplsoccer import Sblocal
>>> parser = Sblocal(dataframe=True)
>>> events, related, freeze, tactics = parser.event(path)
lineup(path)[source]

Read the lineup data from a local file.

Parameters:

path (path to file)

Returns:

A dataframe or a flattened list of dictionaries.

Return type:

lineups

Examples

>>> from mplsoccer import Sblocal
>>> parser = Sblocal(dataframe=True)
>>> lineups = parser.lineup(path)
match(path)[source]

Read the match data from a local file.

Parameters:

path (path to file)

Returns:

A dataframe or a flattened list of dictionaries.

Return type:

matches

Examples

>>> from mplsoccer import Sblocal
>>> parser = Sblocal(dataframe=True)
>>> matches = parser.match(path)
competition(path)[source]

Read the competition data from a local file.

Parameters:

path (path to file)

Returns:

A dataframe or a flattened list of dictionaries.

Return type:

competition

Examples

>>> from mplsoccer import Sblocal
>>> parser = Sblocal(dataframe=True)
>>> competition = parser.competition(path)
frame(path)[source]

Read the 360 data from a local file.

Parameters:

path (path to file)

Returns:

Either dataframes or flattened list of dictionaries.

Return type:

frames, visible

Examples

>>> from mplsoccer import Sblocal
>>> parser = Sblocal(dataframe=True)
>>> frames, visible = parser.frame(path)