Skip to main content
The Game Data API is in preview. Endpoints, fields and limits may change before release, and it is not yet available to call.
The Game Data API returns what Uplift produces from match video: events, phases of play and possessions, physical summaries per player, and tracking for every player and the ball. It uses the same base URL, API keys, errors and conventions as the rest of the Uplift API.

How it is organized

The API has two tiers:
  • Per game. Each endpoint returns a whole game in one response: every event, every segment, or every player’s physical summary. Optional filters narrow the result. Tracking is returned one period at a time.
  • Across games. List Player Stats aggregates physical and event totals per player, grouped by game or season.
To add a game, create the game, then create a clip and upload the video. When processing finishes, the game’s data is available from the per-game endpoints.

Key concepts

  • Game: a match between two teams, with date, competition, pitch size, frame rate (fps), roster and each team’s attacking direction per period. Each team has a stable team_id and a team_side of home or away.
  • Clip: a video uploaded to a game. A game can be one full-match video or several clips.
  • Run: one processing pass over a game’s clips. Every response includes the run_id it came from. Re-processing a game creates a new run and replaces the game’s data.
  • Event: a moment in the game, such as a pass, a high-speed run or a duel. See the event catalogue.
  • Segment: a span of time, such as a phase of play, a team possession, a player possession or a key moment. Every event falls inside a phase of play and, when the ball is involved, a team possession and a player possession.
  • Player: player_id identifies a roster entry in one game. It can be empty, or a placeholder such as track_12, when a player isn’t identified. When it is linked to an Uplift athlete, athlete_id is included, so game data and capture data can be joined.

Conventions

  • Coordinates: pitch metres with the origin at the centre spot, x along the length and y across; z is height for the ball. Event coordinates are turned so that the event’s team attacks towards positive x; attacking_side says which way that team was attacking on the pitch. Tracking stays on the fixed pitch, with each team’s attacking direction per period on the game.
  • Time: period is 1 or 2 for halves, 3 or 4 for extra time and 5 for a penalty shootout; a single clip is period 1. time_s is seconds from the start of the period; frame is the video frame.
  • Frame rate: data is at the game’s frame rate, given in fps on the game.
  • Naming: every field, parameter and value is snake_case.
  • Paging: per-game endpoints return the whole game. List endpoints use limit and offset: List Games returns up to 500 rows per page, List Player Stats up to 5,000.
  • Quality: every event and segment has a confidence from 0 to 1, a confidence_tier (high, medium or low), and the layer it needs: position (player positions only), ball (the ball as well) or skeleton (3D body pose).
  • Formats: responses are JSON. Tracking is a zstd-compressed Parquet file.

Webhooks

Game data uses the existing webhooks:
  • game.processing_completed: a run finished, the first time or after re-processing. The payload includes game_id and run_id.
  • game.processing_failed: processing failed, with an error summary.