Skip to content

Sportec Solutions

kloppy.sportec

Functions for loading Sportec Solutions event and tracking data.

load_event 

1
2
3
4
5
6
7
load_event(
    event_data,
    meta_data,
    event_types=None,
    coordinates=None,
    event_factory=None,
)

Load Sportec Solutions event data.

PARAMETER DESCRIPTION
event_data

XML feed with the raw event data of a game.

TYPE: FileLike

meta_data

XML feed containing the metadata of the game.

TYPE: FileLike

event_types

A list of event types to load.

TYPE: Optional[List[str]] DEFAULT: None

coordinates

The coordinate system to use.

TYPE: Optional[str] DEFAULT: None

event_factory

A custom event factory.

TYPE: Optional[EventFactory] DEFAULT: None

RETURNS DESCRIPTION
EventDataset

The parsed event data.
Source code in kloppy/_providers/sportec.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def load_event(
    event_data: FileLike,
    meta_data: FileLike,
    event_types: Optional[List[str]] = None,
    coordinates: Optional[str] = None,
    event_factory: Optional[EventFactory] = None,
) -> EventDataset:
    """
    Load Sportec Solutions event data.

    Args:
        event_data: XML feed with the raw event data of a game.
        meta_data: XML feed containing the metadata of the game.
        event_types: A list of event types to load.
        coordinates: The coordinate system to use.
        event_factory: A custom event factory.

    Returns:
        The parsed event data.
    """
    serializer = SportecEventDataDeserializer(
        event_types=event_types,
        coordinate_system=coordinates,
        event_factory=event_factory or get_config("event_factory"),
    )
    with open_as_file(event_data) as event_data_fp, open_as_file(
        meta_data
    ) as meta_data_fp:
        return serializer.deserialize(
            SportecEventDataInputs(
                event_data=event_data_fp, meta_data=meta_data_fp
            )
        )

load_tracking 

1
2
3
4
5
6
7
8
load_tracking(
    meta_data,
    raw_data,
    sample_rate=None,
    limit=None,
    coordinates=None,
    only_alive=True,
)

Load Sportec Solutions tracking data.

PARAMETER DESCRIPTION
meta_data

A json feed containing the metadata of the game.

TYPE: FileLike

raw_data

A json feed containing the raw tracking data.

TYPE: FileLike

sample_rate

Sample the data at a specific rate.

TYPE: Optional[float] DEFAULT: None

limit

Limit the number of frames to load to the first limit frames.

TYPE: Optional[int] DEFAULT: None

coordinates

The coordinate system to use.

TYPE: Optional[str] DEFAULT: None

only_alive

Only include frames in which the game is not paused.

TYPE: Optional[bool] DEFAULT: True

RETURNS DESCRIPTION
TrackingDataset

The parsed tracking data.
Source code in kloppy/_providers/sportec.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def load_tracking(
    meta_data: FileLike,
    raw_data: FileLike,
    sample_rate: Optional[float] = None,
    limit: Optional[int] = None,
    coordinates: Optional[str] = None,
    only_alive: Optional[bool] = True,
) -> TrackingDataset:
    """
    Load Sportec Solutions tracking data.

    Args:
        meta_data: A json feed containing the metadata of the game.
        raw_data: A json feed containing the raw tracking data.
        sample_rate: Sample the data at a specific rate.
        limit: Limit the number of frames to load to the first `limit` frames.
        coordinates: The coordinate system to use.
        only_alive: Only include frames in which the game is not paused.

    Returns:
        The parsed tracking data.
    """
    deserializer = SportecTrackingDataDeserializer(
        sample_rate=sample_rate,
        limit=limit,
        coordinate_system=coordinates,
        only_alive=only_alive,
    )
    with open_as_file(meta_data) as meta_data_fp, open_as_file(
        raw_data
    ) as raw_data_fp:
        return deserializer.deserialize(
            inputs=SportecTrackingDataInputs(
                meta_data=meta_data_fp, raw_data=raw_data_fp
            )
        )

load_open_event_data 

1
2
3
4
5
6
load_open_event_data(
    match_id="J03WPY",
    event_types=None,
    coordinates=None,
    event_factory=None,
)

Load event data for a game from the IDSSE dataset.

The IDSSE dataset will be released with the publication of the An integrated dataset of synchronized spatiotemporal and event data in elite soccer paper [1]_ and is released under the Creative Commons Attribution 4.0 license.

PARAMETER DESCRIPTION
match_id

Match-ID of one of the matches. Defaults to 'J03WPY'. See below for available matches.

TYPE: str DEFAULT: 'J03WPY'

event_types

TYPE: Optional[List[str]] DEFAULT: None

coordinates

TYPE: Optional[str] DEFAULT: None

event_factory

TYPE: Optional[EventFactory] DEFAULT: None

Notes

The dataset contains seven full matches of raw event and position data for both teams and the ball from the German Men's Bundesliga season 2022/23 first and second division. A detailed description of the dataset as well as the collection process can be found in the accompanying paper.

The following matches are available::

matches = { 'J03WMX': 1. FC Köln vs. FC Bayern München, 'J03WN1': VfL Bochum 1848 vs. Bayer 04 Leverkusen, 'J03WPY': Fortuna Düsseldorf vs. 1. FC Nürnberg, 'J03WOH': Fortuna Düsseldorf vs. SSV Jahn Regensburg, 'J03WQQ': Fortuna Düsseldorf vs. FC St. Pauli, 'J03WOY': Fortuna Düsseldorf vs. F.C. Hansa Rostock, 'J03WR9': Fortuna Düsseldorf vs. 1. FC Kaiserslautern }

References

.. [1] Bassek, M., Rein, R., Weber, H. et al. "An integrated dataset of spatiotemporal and event data in elite soccer." Sci Data 12, 195 (2025). https://doi.org/10.1038/s41597-025-04505-y

Source code in kloppy/_providers/sportec.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
def load_open_event_data(
    match_id: str = "J03WPY",
    event_types: Optional[List[str]] = None,
    coordinates: Optional[str] = None,
    event_factory: Optional[EventFactory] = None,
) -> EventDataset:
    """
    Load event data for a game from the IDSSE dataset.

    The IDSSE dataset will be released with the publication of the *An integrated
    dataset of synchronized spatiotemporal and event data in elite soccer*
    paper [1]_ and is released under the Creative Commons Attribution 4.0
    license.

    Args:
        match_id (str, optional):
            Match-ID of one of the matches. Defaults to `'J03WPY'`. See below
            for available matches.
        event_types:
        coordinates:
        event_factory:

    Notes:
        The dataset contains seven full matches of raw event and position data
        for both teams and the ball from the German Men's Bundesliga season
        2022/23 first and second division. A detailed description of the
        dataset as well as the collection process can be found in the
        accompanying paper.

        The following matches are available::

        matches = {
            'J03WMX': 1. FC Köln vs. FC Bayern München,
            'J03WN1': VfL Bochum 1848 vs. Bayer 04 Leverkusen,
            'J03WPY': Fortuna Düsseldorf vs. 1. FC Nürnberg,
            'J03WOH': Fortuna Düsseldorf vs. SSV Jahn Regensburg,
            'J03WQQ': Fortuna Düsseldorf vs. FC St. Pauli,
            'J03WOY': Fortuna Düsseldorf vs. F.C. Hansa Rostock,
            'J03WR9': Fortuna Düsseldorf vs. 1. FC Kaiserslautern
        }

    References:
        .. [1] Bassek, M., Rein, R., Weber, H. et al. "An integrated dataset of
               spatiotemporal and event data in elite soccer." Sci Data 12, 195 (2025).
               https://doi.org/10.1038/s41597-025-04505-y
    """
    return load_event(
        event_data=get_IDSSE_url(match_id, "event"),
        meta_data=get_IDSSE_url(match_id, "meta"),
        event_types=event_types,
        coordinates=coordinates,
        event_factory=event_factory,
    )

load_open_tracking_data 

1
2
3
4
5
6
7
load_open_tracking_data(
    match_id="J03WPY",
    sample_rate=None,
    limit=None,
    coordinates=None,
    only_alive=True,
)

Load tracking data for a game from the IDSSE dataset.

The IDSSE dataset will be released with the publication of the An integrated dataset of synchronized spatiotemporal and event data in elite soccer paper [1]_ and is released under the Creative Commons Attribution 4.0 license.

PARAMETER DESCRIPTION
match_id

Match-ID of one of the matches. Defaults to 'J03WPY'. See below for available matches.

TYPE: str DEFAULT: 'J03WPY'

sample_rate

TYPE: Optional[float] DEFAULT: None

limit

TYPE: Optional[int] DEFAULT: None

coordinates

TYPE: Optional[str] DEFAULT: None

only_alive

TYPE: Optional[bool] DEFAULT: True

Notes

The dataset contains seven full matches of raw event and position data for both teams and the ball from the German Men's Bundesliga season 2022/23 first and second division. A detailed description of the dataset as well as the collection process can be found in the accompanying paper.

The following matches are available::

matches = { 'J03WMX': 1. FC Köln vs. FC Bayern München, 'J03WN1': VfL Bochum 1848 vs. Bayer 04 Leverkusen, 'J03WPY': Fortuna Düsseldorf vs. 1. FC Nürnberg, 'J03WOH': Fortuna Düsseldorf vs. SSV Jahn Regensburg, 'J03WQQ': Fortuna Düsseldorf vs. FC St. Pauli, 'J03WOY': Fortuna Düsseldorf vs. F.C. Hansa Rostock, 'J03WR9': Fortuna Düsseldorf vs. 1. FC Kaiserslautern }

References

.. [1] Bassek, M., Weber, H., Rein, R., & Memmert, D. (2024). "An integrated dataset of synchronized spatiotemporal and event data in elite soccer." In Submission.

Source code in kloppy/_providers/sportec.py 
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
def load_open_tracking_data(
    match_id: str = "J03WPY",
    sample_rate: Optional[float] = None,
    limit: Optional[int] = None,
    coordinates: Optional[str] = None,
    only_alive: Optional[bool] = True,
) -> TrackingDataset:
    """
    Load tracking data for a game from the IDSSE dataset.

    The IDSSE dataset will be released with the publication of the *An integrated
    dataset of synchronized spatiotemporal and event data in elite soccer*
    paper [1]_ and is released under the Creative Commons Attribution 4.0
    license.

    Args:
        match_id (str, optional):
            Match-ID of one of the matches. Defaults to `'J03WPY'`. See below
            for available matches.
        sample_rate:
        limit:
        coordinates:
        only_alive:

    Notes:
        The dataset contains seven full matches of raw event and position data
        for both teams and the ball from the German Men's Bundesliga season
        2022/23 first and second division. A detailed description of the
        dataset as well as the collection process can be found in the
        accompanying paper.

        The following matches are available::

        matches = {
            'J03WMX': 1. FC Köln vs. FC Bayern München,
            'J03WN1': VfL Bochum 1848 vs. Bayer 04 Leverkusen,
            'J03WPY': Fortuna Düsseldorf vs. 1. FC Nürnberg,
            'J03WOH': Fortuna Düsseldorf vs. SSV Jahn Regensburg,
            'J03WQQ': Fortuna Düsseldorf vs. FC St. Pauli,
            'J03WOY': Fortuna Düsseldorf vs. F.C. Hansa Rostock,
            'J03WR9': Fortuna Düsseldorf vs. 1. FC Kaiserslautern
        }

    References:
        .. [1] Bassek, M., Weber, H., Rein, R., & Memmert, D. (2024). "An integrated
               dataset of synchronized spatiotemporal and event data in elite soccer."
               In Submission.
    """
    return load_tracking(
        raw_data=get_IDSSE_url(match_id, "tracking"),
        meta_data=get_IDSSE_url(match_id, "meta"),
        sample_rate=sample_rate,
        limit=limit,
        coordinates=coordinates,
        only_alive=only_alive,
    )