Parses the Sportradar timeline files in json format and extracts the event data.

This function provides access to Sport Event Timeline files from the data provider Sportradar exported in json format and returns Event objects for all teams and segments of the game.


filepath_events (str or pathlib.Path) – Full path to json file where the Sport Event Timeline is saved.


data_objects – Nested dictionary with Events objects for all teams and segments. The returned dictionary contains one dictionary per segment, which in return contain one Events object per team. For a usual league match with two halves and two teams this dictionary looks like: {"HT1": {"Home": Events, "Away": Events}, "HT2": {Home: Events, Away: Events}}

Return type

Dict[str: Dict[str: Events]]


Sportradar provides different information depending on the respective Event type. This parser itemizes top-level information for each possible event type listed in the Handball v2 documentation FAQ (most recent check: 11.01.2023).

For example, this involves individual columns for the home and away score parsed event type score_change. However, individual columns for players involved in Events, like seven_m_awarded or shots are not fully itemized, as they can contain different information depending on the situation. More complex information that changes per event type is instead included as dict or list of dicts in according column, so they can be accessed if necessary.

In the return, the following columns contain temporal information about the event: ("gameclock", "time_stamp", "minutes_gross", "seconds_gross", "minutes", "seconds" ). In handball, the match-clock determines the net playing time (60 minutes) and diverges from the gross “real world” time passed. The “gameclock” column contains the gross time passed in seconds in relation to the start of the respective segment. The “minute_gross” and “second_gross” columns contain the “gameclock” converted to minutes and seconds, respectively. The columns “minutes” and “seconds” contain the information about the net match-clock. the column “time_stamp” contains the global time-stamp of the respective event in the ISO 8601 standard format.

The column “outcome” in the return contains the “outcome” information in the raw event data and not information about the success {0, 1} of an event. The outcome in terms of success can be inferred by the eID. E.g. “score_change” implies that a shot lead to a goal, “shot_saved” implies that a goal was not scored.