databallpy

KO | EN

gitlite — search

#php #python #java #javascript #shell #html #jquery #linux #nodejs #r #ruby #actionscript

★ 97 Open GitHub ↗

Package to read, preprocess, vizualise, and synchronise soccer event and tracking data.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[version-image]: https://img.shields.io/pypi/v/databallpy?color=006666
[version-url]: https://pypi.org/project/databallpy/
[python-image]: https://img.shields.io/pypi/pyversions/databallpy?color=006666
[python-url]: https://pypi.org/project/databallpy/
[docs-image]: https://readthedocs.org/projects/databallpy/badge/?version=main
[docs-url]: https://databallpy.readthedocs.io/en/main/?badge=main
[cicd-image]: https://github.com/Alek050/databallpy/actions/workflows/linters_and_tests.yml/badge.svg
[cicd-url]: https://github.com/Alek050/databallpy/actions/workflows/linters_and_tests.yml
[codecov-image]: https://codecov.io/gh/Alek050/databallpy/branch/develop/graph/badge.svg?token=MBI3380I0H
[codecov-url]: https://codecov.io/gh/Alek050/databallpy

[filter-data-url]: https://databallpy.readthedocs.io/en/main/getting_started/preprocessing_options.html#filtering-data
[velocity-acc-url]: https://databallpy.readthedocs.io/en/main/getting_started/preprocessing_options.html#adding-velocity-and-acceleration
[synchronisation-url]: https://databallpy.readthedocs.io/en/main/getting_started/synchronisation_page.html
[covered-distance-url]: https://databallpy.readthedocs.io/en/main/features/covered_distance_page.html
[pressure-url]: https://databallpy.readthedocs.io/en/main/features/pressure_page.html
[team-possession-url]: https://databallpy.readthedocs.io/en/main/features/team_and_player_possession.html#team-possession
[individual_possession-url]: https://databallpy.readthedocs.io/en/main/features/team_and_player_possession.html#individual-player-possession-vidal-codina-et-al-2022
[Expected-Goals-url]: https://databallpy.readthedocs.io/en/main/features/simple_xG_models.html
[Expected-Threat-url]: https://databallpy.readthedocs.io/en/main/features/xT_models.html
[Voronoi-url]: https://databallpy.readthedocs.io/en/main/features/space_occupation.html#voronoi-model
[Guassian-space-occupation-url]: https://databallpy.readthedocs.io/en/main/features/space_occupation.html#gaussian-model-fernandez-born-2018
[dangerous-accessible-space-url]: https://databallpy.readthedocs.io/en/main/features/dangerous_accessible_space.html
[visualizations-url]: https://databallpy.readthedocs.io/en/main/getting_started/visualizations_page.html
[optimization-url]: https://databallpy.readthedocs.io/en/main/features/optimization.html

[floodlight-url]:https://github.com/floodlight-sports/floodlight
[kloppy-url]:https://github.com/PySport/kloppy
[soccer-sync-url]: https://kwiatkowski.io/sync.soccer
[example-url]: https://databallpy.readthedocs.io/en/main/example.html
[getting-started-url]: https://databallpy.readthedocs.io/en/main/getting_started/installation_page.html

[joss-image]: https://joss.theoj.org/papers/10.21105/joss.10223/status.svg
[joss-url]: https://doi.org/10.21105/joss.10223

[![Latest Version][version-image]][version-url]
[![Python Version][python-image]][python-url]
[![Documentation Status][docs-image]][docs-url]
[![CI/CD Status][cicd-image]][cicd-url]
[![Codecov][codecov-image]][codecov-url]
[![PyPI Downloads](https://static.pepy.tech/badge/databallpy)](https://pepy.tech/projects/databallpy)
[![DOI][joss-image]][joss-url]

# DataBallPy

A package for loading, synchronizing, and analyzing your soccer event- and tracking data.

This package is developed to create a standardized way to analyse soccer games using both event- and tracking data. Other packages, like [kloppy][kloppy-url] and [floodlight][floodlight-url], already standardize the import of data sources. The current package goes a step further in combining different data streams from the same game. In this case, the `Game` object combines information from the event and tracking data. The main current feature is the smart synchronization of the tracking and event data. We utilize the Needleman-Wunch algorithm, inspired by [this article][soccer-sync-url], to align the tracking and even data, while ensuring the order of the events, something that is not done when only using (different) cost functions.

## Final goal for DataBallPy

Although reading in and synchronising data is already very helpfull to get started with your analysis, it's only the first step. Even after this first step, getting your first 'simple' metrics out of the data might be more difficult than anticipated. Therefore, the primary end goal for this package is to create a space where (scientific) soccer metrics are implemented and can be used in a few lines. We even plan to go further and show clear notebooks (to combine text and code) with visualizations for all the features we implement. This way, you will not only get easy access to the features/metrics, but also understand exactly how it is calculated. We hope this will inspire others (both developers and scientist) to further improve the current features, and come up with valuable new ones. If you are interested in some of the features we implemented, see our [official documentation][docs-url].

## Changelog V0.7.3 (14/04/2026)

- New parser for Fifa event data ([ouyang1030](https://github.com/ouyang1030))
- Added API docs for TrackingData and different data parsers
- Added support for python 3.14
- Removed `bs4` as dependency
- Added functionality to export events to XML for video analysis purposes
- Fixed bug in donwload open data from IDSSE dataset
- Integration between Kloppy and Databallpy ([UnravelSports](https://github.com/UnravelSports) & [migvidal5](https://github.com/migvidal5))
- Allow for more null values in `Game`
- Loser rules regarding tz aware datetime columns in `TrackingData` and `EventData`
- Removed depricated functions `home_players_column_ids` and `away_players_column_ids`, please use `game.get_column_ids(team="home")` instead.

## Installation
Choose either of both commands. If you would like to use Kloppy as data parser, use the second one, else the first one would do.

```bash
$ pip install databallpy
$ pip install 'databallpy[kloppy]'
```

## Usage

The package is centered around the `Game` object. A `Game` has tracking data, event data metadata about the game.
For a more elaborate example, see the [Getting Started][getting-started-url].

```python
from databallpy import get_game, get_open_game

game = get_game(
  tracking_data_loc="../data/tracking_data.dat",
  tracking_metadata_loc="../data/tracking_metadata.xml",
  tracking_data_provider="tracab",
  event_data_loc="../data/event_data_f24.xml",
  event_metadata_loc="../data/event_metadata_f7.xml",
  event_data_provider="opta",
)

# or get the open game provided by the DFL (Sportec Solutions)
game = get_open_game()
```

> [!note]
> The current internal supported tracking data providers are:
> - Tracab (including Sportec Solutions from the DFL)
> - Metrica
> - Inmotio
> 
> The accepted variables for the `tracking_data_provider` are `["tracab", "metrica", "inmotio", "dfl", "sportec"]`
> 
> The current internal supported event data provider are:
> - Opta (also accepts `"statsperform"`, since StatsPerform acquired Opta - both values behave identically, and Opta's newer MA2/MA13 files are auto-detected alongside the legacy F7/F24 files)
> - Metrica
> - Instat
> - SciSports
> - Sportec Solutions (from the DFL)
> - Statsbomb
> - Fifa
> 
> The accepted variables for the `event_data_provider` are `["opta", "statsperform", "metrica", "instat", "scisports", "dfl", "sportec", "statsbomb","fifa"]`
>
> If you wish to use a different provider that is not listed here, please open an issue [here](https://github.com/Alek050/databallpy/issues)

### Open Data
A great project just released tracking and event data for open use. In total, 2 games of the 1st bundesliga and 5 of the 2nd bundesliga were open sourced [here](https://www.nature.com/articles/s41597-025-04505-y). The dataset was open sources via the CC-BY 4.0 licence, so please consider this when you make use of the data. The data is automatically downloaded and saved locally when you use the `get_open_game` function from DataBallPy. The match information can be imported from `databallpy.utils.constants.OPEN_GAME_IDS_DFL`:

```python
OPEN_GAME_IDS_DFL = {
    "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",
}
```

See [the documentation][docs-url] of the `Game` object and the [example usage][example-url] for more options. Note that this package is developed to combine event and tracking data, for now both datastreams are necessary to create a `Game` object.

## Features

### Preprocessing

- [Data Filtering][filter-data-url]: Filter the data based on the quality of the tracking data.
- [Adding velocity and Acceleration][velocity-acc-url]: Add velocity and acceleration to the tracking data.

### Synchronization of tracking and event data

See our elaborate [synchronisation page][synchronisation-url] in the documentation for more information!

Tracking and event data is often poorly synchronized. For instance, when taking the event data of Opta and tracking data of Tracab, you can sync the fist frame with the kick-off pass. Now you can sync the other events with the tracking data based on the time difference between the event and the kick off pass. If you do this, how get something like this:

<video width="640" height="480" controls>
  <source src="https://raw.githubusercontent.com/Alek050/databallpy/main/docs/example_data/not_synced.mp4" type="video/mp4">
  Your browser does not support the video tag.
</video>

https://user-images.githubusercontent.com/49450063/224564808-fa71735f-5510-464d-8499-9044227a02e8.mp4

As you can see, the timing (and placing) of the events do not correspond good with the tracking data locations, especially when events follow up quickly or around shots. Using the methodology of [this][soccer-sync-url] article, this package is able to synchronize tracking and event data using the Needleman-Wunsch algorithm.

After running the following command, the events are better synchronized to the tracking data:

```batch
$ game.synchronise_tracking_and_event_data()
```

<video width="640" height="480" controls>
  <source src="https://raw.githubusercontent.com/Alek050/databallpy/main/docs/example_data/synced.mp4" type="video/mp4">
  Your browser does not support the video tag.
</video>

https://user-images.githubusercontent.com/49450063/224564913-4091faf7-f6ef-4429-b132-7f93ce5e1d91.mp4

For a more elaborate example of how we synchronize the tracking and event data, see the [Synchronisation Page][getting-started-url] in our [documentation][docs-url].

### Visualizations

DataBallPy offers a variety of visualizations to help you understand the data better. For example, you can visualize the tracking data with synchronised event as shown above. Also, you can visualize events and tracking data separately. For more information, see the [Visualizations Page][visualizations-url] in our [documentation][docs-url].

### Soccer Specific Metrics

- [Covered Distance][covered-distance-url]: Calculate the covered distance in different velocity and acceleration zones.
- [Pressure][pressure-url]: Calculate the pressure any player in the game (Herold & Kempe, 2022).
- [Team Possession][team-possession-url]: Calculate the team possession based on the synchronised event data.
- [Individual Player Possession][individual_possession-url]: Calculate the individual player possession based on the tracking data (Vidal-Codina et al., 2022).
- [Simple Expected Goals (xG) model][Expected-Goals-url]: Calculate the simple expected goals model.
- [Expected Threat model][Expected-Threat-url]: Calculate the expected threat model from Karun Singh to on ball events.
- [Voronoi Model][Voronoi-url]: Calculate the Voronoi space occupation based on the tracking data.
- [Gaussian Model][Guassian-space-occupation-url]: Calculate the Gaussian space occupation based on the tracking data (Fernandez & Born, 2018).
- [Dangerous Accessible Space][dangerous-accessible-space-url]: Compute Dangerous accessible space (Bischofberger & Baca, 2025)
- [Defensive Structure Optimization][optimization-url]: Optimize defensive positioning based on different objective functions.

## Documentation

The official documentation can be found [here][docs-url].

## Providers

Inherintly supported providers.

Event data providers:
- Opta
- Metrica
- Instat
- SciSports
- Sportec Solutions (for the DFL)
- FIFA

Tracking data providers:
- Tracab (including Sportec Solutions format from the DFL)
- Metrica
- Inmotio

Check the [integration between Kloppy and Databallpy](https://databallpy.readthedocs.io/en/main/getting_started/loading_in_a_game_page.html#databallpy-kloppy-integration) to parse any kloppy supported data provider into a DataBallPy `Game` object.

## Seek Support
To reach out to developers, maintainers, and the community in general, you can reply to and open new discussions in the [discussions field](https://github.com/Alek050/databallpy/discussions) of `databallpy`.

## Citing

If you have used DataBallPy in you work, please consider citing the [corresponding papaer](https://joss.theoj.org/papers/10.21105/joss.10223).

```
@article{Oonk2026,
   author = {Gerard Alexander Oonk and Daan Grob and Matthias Kempe},
   doi = {10.21105/JOSS.10223},
   issn = {2475-9066},
   issue = {120},
   journal = {Journal of Open Source Software},
   month = {4},
   pages = {10223},
   title = {DataBallPy: Load, Synchronize, and Analyse your Soccer Data},
   volume = {11},
   url = {https://joss.theoj.org/papers/10.21105/joss.10223},
   year = {2026}
}
```

## Contributing

Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.

## Maintainers & owners

- [Alek050](https://github.com/Alek050/)

## Contributors

- [DaanGro](https://github.com/DaanGro/)
- [rdghe](https://github.com/rdghe/)
- [swopper050](https://github.com/Swopper050)
- [maritsloots](https://github.com/maritsloots)
- [jan-swiatek](https://github.com/jan-swiatek)
- [UnravelSports](https://github.com/UnravelSports) 
- [migvidal5](https://github.com/migvidal5)
- [jonas-bischofberger](https://github.com/jonas-bischofberger)
- [jiangyan yang](https://github.com/ouyang1030)
- [amarshah1999](https://github.com/amarshah1999)

## License

`databallpy` was created by Alexander Oonk & Daan Grob. It is licensed under the terms of the MIT license.

## Similar projects

Although we think this package helps when starting to analyse soccer data, other packages may be better suited for your specific needs. Make sure to check out the following packages as well:
- [kloppy][kloppy-url]
- [floodlight][floodlight-url]
- [codeball](https://github.com/metrica-sports/codeball)
- [socceraction](https://github.com/ML-KULeuven/socceraction)

And for a more specific toturials on how to get started with soccer data"
- [Friends of Tracking](https://github.com/Friends-of-Tracking-Data-FoTD)

databallpy

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README