GPS Support: Data Model, Standardization & Open Data Sources

[koenvo]

GPS Support: Data Model, Standardization & Open Data Sources

Hi all,

I wanted to open a conversation around GPS support in Kloppy. As more users work with wearable tracking data (PlayerData, Catapult, STATSports, etc.), it feels like a good time to explore what GPS support in Kloppy could look like — and what would be needed to get there.

This issue is a place to discuss and brainstorm. Nothing is set in stone — just starting the conversation.

---

🧱 Data model

Currently, Kloppy assumes a match-based structure (with Team, Periods, etc. see Metadata), which makes sense for optical tracking. But GPS data often comes from training sessions with different structures — like multiple drills or free-form running.

• Do we need to introduce new concepts like Session and Drill?
• Can these live alongside Periods in the same core model?
• What should the shared/common data structure be?

---

🧭 Standardization

GPS data is often in lat/lon — which is tricky to work with for analysis. Ideally, we could:

• Convert lat/lon to pitch coordinates (if pitch dimensions and orientation are known, including the four corners in lat/lon)
• Apply standard smoothing techniques to reduce noise
• Support different sampling rates and interpolation strategies

Would love to hear thoughts on how best to handle coordinate normalization and smoothing in a consistent way.

---

🌍 Open data & ingestion

To experiment, we’ll need access to GPS data from different providers.

• Are there any open datasets available (even small ones)?
• What formats are typically used — CSV, JSON, FIT files?
• Can Ingestify play a role in fetching/standardizing the raw data?

Would love to hear from anyone who has worked with real GPS data, or who knows where to find it.

[UnravelSports]

Thanks for this issue @koenvo!

Here are some of my thoughts:

Data Model

For the data model to be changed we need to come up with some common vocabulary. I think Session and Drill (as a subset of session) seems to make a lot of sense, but maybe others have other experiences.

In that sense it could be an idea to make a match a type of session where each period of play represents a drill. The downside to this is that, from my understanding, GPS data does not contain all that much information. This would mean the metadata for GPS for example would become rather sparse.

It could also make sense to simply split it up, this would create no breaking changes, simply because the overlap is "minimal" because of the sparsity of the GPS meta data.

---

Standardization

I think the standardization efforts (for now) should focus on including lat/lon and potential conversions, and we should exclude Inertial measurement units (IMU's) and Heart rate monitors.

Lat / Lon

For converting lat/lon to pitch coordinates normally (again, from my understanding) operators of the GPS units take measurements (either via Google Maps, or otherwise) of the 4 corners of a pitch and use those as reference coordinates. With a set of these reference coordinates it should be relatively simple convert lat/lon to local x/y.

Orientation is harder though, because it's not recorded in the metadata what "direction of play" would be with GPS data, nor is it relevant most of the time.

Smoothing

As far as smoothing goes, there is an open PR #298 by @probberechts for this. It might also make sense to use floodlight (@manuba95) for some of these applications instead, to avoid kloppy being a one-stop-shop instead of a data parser / deserializer.

Sampling rates

I agree that this is important. We currently support sample rate, but no upsampling but @probberechts raises some concerns on those here #401.

---

Datasets / Providers

We can only pull this off of we have raw data from multiple providers available that comes in it's "rawest" form, similar to how we do with tracking data. Below I've compiled a non-exhaustive list of GPS providers that we can try to source data from, one way, or another.

• PlayerData
• STATSports
• Catapult
• Wimu
• Kinexon
• Fitogether
• Inmotio
• Johan Sports

---

Implementation Ideas

Reference Coordinates

One option would be to provide a list of 4 reference coordinates

from kloppy import gps_provider_xyz

dataset = gps_provider_xyz.load_tracking(
    raw_data=["player_a.json", "player_b.json"]
    meta_data="meta.json",
    # optional
    reference_coordinates=[
        (50.735792, -1.83860),
        (50.735416, -1.839118),
        (50.73467,  -1.838207),
        (50.7346726, -1.8382075)   
    ]
)

Additionally we could allow users the option to set some global reference coordinates that we default to inside set_config. We might need to check if when a conversion happens from lat/lon to x/y if it makes sense given the default coordinates.

Intervals

Another option could be to use the dataset.aggregate() functionality to compute intervals on pre-set intervals. For example:

set_config("intervals": {
      "walking": [0, 7.0],
      "jogging": [7.0, 14.3],
      "running": [14.3, 19.7],
      "high_intensity": [19.7, 25.1],
      "sprinting": [25.1, 30.0],
      "max_sprinting": [30.0, float('inf')]
})

dataset.aggregate("intervals_bins")
dataset.aggregate("intervals_minutes")

Lat/Lon to X/Y

It might make sense to have the PlayerData object hold either Point and/or GPSPoint data, and have the GPSPoint data have a method to convert each individual point to a regular Point.

[elliotgPD]

Very interesting topic, @koenvo!

I’m the Data & R&D Manager at PlayerData, and standardising data output is something we’re always working towards. I am interested by your thoughts and as someone working in this field I feel I can share some insight on it.

🧱 Data Model

At PlayerData, we use a Session → Segment → Segment Part model. This allows us to break down both training and match sessions into manageable chunks, making aggregation and investigation more flexible.

A Session is typically a block of (date)time scheduled for continuous athlete activity. For soccer, a session could be training, or a match. Sessions have some additional metadata, like a description string, and tags. We also compute athlete and session average metrics for the entire session duration. Sessions may contain multiple segments.

A Segment is a particular duration of concern during a session. Not all athletes have to participate in a Segment. Athletes may leave and join segments as they please. A segment typically represents a drill during a training session, or a match period. Segments have a title. Segments can optionally have a set of pitch coordinates. We also compute athlete and segment average metrics for a segment. Segment metrics are an aggregation of Segment Part Metrics.

Segment Parts are a unit of continuous segment participation. A segment part starts the instant an athlete joins a segment, and ends the instant an athlete next leaves a segment. Since athletes can leave and join segments as they please, an athlete may have multiple segment parts per segment. For example a substitution during the first half of a soccer match would count as a Segment Part.

The Metadata input should reflect the above and give more information:

Session you should include at minimum the:

• start_time
• end_time
• pitch_coordinates (if required)
• session_participations (which athletes have participated in that session).

Segment you should include at minimum the:

• segment_title,
• start_time,
• end_time,
• segment_participations (which athletes have participated in that segment).

Segment part you should include at minimum the:

• start_time,
• end_time.

All this information is vital in allowing you to distinguish between different segments such as the 1st Half/2nd Half and Warm Ups/Top Ups as they have different physical/tactical implications.

Pitch Coordinates using latitude/longitude coordinates (Top Left, Top Right, Bottom Right, Bottom Left) would be very useful for visualisation and clipping of data. It could also be used so the pitch direction for each half can be easily determined by the user as these coordinates can be fetched via satellite maps e.g(google maps) and the top and bottom of the pitch can be chosen.

Other metadata may include tags, description which could be used at both the Session and Segment level to give more information for further aggregation and averaging.

🧭 Standardisation

We would recommend converting Lat/Lon to UTM coordinates, which makes spatial analysis easier by converting degrees into metres. A great open-source tool for this is: Turbo87/utm, which handles conversions both ways with ease. It is also useful as data is not always within a pitch -> Training Sessions.

Once converted to UTM, pitch coordinates can be consistently visualised. To handle orientation, you could simply flip the direction after each break in play to maintain consistent visuals.

For sampling and smoothing, it’s important to monitor GPS health metrics such as HACC or simply Satellite Count, which help in filtering out unreliable data.

🌍 Open Data & Ingestion

The best format we’ve seen across providers are CSV files: with columns for time, latitude, longitude, speed, and GPS health.

There are other file formats that could be used but I believe this is the widest used format which is a key part of standardisation.

Standardising data ingestion is something the entire GPS community would benefit from, I’m excited to keep this conversation going!

[UnravelSports]

Hi, @elliotgPD thanks for the great insights! I have a bunch of questions:

1. Is this solution how you would standardize GPS data more generally, or is this the data approach that PlayerData uses for their own data processing? (i.e., do other providers use a similar approach (Session -> Segment -> Segment Part), or at least, is the approach by other providers such that it can be generalized with the same granularity (e.g. Session > SubSession > SubSubSession)?
2. You mention "Segment Title" and "Tags" I presume these are added prior to loading / standardizing by the practitioner and are provided in a meta data file?
3. Speaking of files, how is this data generally delivered? For example what is the file type (json, csv, xml etc.), is it 1 file per player per session, 1 file per session with all players, does it even come with a separate meta data file or is this information inside the player, session file(s)? Again, is this different for other providers?
4. Is HACC and/or Satellite Count an industry standard for recording GPS accuracy?
5. Is HACC / Satellite Count recorded per measurement (i.e. per lat / lon pair?)
6. Is a "Segment Part" strictly a subset of one overarching "Segment"?

And for @koenvo and @probberechts

1. Should UTM conversion be optional, and/or part of the Transformer? To me, it feels like the latter. (aka, record Lat/lon, have end-user transfor to local coordinates, UTM or what have you).

---

GPS > Kloppy | TrackingDataset > Frame

Below I will try to draw some parallels with the Kloppy code base to hopefully spark discussion on how to proceed, this is just a bit of a ramble about how things could work, and some other things I noticed.

In Kloppy, for optical tracking data, we generate a TrackingDataset that consists of records (List[Frame]) and metadata for a game (or a subset of a game, i.e. when we specify a limit to the number or rows we want, or set the sample_rate).

From a bit of an informal discussion with @koenvo and @probberechts it seems like it would be preferred if we could use this framework to incorporate GPS data too, but only if the breaking changes are minimal / non existent. Otherwise we might need to create a separate GPS format (that should follow the same approach still).

Eitherway, a Frame in Kloppy looks like this:

@dataclass
class Frame(DataRecord):
    frame_id: int
    players_data: Dict[Player, PlayerData]
    other_data: Dict[str, Any]
    ball_coordinates: Point3D
    ball_speed: Optional[float] = None

where the DataRecord looks like this:

@dataclass
class DataRecord(ABC):
    dataset: "Dataset" = field(init=False)
    prev_record: Optional["DataRecord"] = field(init=False)
    next_record: Optional["DataRecord"] = field(init=False)
    period: Period
    timestamp: timedelta
    statistics: List[Statistic]
    ball_owning_team: Optional[Team]
    ball_state: Optional[BallState]

And PlayerData looks like this:

@dataclass
class PlayerData:
    coordinates: Point
    distance: Optional[float] = None
    speed: Optional[float] = None
    other_data: Dict[str, Any] = field(default_factory=dict)

As we can see there is a lot of irrelevant information (as it pertains to GPS data, e.g. statistics, ball_owning_team and ball_state) in here, but some things to note:

• Each Frame holds the set of coordinates for every player at a certain moment in time (i.e. same frame_id and same timestamp). This might not make sense for GPS if each GPS Unit records data points asynchronously from the rest. For example each unit might record at 25FPS, but they could be recording at a 2 millisecond offset. This might mean "Frames" don't exist in the GPS world.
• Each Frame contains the Period related to that moment in time (e.g. the first half Period object). This could be done similarly for GPS where each lat / lon has a "segment" and a sub-segment ("segment part" / "drill") associated with it.
• The coordinates in PlayerData are a regular Point which is simply a collection of x and y in local space. These x/y values can than be transformed using the DatasetTransformer into any other local space (custom) coordinate system. We could approach this similarly for GPS but with lat / lon.
• Transformations to UMT (or local space, given pitch GPS coordinates) could be done after loading with the DatasetTransformer.

---

GPS > Kloppy | TrackingDataset > Metadata

Within Kloppy the Metadata looks as follows:

@dataclass
class Metadata:
    teams: List[Team]
    periods: List[Period]
    pitch_dimensions: PitchDimensions
    orientation: Orientation
    flags: DatasetFlag
    provider: Provider
    coordinate_system: CoordinateSystem
    score: Optional[Score] = None
    frame_rate: Optional[float] = None
    date: Optional[datetime] = None
    game_week: Optional[str] = None
    game_id: Optional[str] = None
    home_coach: Optional[str] = None
    away_coach: Optional[str] = None
    officials: Optional[List] = field(default_factory=list)
    attributes: Optional[Dict] = field(default_factory=dict, compare=False)

Again, there are a number of things that are not or less relevant to GPS data (e.g. teams as a list of home and away team, score, game_week, coaches, officials etc.). The more interesting things here are:

• teams could be singular (or more than 2) and could contain information on the Session Participants. Each Team currently has (amongst other, less relevant stuff) a list of Player objects.
• I'm not 100% sure Segment Participants would be relevant, as those could be parsed from each Segment ("Period"), but it might be worth while to consider listing all relevant players for a Period (or Segment) in this class too.
• periods as a list of all Period objects could have a similar implementation for Segment where each Segment can hold multiple SubSegment / Drill / SegmentPart objects.
• PitchDimensions would only be relevant if the user provides some sort of reference_coordinates as mentioned in my first message.
• Orientation would be difficult to set directly from the data, no? This might need to be a parameter in the load functionality where for each Segment the user could specify direction of play? This might be tedious for the user though. I don't see how else to obtain this information correctly just from the data.
• Stuff like game_week and / or game_id could be generalized to session_id and name or session_title.
• Each "Segment" (Period-like) object could also hold a "segment_title" / "name" and "tags" parameter.

[manuba95]

Hi guys, thanks for opening the discussion on this topic!
I'd like to add some thoughts based on my experience with LPS and GPS data, and with floodlight. I think many important points have already been raised, and @elliotgPD made some excellent suggestions, so I’ll just add a few more.

Please note that this is based on my experience with two data providers (Catapult for GPS and Kinexon for LPS), so technical details may differ for other systems.

Differences between GPS & LPS

Although this may not affect the final data object, I think it's worth highlighting that GPS (or GNSS, to be precise—but I won't use that here) and LPS are quite different in terms of data collection and analysis.

Collection:
GPS relies on connections to multiple satellites and triangulates sensor positions via time-of-flight/time-difference-of-arrival calculations. This data is continuously available, so GPS sensors can (and do) collect data independently in lat/lon coordinates. However, satellite dependence means variable data quality, no indoor usability, and limited temporal and spatial resolution.

LPS systems replace the satellite network with local anchors around the pitch. These are calibrated with precise relative positions, allowing for more accurate triangulation. The sampling rate is also typically higher (e.g., 10 Hz for GPS vs. 20–50 Hz for LPS). Within LPS, a local reference coordinate system is usually defined during calibration, and coordinates are provided in this reference system.

Analysis:
Due to these technical differences, the raw data output also varies. GPS data typically comes as one file per sensor, with limited metadata like the sensor ID and recording start time (i.e., when the sensor is removed from its box), along with IMU (if available) and GPS data. The challenge is that sensors aren't always taken out or returned at the same time, so synchronization is needed from the earliest start to the latest stop. As @UnravelSports already mentioned, this can introduce slight frame offsets. I’ve personally dealt with this by rounding timestamps to the nearest decimal—since a few milliseconds’ difference is negligible compared to the overall system noise.

In contrast, LPS sessions are started as a unified system, so one file includes all timestamps, sensor identifiers, and respective coordinates. This doesn’t mean that all sensors are constantly tracked (they can be temporarily deactivated), but at least they follow a more "consistent" stream of data points.

In some respects, I find LPS data more comparable to official match tracking data in soccer than to GPS data. The main differences lie in user flexibility and somewhat limited metadata. For instance, information about player identities, exact pitch dimensions, or coordinate system origin may exist in system settings but is often not exported with the raw data.

Data Model

I think using a flexible framework is best here, though I don't have a strong opinion on specific semantics. In floodlight, we can divide data (e.g., by first and second half), but it's not a requirement.

Standardisation (of GPS)

Lat/lon
I fully recommend using the utm package to convert lat/lon coordinates into x/y. Briefly explained: UTM divides the globe into rectangular zones where Earth’s curvature can be ignored. Zones are identified by numbers and letters (e.g., the Netherlands use 31N and 32N). Cartesian coordinates are then used within each zone. I’m personally still hoping to find a pitch that lies exactly on the border of two zones!

Handling raw data really depends on the use case. For example, calculating distances covered does not require a reference coordinate pitch, but calculating space control does. So having the option to input coordinates from a reference system, and the ability to translate and rotate them into place, is very useful.

Smoothing
These are very relevant points concerning GPS data quality. Unfortunately, as Ellens, S. et al. (2022). Techniques to derive and clean acceleration and deceleration data of athlete tracking technologies in team sports: A scoping review. Journal of Sports Sciences, 40(16), 1772–1800. point out, sports science currently lacks a gold (or even bronze) standard for processing raw tracking data. Within floodlight, we offer low-pass filters to smooth data as the user sees fit, and we aim to integrate up/down-sampling and interpolation in future versions.
Overall, I think understanding these nuances should help aligning the data structure and processing with the respective requirements and use case. Looking forward to further discussion!

[MatKempeGroningen]

Hi all @UnravelSports invited me this issue. We been working on setting up preprocessing for GPS data for tactcial analysis for a while. It is far from perfect but we adress some of the issues raised in this thread. For example we pride the reliabilty of getting "anchors" for pitch coordinates via extra gps devices vs. via Google maps with the Google Maps option providing better results.
All the code can be found in https://github.com/latilongitude/GNSS_FootballTactical
by @latilongitude (Guangze Zhang).

The acompining paper with a detailed description is under review right now and I am happy to share it at a later stage. The respository also include a data set (Catapult) that are open to use.

[UnravelSports]

Thanks for sharing @MatKempeGroningen! Do you know if any of these 3 files represent the "raw" data you'd pull from their API directly? Or have they been modified?

[latilongitude]

Thanks @MatKempeGroningen for mentioning the repository.

Thanks @UnravelSports for your question. To preserve anonymity, the positional data and pitch location have been modified without affecting the demonstration purpose. Since we have received a few suggestions on the codes last week, the code package is currently being refined. The updated version is expected to be available by the end of next week. DM if you have any questions. Happy to discuss more!

[UnravelSports]

I've been trying this GPS integration (skipping LPS for now) out over the past couple of days and I'm having a couple issues that need to be resolved. Let me start off by explaining a bit of what I have done so far, and then I'll explicitly state the bottleneck(s) I'm running into when trying to fit GPS data into the Kloppy mold.

I started by drawing up a top-down re-design starting with the Dataset and DatasetType classes, DataRecord and Metadata classes and finally Frame and PlayerData classes. At some point after that I figured I should simply start with building a implementation, because I was never going to find all the bottle necks, working my way back up to see what I would encounter.

I will start with the (minor) redesigns I did, with the comment that any changes I've made I'm showing here are from the GPS perspective, the Tracking implementation has not changed in function.

---

Re-Design Kloppy Backend

Metadata

GPS and Tracking data have a couple of things in common, but they both have their own unique requirements.

I split Metadata into MatchMetadata and GPSMetadata where the latter two now inherit the common bits from the Metadata class.

Note: I have not yet done anything with the CoordinateSystem, PitchDimensions or Orientation they are currently not set for GPS. The idea is to ultimately set these using reference_coordinates, but I'll get to that.

Metadata

@dataclass
class Metadata:
    teams: list[Team]
    coordinate_system: CoordinateSystem
    pitch_dimensions: PitchDimensions
    orientation: Orientation
    flags: DatasetFlag
    provider: Provider
    frame_rate: float | None = None

    def __post_init__(self):
        if self.coordinate_system is not None:
            # set the pitch dimensions from the coordinate system
            self.pitch_dimensions = self.coordinate_system.pitch_dimensions 

GPSMetadata

@dataclass
class GPSMetaData(Metadata):
    segments: list[TimeSegment] = field(default_factory=list)
    reference_coordinates: list[GPSPoint] = field(default_factory=list)

    def __post_init__(self):
        super().__post_init__()

        for i, segment in enumerate(self.segments):
            segment.set_refs(
                prev=self.segments[i - 1] if i > 0 else None,
                next_=(
                    self.segments[i + 1] if i + 1 < len(self.segments) else None
                ),
            )

        if (
            self.reference_coordinates is not None
            and len(self.reference_coordinates) != 4
        ):
            raise ValueError("There must be exactly 4 reference coordinates.")

The most important thing in GPSMetadata is the use of segments. These segments are similar to periods, but Period is now a special case of TimeSegment (name is up for debate). Basically, we need a way to capture information on things that are not strictly periods, but that do segment GPS sessions by time. For this, we allow id to additionally be a string, because each segment should have a unique identifier coming from the data. Additionally each segment will be named (manually) by the practitioner (e.g., "drill 1", "gk drill" etc.) so we add name. We need this id later to determine which player was in which segment.

Small teaser, these segments are going to get annoying...

@dataclass
class TimeSegment:
    id: int | str
    start_timestamp: Union[datetime, timedelta]
    end_timestamp: Optional[Union[datetime, timedelta]]
    name: Optional[str] = None

    _prev_segment: Optional["TimeSegment"] = field(init=False, repr=False, default=None)
    _next_segment: Optional["TimeSegment"] = field(init=False, repr=False, default=None)
    .... 

@dataclass
class Period(TimeSegment):
    def __post_init__(self):
        if not isinstance(self.id, int):
            raise ValueError("Period id must be an integer")
        return super().__post_init__()

    @property
    def prev_period(self) -> "Period":
        return self._prev_segment

    @property
    def next_period(self) -> "Period":
        return self._next_segment

---

PlayerData (not to be confused with the company)

Frame records frame_id and players_data most importantly (for GPS). To accommodate the lack of ball_coordinates this has been set to Optional inside Frame.

Additionally, PlayerData now allows coordinates to be Point or GPSPoint as shown below.

@dataclass
class PlayerData:
    coordinates: Point | GPSPoint
    distance: Optional[float] = None
    speed: Optional[float] = None
    other_data: dict[str, Any] = field(default_factory=dict)

GPSPoint
We add a distance_to method to keep the Point functionality similar as Point also has such a method.

@dataclass(frozen=True)
class GPSPoint:
    lat: float
    lon: float

    def distance_to(self, other: "GPSPoint") -> float:
        # Calculates the great-circle distance between two GPS points using the Haversine formula.
        ....
        return distance

---

DataRecord

Frame inherits from DataRecord. This in itself is not really a problem, because statistics, ball_owning_team and ball_state can simply be ignored.

The main problem with DataRecord arises from the period attribute. As mentioned above, GPS has no periods, but rather segments. There are two ways I can see to resolve this:

1. Add segments: list[TimeSegment] | None = None to DataRecord and ensure that either period or segments is set, never both and never neither.
2. Split into MatchDataRecord and GPSDataRecord, but this feels a lot less nice.

---

GPS Implementation

Before I get into this implementation it's good to know that I'm currently using PlayerData to build this. PlayerData has a GraphQL API, so you can basically construct the output to be whatever you want. That is, there is no strict single endpoint to grab a single structured file, as we are accustomed to with tracking or event data. This will probably mean we will have to be more precise on throwing warnings / exceptions for missing keys, and informing the user in the docs what kloppy expects as inputs.

File Structures

Session Files / Data Recordings
The load function is designed like Hawkeye's, because we will have 1 file per "data recording". Each data recording json is for a single player, in a single session. It has an array of json objects like so:

[{
        "time": 1751342342299,
        "type": "GPS",
        "fix": "THREE_D_FIX",
        "satellites": 23,
        "latitude": ...,
        "longitude": ...,
        "speed": ...
    },...]

This means, no playerIds or other information, as a result the user will have to store the file as "{dataRecording.id}".json, otherwise we can't know which file belongs to which player. Again, this is similar to HawkEye where the file names are ordered by minute and labeled as such in the file names. It's not perfect, but that's what we have to deal with.

Meta Data / Session Data
Then we have a meta data file, or rather a session_data file to make it more explicit. Due to the GraphQL API, we have to ensure this file contains a:

• A "session" key that holds a dict which contains "club" and "id" variables.
• A "segments" key (a list of dicts) that contain at least the keys 'id', 'title', 'startTime' and 'endTime'.
• A "sessionParticipants" key (a list of dicts) that contains "athlete" and "dataRecordings" objects. Where "dataRecordings" is a list with 1 dict that has atleast an "id", but always with a single object (this is just how it is), and "athlete" should have "id" and "name".

We use this "dataRecordings" object and it's "id" to refer back to the file names, to figure out which player belongs to which file or vice versa.

Because I don't exactly know how everyone will structure this JSON file, I'm using PR#485 to dynamically search for them.

playerdata.load now looks as follows:

from kloppy import playerdata

dataset = playerdata.load(
    player_feeds="data/playerdata/full_session/sessions/",
    session_data="data/playerdata/full_session/session_complete.json"
)

GPSDataDeserializer

We create a GPSDataDeserializer similar to TrackingDataDeserializer but with support for reference_coordinates and the need for an updated transformer_builder (not yet implemented).

class GPSDataDeserializer(ABC, Generic[T]):
    def __init__(
        self,
        limit: Optional[int] = None,
        sample_rate: Optional[float] = None,
        only_alive: Optional[bool] = True,
        reference_coordinates: Optional[list[float]] = None,
    ):
    ...

Within deserialize we first extract all relevant meta data as described above. Then we loop over every individual object in the files to extract "time", "latitude", "longitude" and "speed". As suggested by @manuba95 we round each timestamp to the nearest "frame" (i.e., we interpret frame_rate and then round the timestamps). We don't lose much of anything when rounding these timestamps, but it allows us to then store the PlayerData objects (with lat, lon etc.) in a dict where they keys are the timestamps (appending if more PlayerData objects exist for a single timestamp).

By doing this we can then sort these dict keys (timestamps) and loop over every set of PlayerData objects for that timestamp to create a Frame object. For each frame. We do this to stay within the bounds of the TrackingDataset-type functionality.

So, we have to make 2 passes over the data, first to combine individual lat / lon in such a way that they are aligned by timestamp, and then to create an ordered list of Frames. One frame per timestamp.

---

Misc

Some other things I included:

• Create a DatasetFlag.BALL_DATA to indicate if we have ball data in our GPSDataset and/or TrackingDataset. This flag will make sure we do not include columns "ball_{xyz}" when calling to_df().
• Added Ground.NOT_SET because we don't know this / it's not relevant for GPS data.
• only_alive would only include Frames / PlayerData for players active in a session / drill. This is more complex than it seems, see below.
• Added DatasetType.GPS
• Dataset._initialize_player_positions and Dataset._update_formations_and_positions only triggers when self.metadata is of type MatchMetadata (basically skipping for GPS).

TODO's

• Proper PitchDimensions, Orientation and CoordinateSystem stuff including transformations as shown by @latilongitude here.
• GPSDataset.to_tracking_dataset conversion. Requires reference_coordinates and the operations from the previous point.

---

Bottlenecks / Discussion

This is the point where I'm currently at and I want to now open this up for discussion, both to discuss to above and to address some bottlenecks for which we need to make a decision.

Multiple Sessions

Currently, my biggest concern is that within the GPS data a single PlayerData object (i.e., lat/lon/speed) can belong to multiple Sessions. For example a player at timestamp t might be registered as part of "Drill A" and "Entire Session". These two would be two distinct TimeSegment objects, and for usability they should be recorded as such.

Additionally, each Frame now does not have a single period but instead it can also have multiple segments because we can have 23 players at the same time in practice (so same timestamp), but goalkeepers might be doing "GK Drill A", 5 players might be doing "Rondo" and another 16 players might be doing "8v8". These would all be recorded in a single Frame object, where each PlayerData object has all the relevant segments per player, but the overall frame maybe should also have this data as a replacement for period. Additionally, these different drills can end at various different times creating some complex overlaps.

We could squeeze this into Frame.other_data and PlayerData.other_data but it seems to be too vital to dump it there.

Finally, when thinking about this from a DataFrame perspective, our current "wide" format has 1 column for period_id, but now we might need to have a way of indicating which player is participating in which drill / session / segment (and it can be multiple at the same time).

This might be a little easier in the "long" format PR#475, but it might still require n columns if 1 player is in multiple drills at the same time.

File Structure Discussion

As you've seen it's rather complex to implement this, not only because of the slightly different nature of the data, but also because the file structures are completely different to what we're used to. I would love to hear thoughts on what I've done so far, and potential ways to make this better from Kloppy's perspective.

TimeSegment

Curious to hear thoughts on TimeSegment (and segments (list) as a companion to period) as it's the main reason this whole integration is getting complicated.

---

@koenvo @probberechts @elliotgPD @manuba95 @MatKempeGroningen @latilongitude I would love to hear your thoughts on this.

[probberechts]

Maybe you can think a bit more out-of-the-box. To me, the segments seem very similar to a CodeDataset. They are essentially labels for certain periods of the session. Is it really necessary to store everything in a single dataset? Maybe you can split it up?

[UnravelSports]

I have never used the CodeDataset, so no idea how they behave. Not sure what it would entail to store it in multiple datasets, or how you envision that. Do you have any examples? Do you mean one dataset per segment?

[probberechts]

Essentially, this would be similar to using a TrackingDataset in combination with an EventDataset or CodeDataset. The TrackingDataset contains the locations of players and the CodeDataset provides additional labels.

This is what a CodeDataset for GPS data would look like:

from kloppy.domain import (
    CodeDataset,
    Code,
    Metadata,
    Period,
    Provider,
    DatasetType,
    Team,
)
from datetime import datetime

# --- 1. Define Basic Metadata ---
prematch = Period(id=1, start_timestamp=datetime(1993, 7, 30, 14, 0, 0), end_timestamp=datetime(1993, 7, 30, 14, 50, 0))

# GPS data usually belongs to one "Team" (the squad training).
squad = Team(team_id="squad_A", name="First Team", ground=None)

metadata = Metadata(
    teams=[squad],
    periods=[prematch],
    coordinate_system=None,
    pitch_dimensions=None,  # Not strictly needed for drill codes
    orientation=None,
    provider=None,
    flags=None,
)

# --- 2. Define the Drills (The Codes) ---
# A 'Code' in Kloppy represents an event or annotation.
# Structure: Period, Timestamp (start), End Timestamp, Label (code), and any extra attributes.

drill_definitions = [
    # (Period Object, Start Time, End Time, Drill Name)
    (prematch, 60.0, 600.0, "Warm Up"),
    (prematch, 660.0, 1200.0, "Rondo 5v2"),
    (prematch, 1300.0, 2400.0, "Tactical Shape"),
    (prematch, 2800.0, 3400.0, "Small Sided Game"),
    (prematch, 3500.0, 3800.0, "Sprints"),
]

codes = []
for idx, (p, start, end, name) in enumerate(drill_definitions):
    # Create the Code object
    drill_code = Code(
        code_id=idx,
        period=p,
        timestamp=start,
        end_timestamp=end,
        code=name,  # The main identifier (Drill Name)
        # You can store extra arbitrary data in labels if needed
        labels={"intensity": "High" if "Sprints" in name else "Low"} ,
        statistics=None,
        ball_owning_team=None,
        ball_state=None,
    )
    codes.append(drill_code)

# --- 3. Instantiate the CodeDataset ---
drill_dataset = CodeDataset(
    metadata=metadata,
    records=codes
)

print(f"Successfully created CodeDataset with {len(dataset.records)} drills.")

# Convert to Pandas to view the table
df = drill_dataset.to_df()

print("\n--- GPS Drill Annotations ---")
print(df[['period_id', 'timestamp', 'end_timestamp', 'code', 'intensity']])

# Example: Calculate duration for each drill
df['duration_min'] = (df['end_timestamp'] - df['timestamp']) / 60

print("\n--- Drill Durations ---")
print(df[['code', 'duration_min']])

[UnravelSports]

Okay, this sorta makes sense, I can see how this would be a great addition to the GPSDataset (or a different approach). Two questions:

1. Can the drills overlap in time?
2. How do we relate drills to players (or players to drills)?

[probberechts]

1. Can the drills overlap in time?

Sure. There are essentially no constraints on codes.

3. How do we relate drills to players (or players to drills)?

By adding a label. See https://kloppy.pysport.org/user-guide/concepts/code-data/ for an example.

[UnravelSports]

Okay, thanks for pointing me in this direction!

How do you see the "TrackingDataset" and "CodeDataset" parts of this be combined? Should the Deserializer return two objects (TrackingDataset and CodeDataset)? Should the GPSDataset contain a tracking and code dataset and a single MetaData object?